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 are using 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.


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.




Use this option to display short help, which includes dbutility command syntax and parameters but not options.


Use this option to toggle the setting of the display_active_only parameter.


Use this option to toggle the setting of the defer_fixup_phase parameter during a clone command.


Use this option with any dbutility command to enable 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

Use this option when exporting or importing a configuration file to specify an input filename other than the default. 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.


Use this option to display long help, which includes dbutility command options, syntax, and parameters.


Use this option for a reload command to preserve the stateinfo for data sets whose format levels and item counts remain unchanged.


Use this option with any dbutility command to include a 5-digit millisecond timer in all output messages. The millisecond timer is appended to the timestamp in the trace.log file.


Use this option with dbutility runscript to override your entry for user_script_dir so that you can run any script that is not located in that directory.


This option 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.


This option 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.


Use this option for the rare occasions when certain relational database tables cannot be loaded via the bulk loader utility (SQL*Loader for Oracle and bcp for Microsoft SQL Server).

Using the -s option, you can inhibit 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.

-t mask

Use this option to enable the trace options designated by mask. See Enabling a Trace.

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.


Use this option if you want 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.


Use this option as a debugging tool when you need more information than what is provided by the DATABridge Client log file.

The -v option does the following:

  • Displays a message after every update received from DBServer or DBEnterprise.
  • Causes DATABridge Client scripts and user scripts to display the number of rows affected by INSERT, UPDATE, and DELETE SQL statements.

    Caution: It is recommended that you do not use the -v option when you run dbutility process to track changes. When you use the -v option during update processing, the following line of output is generated for each update record:

    Updating tablename for typeofupdate

    The result is a vast amount of output during update processing which will clutter up the log file and adversely affect performance.


Use this option to toggle the setting of the use_dbwait parameter.


Use this option to make the dbutility clone command clone all active data sets except for those specified at the command line.


Caution: This option is for troubleshooting only in a test environment. Do not use it in a production environment.

This troubleshooting option lets dbutility simulate a dbutility process or clone command, without actually storing data.

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) provides a way of determining 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.


Use this option 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. This prevents the client from deleting the tables when cloning these data sets. It drops their indexes instead and proceeds to append the new records to the tables.


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


Toggles the inhibit_console parameter. On UNIX, this doesn't apply if you run dbutility as a background run.

-D databasename

(Oracle only) Use this option to specify the relational database you are using.

-F afn

Use this option to make the client act as if a "QUIT AFTER afn" command had been executed. It applies to process and clone commands only. The range of values allowed are 1 through 9999.


This option 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.


Use this option to force the client to start using a new log file.


Use this option to toggle the setting of the enable_optimized_sql parameter.

-O ODBCdatasource

Use this option to specify an ODBC data source that connects to the Microsoft SQLServer and DB2 clients.

-P password

Use this option to define the password for accessing the relational database.


This option 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 fileprefix

Use this option to override the default trace prefix ("trace"). See Log and Trace Files.

-U userid

Use this option to define the user ID for accessing the relational database.


Use this option with the dbutility unload command to 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: 24 (version 6.1); 23 (version 6.0); 22 ; 21 (version, also referred to as TD2); and 19 (version 5.1).



Version 6.2



Version 6.1



Version (also referred to as TD7)



Version (also referred to as TD2)



Version 5.2 (base version)



Version 5.1

-X password

Use this option 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 the Server Accessory.


Use this option to force a process or clone command to drop and create the tables of all recloned data sets, regardless of the use of the deleted_record or expanded update_type columns.