dbutility Commands

The following table lists all of the dbutility commands and their related command-line options.


Assume you want to override the environment variable for the relational database name (DBDATABASE) and enter a blank instead (which is the same as the using the default database name). To do this, you could enter either of the following:

dbutility -U usera -P secret -D "" configure

dbutility -U usera -D -P secret configure


Purpose and Result

dbutility clone datasource dataset1 [dataset2... datasetn]

Related command-line options: Signon options, -c, -f, -m, ‑o, -s, -t, -u, -v, -x, -z, -A, -F, -K, -L, -N, -T

Run this command to clone or reclone (not track changes) a list of data sets. Using the dbutility clone command is a convenient way of cloning a few data sets without having to update the DATASETS client control table. For recloning with dbutility clone, see Recloning.

dbutility configure

Related command-line options: Signon options, -f, -m, -t, -u, -L, -T

Run once for each set of client control tables you want to create. The result is empty client control tables and their indexes in the relational database. See Creating Client Control Tables.

Note: The only time you would run dbutility configure again for the same relational database is if you previously executed a dbutility dropall command.

dbutility define datasource host port

Related command-line options: Signon options, -f, -m, -t, -u, -v, -L, -T

Run once for each data source you want to define except when customizing with user scripts. See Customizing with User Scripts. The result is a data source entry in the DATASOURCES client control table and all other client control tables containing the DMSII database layout and corresponding relational database table schema information. See Defining a Data Source.

dbutility display datasource

Related command-line options: Signon options, -a, -f, -m, -t, ‑B, -L, -T

Run this command to create a report of the DATABridge Client control tables for the specified data source. The report is written to the log file in the logs directory. For more information about log files, see Log and Trace Files.

Use this command to check the results of the dbutility define command or script customization.

Note: When you use dbutility display, the column names for the client control tables are abbreviated. The actual column names and the abbreviated column names are listed for each client control table in Chapter 6, DATABridge Client Control Tables.

dbutility drop datasource

Related command-line options: Signon options, -m, -t, -v, -L, -T

Run this command to "undo" the results of a dbutility define, generate, process, and clone for a specified data source. dbutility drop does the following:

  • Drops tables and their associated stored procedures
  • Removes the script files in the current directory
  • Deletes the DMSII record layout and relational database table schema information (for the specified data source) from the client control tables

    Caution: It is recommended that you create a separate directory for each data source. When you must drop a data source, make sure that the current directory is the directory you created for the data source. Then, use the drop (not dropall) command to drop each individual data source. Failure to do this results in dbutility not being able to locate the required scripts, which causes it to terminate with an error.

dbutility dropall

Related command-line options: Signon options,-m, -t, -u, -L, -T

Run this command to drop all tables that have been created by the DATABridge Client, as well as to remove the script files in the current directory. Note that your other non DATABridge tables are not affected.

If you are executing dbutility commands from more than one directory, the dbutility dropall command locates scripts in the current directory only. In this case, it drops the scripts that it can find and then refrains from removing the client control table entries for those data sources that it could not properly delete (that is, the data sources whose scripts are in other directories). Therefore, it is recommended that you do either of the following:

  • Change the directory and repeat the dbutility dropall command.
  • Drop each data source via the drop command, then use dbutility dropall for the final data source.

    Typically, you do not need to use this command.

dbutility options export filename

Related command-line options: -E, -u

Exports the binary client configuration file to an editable text file (dbridge.ini, by default) that can then be imported, using the import command, for use with the DATABridge Client. See Export or Import a Configuration File.

dbutility generate datasource

Related command-line options: Signon options, -f, -m, -t, -u, -v, -L, -T

Generates the DATABridge Client script files required to populate the DATABridge data tables in the relational database.

The result is a set of scripts in the dbscripts subdirectory of the working directory. There are approximately five scripts for each DMSII data set.

See Generating DATABridge Client Scripts.

dbutility options import filename

Related command-line options: -E, -f filename, -u

Reads the specified input file and writes it as a binary client configuration file (dbridge.cfg, by default). See Export or Import Configuration Files.

dbutility process datasource

Related command-line options: Signon options, -f, -m, ‑o, -s, -t, -v, -w, -z, ‑C, -K, -N, -L, -T

Run the first time to populate the DATABridge tables in the relational database with the DMSII database data. Run subsequent times to update the relational database with only the changes that have been made to the DMSII database since the last time you ran dbutility process.

Note: dbutility process can also reclone instead of update if ds_mode=0 when you run dbutility process.

See Populating the DATABridge Data Tables and Updating the DATABridge Data Tables.

dbutility redefine datasource

Related command-line options: Signon options, -f, -m, -t, -u, -v, -r, -R, -L, -T

The redefine command compares the old and new layouts of all the tables generated for data sets whose status_bits columns indicate a structural reorganization.

The redefine command also does the following:

  • If a new data set appears, the redefine command defines it with its corresponding active column set to 0 in the DATASETS client control table (unless the suppress_new_datasets parameter is set to False). When the active column is set to 0, the redefine command will not perform any mapping for it unless you set the active column in the DATASETS entry to 1 in the corresponding data set mapping customization user script.
  • If a data set no longer exists, the redefine command deletes all the associated client control table entries, but does not drop the data tables and their associated stored procedures. You must delete them by running the corresponding scripts (these are not removed either).
  • The redefine command refreshes the data set mapping in three instances. First, the mapping is refreshed when the data set’s DS_Needs_Remapping bit is set (value 4). Use this method when you modify the DATASETS and DMS_ITEMS tables. Because the data set mapping customization scripts are not run in this instance, you must execute the runscript command prior to executing the redefine command. Secondly, mapping is refreshed if a data set’s active column is set to 1, and the DS_Needs_Mapping bit is set (value 1) in the status_bits column. Thirdly, mapping is refreshed when you set the DS_Needs_Redefining bit (value 8). In this case, the redefine command refreshes the DMSII layout as well.
  • If a data set has an active column set to 0, and the DS_Needs_Mapping bit is set (value 1) in the status_bits column, the layout information is refreshed, but no mapping is performed.
  • The redefine command sets the active columns of the client control tables equal to zero for data sets that contain global data. No other data sets are affected by the redefine command. You must execute a generate command after a redefine command to update the scripts.

dbutility [options] refresh datasource dataset

Related command-line options: Signon options

The refresh command enables you to drop and recreate all of the stored procedures for the tables associated with the given data set in the specified data source. It is a variation of the runscript command that is designed to run portions of the DATABridge Client scripts (script.drop.tablename and script.create.tablename). This command is useful when you want to add a new column to a table after a DMSII reorganization.

If _ALL is specified for dataset, the program refreshes the stored procedures for all active tables. If a specific data set is specified, only the stored procedures for that data set refreshed. All data sets specified must already exist.

Note: When variable-format data sets are involved, the tables for all the record types that have their active column set to 1 in the DATASETS client control table are refreshed.

dbutility reload datasource backupfile [dataset,dataset2...]

Related command-line options: Signon options, -f, -k, -m, -t, -L, -T

Restores the client control tables from a file that the unload command created. If a datasource of _ALL is specified, all data sources contained in the backup file are restored. If a specific data source is specified, only the entries for that data source are restored from the file. The reload operation is sensitive to the version of the program that wrote the backup file.

As an option, you can provide a list of data sets to be loaded. If such a list does not exist, all data sets for the given data source are reloaded. The -k option preserves the stateinfo for data sets whose format levels and item counts remain unchanged.

dbutility reorg datasource

Related command-line options: Signon options

Generates new scripts for stored procedures and refreshes the relational database stored procedures. The reorg command resets ds_mode to 2 (indicating that the data set is in tracking mode).

Typically, you would use the reorg command after the redefine command when a reorganization has occurred on the DMSII database.

dbutility runscript filename

Related command-line options: Signon options,-m, -n, -t, -L, -T

Use this command to run user scripts (for example, script.user_define.primary_tablename) or DATABridge Client scripts (for example, script.create.tablename).

The DATABridge Client expects the user scripts to be located in the directory specified by user_script_dir in the DATABridge Client configuration file. To override this directory specification, use the -n option, as follows:

dbutility -n runscript drive:\directory\scriptfilename

The runscript command automatically enables SQL tracing and logging (similar to setting the -t 3 option).

The runscript command runs in transaction mode so that if an error occurs, all changes are rolled back. You can then fix your scripts and run them again.

dbutility switchaudit datasource

Related command-line options: Signon options, -f, -k, -m, -t, -v, -L, -T

Run this command to close an audit file on the host. This ensures that you get the most current information possible because the DBEngine does not read the currently open audit file. DMSII audit files are explained in detail in the DATABridge Host Administrator’s Guide.

Important: Do not use this command unless you check with the DMSII database administrator first.

dbutility tcptest datasource [host port] length count

Related command-line options: Signon options, -f, -m, -t, -L, -T

Run to test the TCP/IP interface between the DATABridge Client and the server. You can use this command as a diagnostic tool to help troubleshoot slow network connections.

If the data source is already defined, you do not have to specify the host and the port parameters; the program reads them from the DATASOURCES table entry instead.

Length is the size of the message to use and count is the number of iterations that should be executed. 8000 and 1000 are standard values with these options.

dbutility unload datasource backupfile

Related command-line options: Signon options, -f, -k,-m, -t, -L, -O, -T

Creates a file containing a backup of the client control tables. If a datasource of _ALL is specified, all of the data sources that are found in the client control tables are written to the backup file backupfile. If any other data source is specified, only the entries for that data source are written to the file.