Appendix B: dbutility Commands and Options

This appendix provides a list of all dbutility commands and command-line options. For a complete reference of command-line options paired with their equivalent environment variables and configuration file parameters, see Reference Tables.

Note

The hyphen is used for all command options and is valid for Windows and UNIX. Windows users can substitute the slash ( / ) for the hyphen.

dbutility Commands

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

Example

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

Command	Purpose and Result
dbutility clone datasource dataset1 [dataset2... datasetn]	Related command-line options: Signon options, `-c`, `-f`, `-l`, `-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: We recommend 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, we recommend 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`, `-l`, `-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 re-clone 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 DATA SETS 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 rem . . .	A dummy command that opens the log file and echoes the command line into it. The purpose of this command is to make it possible for script files or operators to create a log file entry to document the action that was taken. For example: `dbutility rem accidentally killed the Client – JaneDoe`
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 rowcounts datasource	Related command-line options: Signon options, `-f`, `-m`, `-t`, `B`, `-L`, `-T` Creates a report in the log file with all the row counts for all the active tables associated with the data source.
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 Databridge Engine 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.

dbutility Command-Line Options

This section explains the command-line options you can enter with dbutility commands, with all lowercase options first in alphabetical order and all uppercase options following. Use the following syntax to include the command-line options:

dbutility [options] command

where [options] begin with the forward slash (/) or hyphen (-) and are followed by a letter and a possible argument, as listed in the following table. If you use a UNIX Client, all options must start with a hyphen (-). Note the following guidelines for using command-line options:

All options are case-sensitive.
The options can be used in any order.
When you enter any of these command-line parameters, do not type the [brackets]. The [brackets] indicate that the command-line parameter is optional.
Following the option letter, you can enter option arguments with or without a space. For example, -tl and -t l are equivalent.
If an argument is blank (an empty character string), you can omit it if the next entry on the command line is another option (for example, -D). Otherwise, you must enter the blank argument as " " (quotation marks) with both leading and trailing spaces.

Examples

Assume you want to override the environment variable for the relational database name 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

(Both of these examples override the environment variable DBDATABASE.) For a complete reference of command-line options paired with their equivalent environment variables and configuration file parameters, see Reference Tables.

This option	Does this
`-?`	Displays short help, which includes dbutility command syntax and parameters but not options.
`-a`	Toggles the setting of the `display_active_only` parameter.
`-c`	Toggles the setting of the `defer_fixup_phase` parameter during a `clone` command.
`-d`	When used with any dbutility command, this option enables full tracing. This is the same as entering `-t 8191` (or `-t 0x1FFF`). If you are not sure whether to use the `-d` option or the `-t` option, you may want to use the `-d` option. It is often better to have too much tracing information than not enough.
-f filename	Specifies an input configuration file other than the default filename when used with an import command. If filename doesn't start with a backslash () on Windows or a forward slash (/) on UNIX, it is assumed to be in the config subdirectory of the working directory. Conversely, if filename starts with the appropriate slash, it is taken to a full file specification.
`-h`	Displays long help, which includes dbutility command options, syntax, and parameters.
`-k`	Used with a `reload` command to preserve the stateinfo for data sets whose format levels and item counts remain unchanged. Used by the `process`, `clone` and `drop` commands in a multi-source environment to force the Client drop tables rather than running the cleanup script. This is designed to be used after a reorg that requires a re-clone, one would otherwise have to physically drop the affected table(s) to get the clone to recreate the table(s) with the new layout. Now you can use the `-k` option on the first data source that gets re-cloned; from thereon the `-k` option must obviously not be used.
`-l`	(SQL Server only) forces the Client to use the bcp utility instead of the BCP API.
`-m`	Includes a 5-digit millisecond timer in all trace messages. The millisecond timer is appended to the timestamp in the trace file. This option does not affect log file output.
`-n`	Used with the `runscript` command to override your entry for `user_script_dir` so that you can run any script that is not located in that directory.
`-o`	Overrides shutdown periods, including those initiated by the stop_time and end_stop_time values in the DATASOURCES Client control table for the data source entry when the `controlled_execution` configuration file parameter is enabled.
`-r`	Forces the parameter `use_dbconfig` to be treated as False when running a redefine command. The `use_dbconfig` parameter is internal and not directly editable. However, this parameter is set to True in the following situations: When a data source is created using the Client Configurator When a define command creates the data source and no users scripts are encountered When you run the dbscriptfixup program In all other cases, including after an upgrade using the migrate program, the `use_dbconfig` parameter is set to False. Its purpose is to ensure that the Client Configurator isn't run with improperly setup Client control tables. This would cause all changes that were made via user scripts to be lost.
`-s`	Loads relational database tables that cannot be loaded via the bulk loader utility (SQLLoader for Oracle and bcp for Microsoft SQL Server). The `-s` option inhibits the use of the bulk loader utility during the data extraction phase of cloning. The Databridge Client loads the table using SQL statements instead. CAUTION:* Use this option only when certain tables will not load via the bulk loader utility. Do not use it under normal circumstances. The -s option slows the cloning process considerably. The `-s` option is also used by the createscripts command to add the data source name in all where clause of the SQL statements that are created.
`-t` mask	Enables trace options designated by mask. See Enabling a Trace. If you are unsure whether to use the `-d` option or the `-t` option, you may want to use the `-d` option. It is often better to have too much tracing information than not enough.
`-u`	Creates override conditions that dbutility would otherwise interpret as a possible user error. These situations include the following: Creating a second set of Client control tables within one relational database. In this case, the second set of tables must be owned by a different user ID. Starting over by dropping and creating the Client control tables, even though this removes all of the state information associated with the user tables. Attempting to define a data source that already exists. With the dbutility `dropall` command, use this option to drop Databridge Client tables that still contain data.
`-v`	Causes the Databridge Client to write some additional information to the log file and sometimes to the screen. The most useful one is causing user scripts executed by the Client to write the number of rows affected by INSERT, UPDATE and DELETE SQL statements to the log file.
`-w`	Toggles the setting of the `use_dbwait` parameter.
`-x`	Makes the `clone` command clone all active data sets except for those specified at the command line.
`-y`	Forces the Client to re-clone data sets with a mode of 11 and 12.
`-z`	CAUTION: This option is for troubleshooting only in a test environment. Do not use it in a production environment. Allows dbutility to simulate a dbutility `process` or `clone` command without actually storing data. For troubleshooting purposes. After the Client control tables are loaded for the specified data source, the program sets a global flag that disables all SQL execution by the ODBC (Microsoft SQL Server) or OCI (Oracle) interface routines. Using this option with statistics enabled (`show_statistics` and `show_perf_stats` both set to True) to determine the rate at which the Databridge Engine and the Databridge Client can process data without including any of the additional delays caused by the relational database. If this rate is significantly slower than the rate you get when the `-z` option is set, you can conclude that the slowness is caused by the actual relational database, which might need to be tuned.
`-A`	Prevents the Client from deleting the tables when cloning virtual data sets that have the `DSOPT_Ignore_Dups` option bit (value 32) set in the `ds_options` column of the DATASETS Client control table. Instead, it drops their indexes and appends the new records to the tables.
`-B`	Causes the display command to report only the second half of the DATASETS Client control table to the trace.log file, then causes the program to quit. (In most cases, the information in the second half of the DATASETS Client control table is the only information you actually need from that table.)
`-C`	Toggles the `inhibit_console` parameter. On UNIX, this doesn't apply if you run `dbutility` as a background run.
`-D` databasename	(Oracle only) Specifies the relational database you are using.
`-F` afn	Makes the Client act as if a `QUIT AFTER afn` command had been executed. Applies only to `process` and `clone` commands. The range of values allowed are 1 through 9999.
`-K`	Inhibits audit file removal WFLs from running on the host during a process command. This option is also implied during a `clone` command and when used with the `-z` option.
`-L`	Forces the Client to start using a new log file.
`-N`	Toggles the setting of the `enable_optimized_sql` parameter.
`-O` ODBCdatasource	Specifies an ODBC data source that the Client uses to connects to the Microsoft SQLServer database.
`-P` password	Defines the password for accessing the relational database.
`-R`	Treats every data set as if its DS_Needs_Redefining status bit is set and allows the program to rebuild the control tables when you change a configuration parameter such as `optimize_updates` or `read_null_records`.
`-T`	Forces the Client to start using a new trace file. See Log and Trace Files.
`-U` userid	Specifies the user ID defined in the relational database.
`-V`	Used with the unload command, this option lets you specify the control table version you want. To create tables that you can use with an older Client version, use the value that corresponds to that version. Values for the Databridge Client are as follows: 34: Version 7.0 SP1 33: Version 7.0 31: Version 7.0 30: Version 6.5 SP1 29: Version 6.5 26: Versions 6.2 and 6.3 25: Version 6.1 SP3 24: Version 6.1 23: Version 6.0 22: Version 5.2.0.12 21: Version 5.2.0.3 20: Version 5.2 (base release) 19: Version 5.1
`-W`	NOTE: Uses Integrated Windows Authentication to connect to the SQL Server database.
`-X` password	Used to define a host password. The host password is required only when it is configured on the host in the DBServer control file. CAUTION: The password is currently not encrypted in communications between the Databridge Client and Databridge Server.
`-Y` `reclone_all`	Causes a process command to re-clone all data sets. The text reclone_all is required and prevents you from accidentally recloning everything, when you actually wanted to specify the -y option. When using the console, specify this option by selecting a check-box labeled “Reclone all active data sets.” To find this option, click the data source in Administrative Console Explorer view to activate the Data Source menu, then click Data Source > Advanced > Process with options.
`-Z`	Forces a `process` or `clone` command to drop and create the tables of all re-cloned data sets, regardless of the use of the `deleted_record` or expanded `update_type` columns.