DB Checker Utility

User's Guide

Version 2016 (11.0)

April 2016

DSPI2-PE-200004C
Copyright
Copyright © 2002-2016 Intergraph® Corporation. All Rights Reserved. Intergraph is part of Hexagon.
Including software, file formats, and audiovisual displays; may be used pursuant to applicable software license agreement; contains
confidential and proprietary information of Intergraph and/or third parties which is protected by copyright law, trade secret law, and
international treaty, and may not be provided or otherwise made available without proper authorization from Intergraph Corporation.

U.S. Government Restricted Rights Legend

Use, duplication, or disclosure by the government is subject to restrictions as set forth below. For civilian agencies: This was
developed at private expense and is "restricted computer software" submitted with restricted rights in accordance with
subparagraphs (a) through (d) of the Commercial Computer Software - Restricted Rights clause at 52.227-19 of the Federal
Acquisition Regulations ("FAR") and its successors, and is unpublished and all rights are reserved under the copyright laws of the
United States. For units of the Department of Defense ("DoD"): This is "commercial computer software" as defined at DFARS
252.227-7014 and the rights of the Government are as specified at DFARS 227.7202-3.
Unpublished - rights reserved under the copyright laws of the United States.
Intergraph Corporation
305 Intergraph Way
Madison, AL 35758

Documentation
Documentation shall mean, whether in electronic or printed form, User's Guides, Installation Guides, Reference Guides,
Administrator's Guides, Customization Guides, Programmer's Guides, Configuration Guides and Help Guides delivered with a
particular software product.

Other Documentation
Other Documentation shall mean, whether in electronic or printed form and delivered with software or on Intergraph Smart Support,
SharePoint, or box.net, any documentation related to work processes, workflows, and best practices that is provided by Intergraph
as guidance for using a software product.

Terms of Use
a. Use of a software product and Documentation is subject to the End User License Agreement ("EULA") delivered with the
software product unless the Licensee has a valid signed license for this software product with Intergraph Corporation. If the
Licensee has a valid signed license for this software product with Intergraph Corporation, the valid signed license shall take
precedence and govern the use of this software product and Documentation. Subject to the terms contained within the
applicable license agreement, Intergraph Corporation gives Licensee permission to print a reasonable number of copies of the
Documentation as defined in the applicable license agreement and delivered with the software product for Licensee's internal,
non-commercial use. The Documentation may not be printed for resale or redistribution.
b. For use of Documentation or Other Documentation where end user does not receive a EULA or does not have a valid license
agreement with Intergraph, Intergraph grants the Licensee a non-exclusive license to use the Documentation or Other
Documentation for Licensee’s internal non-commercial use. Intergraph Corporation gives Licensee permission to print a
reasonable number of copies of Other Documentation for Licensee’s internal, non-commercial use. The Other Documentation
may not be printed for resale or redistribution. This license contained in this subsection b) may be terminated at any time and
for any reason by Intergraph Corporation by giving written notice to Licensee.

Disclaimer of Warranties
Except for any express warranties as may be stated in the EULA or separate license or separate terms and conditions, Intergraph
Corporation disclaims any and all express or implied warranties including, but not limited to the implied warranties of merchantability
and fitness for a particular purpose and nothing stated in, or implied by, this document or its contents shall be considered or deemed
a modification or amendment of such disclaimer. Intergraph believes the information in this publication is accurate as of its
publication date.
The information and the software discussed in this document are subject to change without notice and are subject to applicable
technical product descriptions. Intergraph Corporation is not responsible for any error that may appear in this document.
The software, Documentation and Other Documentation discussed in this document are furnished under a license and may be used
or copied only in accordance with the terms of this license. THE USER OF THE SOFTWARE IS EXPECTED TO MAKE THE FINAL
EVALUATION AS TO THE USEFULNESS OF THE SOFTWARE IN HIS OWN ENVIRONMENT.

DB Checker Utility User's Guide 2

Intergraph is not responsible for the accuracy of delivered data including, but not limited to, catalog, reference and symbol data.
Users should verify for themselves that the data is accurate and suitable for their project work.

Limitation of Damages
IN NO EVENT WILL INTERGRAPH CORPORATION BE LIABLE FOR ANY DIRECT, INDIRECT, CONSEQUENTIAL INCIDENTAL,
SPECIAL, OR PUNITIVE DAMAGES, INCLUDING BUT NOT LIMITED TO, LOSS OF USE OR PRODUCTION, LOSS OF
REVENUE OR PROFIT, LOSS OF DATA, OR CLAIMS OF THIRD PARTIES, EVEN IF INTERGRAPH CORPORATION HAS BEEN
ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
UNDER NO CIRCUMSTANCES SHALL INTERGRAPH CORPORATION’S LIABILITY EXCEED THE AMOUNT THAT
INTERGRAPH CORPORATION HAS BEEN PAID BY LICENSEE UNDER THIS AGREEMENT AT THE TIME THE CLAIM IS
MADE. EXCEPT WHERE PROHIBITED BY APPLICABLE LAW, NO CLAIM, REGARDLESS OF FORM, ARISING OUT OF OR IN
CONNECTION WITH THE SUBJECT MATTER OF THIS DOCUMENT MAY BE BROUGHT BY LICENSEE MORE THAN TWO (2)
YEARS AFTER THE EVENT GIVING RISE TO THE CAUSE OF ACTION HAS OCCURRED.
IF UNDER THE LAW RULED APPLICABLE ANY PART OF THIS SECTION IS INVALID, THEN INTERGRAPH LIMITS ITS
LIABILITY TO THE MAXIMUM EXTENT ALLOWED BY SAID LAW.

Export Controls
Intergraph Corporation’s software products and any third-party Software Products obtained from Intergraph Corporation, its
subsidiaries, or distributors (including any Documentation, Other Documentation or technical data related to these products) are
subject to the export control laws and regulations of the United States. Diversion contrary to U.S. law is prohibited. These Software
Products, and the direct product thereof, must not be exported or re-exported, directly or indirectly (including via remote access)
under the following circumstances:
a. To Cuba, Iran, North Korea, Sudan, or Syria, or any national of these countries.
b. To any person or entity listed on any U.S. government denial list, including but not limited to, the U.S. Department of Commerce
Denied Persons, Entities, and Unverified Lists, http://www.bis.doc.gov/complianceandenforcement/liststocheck.htm, the U.S.
Department of Treasury Specially Designated Nationals List, http://www.treas.gov/offices/enforcement/ofac/, and the U.S.
Department of State Debarred List, http://www.pmddtc.state.gov/compliance/debar.html.
c. To any entity when Licensee knows, or has reason to know, the end use of the Software Product is related to the design,
development, production, or use of missiles, chemical, biological, or nuclear weapons, or other un-safeguarded or sensitive
nuclear uses.
d. To any entity when Licensee knows, or has reason to know, that an illegal reshipment will take place.
Any questions regarding export or re-export of these Software Products should be addressed to Intergraph Corporation’s Export
Compliance Department, Huntsville, Alabama 35894, USA.

Trademarks
Intergraph, the Intergraph logo, Intergraph Smart, PDS, SmartPlant, SmartMarine, FrameWorks, I-Sketch, IntelliShip, ISOGEN,
Sapphire, SmartSketch, SPOOLGEN, SupportManager, and SupportModeler are trademarks or registered trademarks of Intergraph
Corporation or its subsidiaries in the United States and other countries. Microsoft and Windows are registered trademarks of
Microsoft Corporation. MicroStation is a registered trademark of Bentley Systems, Inc. Other brands and product names are
trademarks of their respective owners.

DB Checker Utility User's Guide 3

Contents
DBChecker Utility ........................................................................................................................................ 5
Log File Descriptions .............................................................................................................................. 7
Start the DBChecker Utility ..................................................................................................................... 8
Check the Database ............................................................................................................................... 8
Create a User Log File Without Implementing the Fixes ........................................................................ 9
Implement Fix Suggestions ..................................................................................................................... 9
Exit the DBChecker Utility ..................................................................................................................... 10

Windows and Dialog Boxes...................................................................................................................... 11

DBChecker Utility Window .................................................................................................................... 11
Check Results Dialog Box .................................................................................................................... 12
Summary Dialog Box ............................................................................................................................ 12

DB Checker Utility User's Guide 4

SECTION 1

DBChecker Utility
The DBChecker Utility is used for maintenance and troubleshooting of the SmartPlant
Instrumentation database. The utility allows you to inspect and maintain data integrity, and to
troubleshoot and resolve various database problems. It is also used to fix inconsistencies that
can occur if enhanced data integrity rules or changes in the data model are applied to legacy
data before and after an upgrade. For example, legacy data may have an allowed NULL value
in a specific database column but an application improvement requires the column value to be
NOT NULL. The DBChecker Utility allows you to detect and fix this type of data integrity
problem. Ongoing improvements are made in the DBChecker Utility itself, just like the
enhancements and improvements in SmartPlant Instrumentation, and the DBChecker Utility of a
later version of SmartPlant Instrumentation can find data legacy problems that were not exposed
in previous versions.
In some cases, mass data transformation operations in SmartPlant Instrumentation require
extensive changes that bypass the business object processing. This is usually done in order to
significantly improve the performance of such data transformation operations, for example, when
running the Merger or Import utilities. Such operations involve record manipulation directly in
the database, rather than through the business objects wrapper and, therefore, might cause
data integrity problems. The DBChecker Utility allows you to troubleshoot these problems and
fix them on the fly.
Additionally, there are operations, carried out via the program interface, that are extremely
sensitive to the integrity and synchronization of the manipulated data. The DBChecker Utility
assists in preventing failure during such operations.
The DBChecker Utility enables you to predict or fix problems in your database by running
specific SQL commands without having to contact Intergraph Support. You can either fix the
problems on the fly or create a file that contains suggestions for fixing the selected
problems. The DBChecker Utility displays defective rows and problem descriptions so that you
can open SmartPlant Instrumentation and check the issues that the DBChecker Utility found. In
addition, the DBChecker Utility allows you to select fixes that you want to implement.
When you start the DBChecker Utility, the software automatically connects to the Admin schema
of the user database defined in the INTOOLS.INI file. Then, you can select a target domain and
perform a database check for that domain. You can only perform a database check at the
domain level. If the domain type is Owner operator, As-Built and all existing projects are
included in a single database check.
When running the DBChecker Utility, if you suspect that execution of certain SQL
commands can damage valuable data, we recommend that you back up your database before
implementing fixes. This is because in certain cases, the SQL commands delete data based on
the known format of the SmartPlant Instrumentation data model and data. In most cases, the
changes are irreversible. If your database contains data that does not comply with the
SmartPlant Instrumentation data model, some changes may lead to unexpected results. The
DBChecker Utility scripts are tested by our certification team, but the tester or script designer
might not be aware of all possible data set combinations that are likely to cause database
problems.

DB Checker Utility User's Guide 5

 DBChecker Utility

You can check the structures and definitions of your database objects to identify invalid or
missing objects or data inconsistencies. Where problems occur, the DBChecker Utility can also
fix them. The software performs the check by automatically comparing the database objects
with the SmartPlant Instrumentation template database. After checking, the utility generates an
error report and prompts you to correct the errors.
After completion of the database check, the results are stored in the complog.txt file, whose
default location is the SmartPlant Instrumentation home folder. You can specify another
location as you require.
The DBChecker Utility is used by the SmartPlant Instrumentation certification
and development teams in the course of certifying a version release.

Activities that Require a Database Check

 A major upgrade of the SmartPlant Instrumentation database — Run the DBChecker Utility
before and after the upgrade process to minimize the number of upgrade stops and
problems during the process, and to minimize downtime.
 Initializing a new domain using another domain as a source — Run the DBChecker Utility for
the source domain, before starting the initialization process.
 Copying data from one lowest plant hierarchy item to another — Run the DBChecker Utility
before performing the activity.
 Merging a large project with As-Built — Run the DBChecker Utility before performing the
activity.
 Running the Merger Utility — Run the DBChecker Utility before and after performing the
activity.
 Massive data import, especially in the Table mode — Run the DBChecker Utility before and
after performing the activity.

Possible DBChecker Utility Use Scenarios

 Intergraph Support requests the DBChecker Utility to be used at customer's site, and the
details to be sent to Intergraph Support for faster troubleshooting when database integrity
can be a factor in the problem reported by the customer.
 A customer decides to run the DBChecker Utility if SmartPlant Instrumentation users report
problems that are hard to reproduce, and the SmartPlant Instrumentation System
Administrator suspects there is a problem with the database integrity.

DBChecker Utility Use Frequency Factors

It is possible to use The DBChecker Utility on a periodic basis to find problems in their early
stages, before they manifest themselves in application malfunctions. Factors to be considered
in the frequency of using the utility as a maintenance data validation tool are as follows:
 The origin of the database — If the database was created mostly by importing data from
external files, via a data migration process, or in the early versions of SmartPlant
Instrumentation, the use frequency should be increased.
 The nature of operations — If the current database undergoes massive data transformation,
frequent or massive claim or merge operations in an Owner operator domain, or numerous
import activities, the use frequency should be increased.

DB Checker Utility User's Guide 6

 DBChecker Utility

 The history of previous use of the DBChecker Utility and results — If the DBChecker Utility
sessions do not indicate any issues with the database, the use frequency should be
decreased.
 Consistency of the version — Remaining on the same version of SmartPlant Instrumentation
for a prolonged period of time should decrease the need for running the DBChecker Utility
and, therefore, the use frequency should be decreased.
Before you run the DBChecker Utility, you can set the software to check all or only certain
database objects. For details, see the Help topic DBChecker Utility Window (on page 11).

See Also
Check Results Dialog Box (on page 12)
Create a User Log File Without Implementing the Fixes (on page 9)

Log File Descriptions

The DBChecker utility generates and executes SQL commands for database verification. This
verification procedure generates a result log file complog.txt and a suggested corrective action
list in the log files recreate.txt and recreate_user.txt.
complog.txt — Contains all database problems the DBChecker Utility has found during a
database check. The software creates this file on completion of a database check. When
detecting a data integrity problem, the DBChecker Utility writes to the complog.txt file the SQL
command or commands that have identified the problem. The complog.txt file can also
include the Special Operations section that contains the SQL commands that identified the
problem, but for which there is no pre-defined automatic solution. Usually, the issues identified
in the Special Operations section are related to the engineering data inconsistencies that need
to be resolved through the user operations in SmartPlant Instrumentation itself. If no problems
are found, the file only contains the time of the session, the database platform information, and
the database name. If you run another database check, the software overwrites the records
that appear in the file.
recreate.txt — Contains all fix suggestions for the database problems found during a database
check. The fix suggestions are represented as SQL commands. The software creates this file
on completion of a database check. If the software does not find any problems in the database,
the recreate.txt file only contains the time of the session and the database platform
information. If you run another database check, the software overwrites the records that appear
in the file.
recreate_user.txt — Contains selected specific fix suggestions for the problems that you select
in the Check Results dialog box. The fix suggestions are represented as SQL
commands. The Check Results dialog box only opens if the software finds a database
problem. The software creates this file after you click Fix or Create Log in the Check Results
dialog box. If you click Fix to fix the database problems on the fly, some of the fixes that you
selected might not be implemented successfully. The software records information of such fixes
in the recreate_user.txt file. If you previously created the recreate_user.txt file, the software
appends new log data to the existing data. The records in the log file are separated by date and
time of log data creation. You can clear the log file manually.

DB Checker Utility User's Guide 7

 DBChecker Utility

See Also
The DBChecker Utility (see "DBChecker Utility" on page 5)
Check the Database (on page 8)
Create a User Log File Without Implementing the Fixes (on page 9)

Start the DBChecker Utility

 Do one of the following:

 In the SmartPlant Instrumentation home folder, double-click checkdb.exe.

 At the command line, type checkdb.exe, and then click OK.

Check the Database

It is recommended that only trained users with advanced knowledge of SmartPlant
Instrumentation and administration options should use the utility. If such knowledge is lacking, it
is recommended to use Intergraph Support assistance when using the utility for the first time.
1. In the DBChecker Utility window.
2. Click Connect to connect to the Admin schema of your SmartPlant Instrumentation
database.
3. From the Domain box, select a target domain.
4. Under Output data file path, do one of the following:
 Accept the default path where the software creates the log files on completion of the
database check. The default location is the SmartPlant Instrumentation home folder.
 Click Browse to specify another path.
If you previously ran the DBChecker Utility, the software has already created the log
files. Specifying a different path prevents you from overwriting existing data in the files
complog.txt and recreate.txt.
5. Under Check tables and related items, select Tables, and then select a combination of
the check boxes.
If you want to check reference data, you must select the Initial records check
box. Initial records are rows in which all fields of primary keys are zeros. When checking
reference data, the software checks existence of required rows in pertinent tables.
6. If needed, under Check other database items, depending on your database platform, do
one of the following:
 On Oracle, select Invalid objects and/or Disabled foreign keys.
 On SQL Server, select Disabled foreign keys.
7. Click Run to start the database check.

 On completion of the database check, the software creates the files complog.txt and
recreate.txt. If database problems are found, the software opens the Check Results
dialog box, where you can analyze the problems and fix suggestions, and select all or
specific problems which you want to fix on the fly or at a later stage. If you choose to

DB Checker Utility User's Guide 8

 DBChecker Utility

repair the database yourself, it is recommended that you run the DBChecker Utility once
more to verify that all the problems have been fixed.
 If the DBChecker Utility generates corrective statements identical to the ones
successfully used before to resolve the problem the user can execute them at their own
discretion. When contacting Intergraph Support, make sure you forward to Intergraph
Support the three log files generated by the DBChecker Utility and await instructions on
how to execute them.

Create a User Log File Without Implementing the

Fixes
1. In the Check Results dialog box, for the problems for which you want to record fix
suggestions in a log file, select the check boxes under the Include in Fix column.
The Check Results dialog box only opens if the DBChecker Utility finds a problem
during a database check.
2. Click Create Log.
The software creates the recreate_user.txt file in the location you specified in the
DBChecker Utility window. The default location is the SmartPlant Instrumentation home
folder. If you previously created the recreate_user.txt file, the software appends new log
data to the existing data. The records in the log file are separated by date and time of log
data creation. You can clear the log file manually.

Implement Fix Suggestions

1. In the Check Results dialog box, for the problems for which you want to implement fix
suggestions, select the check boxes under the Include in Fix column.
The Check Results dialog box only opens if the DBChecker Utility finds a problem
during a database check.
2. Click Fix.
It is highly recommended that you back up your database before implementing the
fixes because in certain cases, the SQL commands delete data based on the known format of
the SmartPlant Instrumentation data model and data content. In most cases, the changes are
irreversible. If your database contains data that does not comply with the SmartPlant
Instrumentation data model, some changes may lead to unexpected results.
See Also
DBChecker Utility (on page 5)
Create a User Log File Without Implementing the Fixes (on page 9)
Check Results Dialog Box (on page 12)

DB Checker Utility User's Guide 9

 DBChecker Utility

Exit the DBChecker Utility

 In the DBChecker Utility window, click Close.
On completion of a database check, if the software has found a database problem, the
Check Results dialog box opens, where you can either implement problem fixes on the fly, or
create a log file and then send the log file to Intergraph Support. Clicking Close in the Check
Results dialog box closes the DBChecker Utility. Therefore, make sure you perform the
operation that you require before clicking Close in the Check Results dialog box.

DB Checker Utility User's Guide 10

SECTION 2

Windows and Dialog Boxes

In This Section
DBChecker Utility Window ............................................................. 11
Check Results Dialog Box ............................................................. 12
Summary Dialog Box ..................................................................... 12

DBChecker Utility Window

The DBChecker Utility allows you to select all or specific database items and run a database
check for a SmartPlant Instrumentation domain.
Domain — Allows you to select a target domain in your database after you click Connect.
Connect — Connects to the Admin schema of the database.
Output data file path — Allows you to specify a path where the software creates the log files
that contain information about the database problems and problem fix suggestions. For the log
file details, see Log File Descriptions (on page 7). The default location of the log files is the
SmartPlant Instrumentation home folder.

Check tables and related items

Tables — Allows you to check the database tables. Selecting this check box enables you to
select other check boxes.
Primary keys — Allows you to check the primary keys.
Foreign keys — Allows you to check the foreign keys.
Stored procedures — Allows you to check stored procedures.
Triggers — Allows you to check triggers.
Indexes — Allows you to check indexes.
Initial records — Allows you to check rows in which all fields of primary keys are
zeros. Selecting this check box enables you to include reference data in the database check.
Reference data — Allows you to check existence of required rows in pertinent tables.
Check other database items
Invalid objects — Allows you to check invalid objects in Oracle.
Disabled foreign keys — Allows you to check disabled foreign keys in Oracle or SQL Server.
Run — Starts checking the database.

DB Checker Utility User's Guide 11

 Windows and Dialog Boxes

Check Results Dialog Box

Displays problems found in the database and allows you either to fix the problems on the fly, or
record the fix suggestions in a log file without implementing the fixes. If you choose to create a
log file, you can implement the fixes manually later, or send the log file to Intergraph Support.
Include in Fix — Enables the software to implement the fix for the problem that was
found. The software implements the fix after you click Fix. If you choose not to implement the
fixes on the fly, you can click Create Log and record the fix suggestions in the recreate_user.txt
file.
Summary — Opens a dialog box that shows the problem description, the SQL command that
found the problem, and the SQL command that can fix the problem.
Details — Opens a dialog box that shows details of the affected rows. This dialog box can
show specific settings that the software considers problematic. Where possible, the software
displays the name of the problematic item, in other cases, the item ID in the database.
Select all — Selects all the check boxes in the Include in Fix column.
Fix — Implements the fixes for the problems for which you selected the Include in Fix check
box.
Create Log — Creates the recreate_user.txt file in the location you specified in the
DBChecker Utility window. The default location is the SmartPlant Instrumentation home
folder. If you previously created the recreate_user.txt file, the software appends new log data
to the existing data. The records in the log file are separated by date and time of log data
creation. You can clear the log file manually.
Close — Closes the DBChecker Utility.
See Also
Create a User Log File Without Implementing the Fixes (on page 9)

Summary Dialog Box

Displays a summary of SQL commands that relate to the problem that the DBChecker Utility
found. This summary includes the SQL command that found the problem, the SQL command
that can fix the problem, and the detailed description of the problem. You can display a
summary for each record that appears in the Problem Description column of the Check
Results dialog box.
Problem description — Displays a meaningful description of the problem that was found in the
database.
SQL that found the problem — Displays the SQL command that found the problem. The
same SQL command appears automatically in the complog.txt file, on completion of the current
database check. This SQL command shows records that do not comply with SmartPlant
Instrumentation database constraints.
SQL that can fix the problem — Displays the SQL command that can fix the problem when
you click Fix in the Check Results dialog box.
See Also
Check Results Dialog Box (on page 12)

DB Checker Utility User's Guide 12