DB Checker Utility

User's Guide

Version 2013

March 2013

DSPI2-PE-200004B
Copyright
Copyright © 2002-2013 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
P.O. Box 240000
Huntsville, AL 35813
Terms of Use
Use of this software product is subject to the End User License Agreement ("EULA") delivered with this 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. 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.
Warranties and Liabilities
All warranties given by Intergraph Corporation about equipment or software are set forth in the EULA provided with the software
or applicable license for the software product signed by Intergraph Corporation, and nothing stated in, or implied by, this
document or its contents shall be considered or deemed a modification or amendment of such warranties. 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 discussed in this document is furnished under a license and may be used or copied only in accordance with the
terms of this license. No responsibility is assumed by Intergraph for the use or reliability of software on equipment that is not
supplied by Intergraph or its affiliated companies. THE USER OF THE SOFTWARE IS EXPECTED TO MAKE THE FINAL
EVALUATION AS TO THE USEFULNESS OF THE SOFTWARE IN HIS OWN ENVIRONMENT.
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.
Trademarks
Intergraph, the Intergraph logo, PDS, SmartPlant, SmartMarine, FrameWorks, I-Convert, I-Export, I-Sketch, IntelliShip, INtools,
ISOGEN, MARIAN, 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.
Contents
DBChecker Utility ........................................................................................................................................ 5
Log File Descriptions .............................................................................................................................. 7
Start the DBChecker Utility ..................................................................................................................... 9
Check the Database ............................................................................................................................... 9
Create a User Log File Without Implementing the Fixes ...................................................................... 10
Implement Fix Suggestions ................................................................................................................... 10
Exit the DBChecker Utility ..................................................................................................................... 10

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

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

Index ........................................................................................................................................................... 13

DB Checker Utility User's Guide 3

Contents

4 DB Checker Utility User's Guide

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.
Also, 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. Also, 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.
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

DB Checker Utility User's Guide 5

DBChecker Utility

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 also 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.

6 DB Checker Utility User's Guide

 DBChecker Utility

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.
 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 10)

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.

DB Checker Utility User's Guide 7

DBChecker Utility

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.
See Also
The DBChecker Utility (see "DBChecker Utility" on page 5)
Check the Database (on page 9)
Create a User Log File Without Implementing the Fixes (on page 10)

8 DB Checker Utility User's Guide

 DBChecker Utility

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 desired
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
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.

DB Checker Utility User's Guide 9

DBChecker Utility

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 10)
Check Results Dialog Box (on page 12)

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.

10 DB Checker Utility User's Guide

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 10)

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)

12 DB Checker Utility User's Guide

Index
creating without implementing fixes • 9
A descriptions • 7
activities that require database check • 5
O
C overview • 5
Check Results Dialog Box • 12
Check the Database • 8 P
checking the database • 5, 8, 11 problems • 7, 9, 12
activities that require database check • 5 detailed descriptions • 12
frequency factors • 5 fixing on the fly • 9
objects available for checking • 11 log files • 7
performing a check • 8
complog.txt • 7 R
Create a User Log File Without
Implementing the Fixes • 9 recreate.txt • 7
recreate_user.txt • 7
D
S
database • 8, 9
database objects • 11 SQL commands • 12
checking • 8 fix suggestions • 12
implementing fixes • 9 problem descriptions • 12
objects available for checking • 11 Start the DBChecker Utility • 8
DBChecker Utility • 5 starting • 8
DBChecker Utility Window • 11 Summary Dialog Box • 12

E W
errors • 7, 9 windows and dialog boxes • 11, 12
fixing on the fly • 9 Check Results • 12
log files • 7 DBChecker Utility • 11
Exit the DBChecker Utility • 9 Windows and Dialog Boxes • 11
exiting • 9

F
fix suggestions • 7, 9, 12
implementing • 9
log files • 7
SQL sentences • 12

I
Implement Fix Suggestions • 9
in_templ.db • 5

L
Log File Descriptions • 7
log files • 7, 9

DB Checker Utility User's Guide 13