Skip to content

Advanced Options and Commands

Getting there

  1. From the Dashboard select the Client Manager server.

    -or-

    Select Servers from the left side navigation and select the Client Manager server.

  2. From the Client Manager data source page, select the Advanced drop-down button and choose from the commands and options listed below on this page.

Trace and Log Options

To open the Trace and Log Options settings page, select the Advanced button drop-down and select Trace and Log Options. Use the options in this dialog box to enable tracing.

Trace files are primarily used by Micro Focus Customer Support for diagnostic purposes. Trace files are not enabled by default because they use a significant amount of hard disk space.

It is recommended that you use the default trace options when sending a trace to Micro Focus Customer Support, unless you are specifically asked to use different options. You can also specify default trace options for a process or clone command by using Data Source page > Advanced > Process (with options) (just check the Enable default tracing option in the dialog box).

Note

When you enable tracing options using this dialog, they are applied to the next command or run launched from the Administrative Console unless there is an active Process or Clone command being run. When there is an active run, the specified tracing options get enabled for the run by sending it an RPC that enables the tracing. Once the tracing options get applied to a run or command, these settings are reset. This eliminates the possibility of having all subsequent commands and runs launched by the Administrative Console execute with tracing enabled.

For more information about trace files, see Trace and Log Files in the Databridge Client Administrator's Guide.

Global Selection Options
Select all Click to select all of the trace options
Select default Click to select the default trace options
Select none Click to deselect all of the trace options
Trace Options
Log output Writes log messages (in addition to trace information) to the trace.log file.

(Decimal value: 1 Hexadecimal value: 0x1.)
Server messages Enables tracing of Databridge Server communications messages for key actions associated with Databridge on the host, including RPCs such as DB_SELECT and DB_READ and their responses.

(Decimal value: 4. Hexadecimal value: 0x4.)
Database API calls Enables the logging of calls from the Databridge Client to the ODBC or OCI APIs. This is also referred to as relational database API tracing.

(Decimal value: 16. Hexadecimal value: 0x10)
TCP/IP data Enables a protocol trace of the information exchange between Databridge Server on the host or Enterprise Server and the Databridge Client. The blocks of data are traced as they are read and written to the TCP interface. The messages are listed in DEBUG format, which is an offset followed by 16 bytes in hexadecimal, followed by the same 16 bytes interpreted as EBCDIC text. The non-printable EBCDIC characters are displayed as periods (.).

(Decimal value: 64. Hexadecimal value: 0x40.)
Debug Enables debugging code that may be added to engineering releases of the Databridge Client.

(Decimal value: 256. Hexadecimal value: 0x100.)
Remote console RPC's Enables remote console message tracing when running DBClient or DBClntCfgServer in conjunction with the service.

(Decimal value: 1024. Hexadecimal value: 0x400.)
Callback exit Enables a trace that helps determine if delays occurred while SQL statements were being executed or while the Databridge Client was waiting for data from the Databridge Server.

(Decimal value: 4096. Hexadecimal value: 0x1000.)
Verbose trace Enables the tracing of certain entries that are normally not traced as the information they provide is often of rather dubious value.

(Decimal Value: 65,536. Hexadecimal value: 0x10000)
DMS buffers Enables the tracing of the allocation and freeing of DMSII buffers. Use this trace when trying to debug a DMSII buffer leak.

(Decimal Value: 262,144. Hexadecimal value: 0x40000)
Buffer sizes Enables a trace that Shows the size calculations for the SQL and host variable buffers. This trace is only useful when you have problem with buffer or host variable overruns.

(Decimal Value: 1,048,576. Hexadecimal value: 0x100000)
SQL commands Enables a trace of SQL commands.

(Decimal value: 2. Hexadecimal value: 0x2.)
Control table load This is load tracing. Load tracing logs information on the Databridge Client control tables as they are loaded from the relational database.

(Decimal value: 8. Hexadecimal value: 0x8.)
Bulk loader data This is a trace of the records that are written to temporary data files (or UNIX pipes) and used by the bulk loader utility during the data extraction phase of cloning.

(Decimal value: 32. Hexadecimal value: 0x20.)
Remote console data This is a protocol trace of the information exchange between DBClient or DBClntCfgServer and the service. The output looks like a Databridge Server protocol trace, except for the fact that all the data is ASCII.

(Decimal value: 128. Hexadecimal value: 0x80.)
List config file This option displays the configuration file parameters as they are processed.

(Decimal value: 512. Hexadecimal value: 0x200.)
User script SQL Temporarily enables SQL tracing when running user scripts during define and redefine commands.

(Decimal value: 2048. Hexadecimal value: 0x800.)
DOC Records Enables a trace of DOC records, which must be enabled. DOC records help get a better insight of what is going on in the audit files. This option is meaningless when Server Message tracing is enabled, because that trace includes DOC records.

(Decimal Value: 8192. Hexadecimal value: 0x2000)
Thread Trace Enables a trace that shows when thread are started and stopped, this trace is seldom useful, unless you are dealing with hung threads.

(Decimal Value: 131,072. Hexadecimal value: 0x20000)
Row Count Enables a tracing of the row counts after SQL statement are executed.

(Decimal Value: 524,288. Hexadecimal value: 0x80000)
Trace mask This entry is automatically filled in as you select trace options. It represents the hex value of the trace mask that is added to the command line using the /t option using a prefix of 0x.
Log Options
Verbose Logs some additional information. Most of the verbose output that you had in older versions is now available in the trace options.

Change Database Password

The database password is specified in the authentication settings when you add a new data source. For example, if you use SQL Server authentication, this password is used by the Databridge Client to log in to the relational database.

Some sites periodically require all passwords to be changed, when this is the case, this command allows you to update the database password in the Client configuration file so that the client can continue operating after the database user password was changed.

To change the data source password

  1. From the Client Manager data sources page, select Advanced > Change Database Password.

  2. Add the new password in New password and the Verify password input fields, and then select OK.

Change SOURCE Password

Use this procedure to regain access to the DBServer if the password to the SOURCE changes. The SOURCE password is specified by the KEY parameter in the DBServer control file. For more information, see the Databridge Host Administrator's Guide.

To change the SOURCE password

  1. From the data sources page, select Advanced > Change SOURCE Password.

  2. In the New Password box, enter the password exactly as it appears in the DBServer control file

  3. In the Verify Password box, type the password again, and then select OK.

Export Client Configuration

Use this procedure to create a readable copy of the Client configuration file. The Client configuration file contains the current configuration settings for a data source, which are set from the Administrative Console and the Client Manager. (The Administrative Console also includes settings to configure the service. These settings are saved to the service configuration file. For more information about this file, see Client Configuration Files" in Appendix D of the Databridge Client Administrator's Guide.)

On rare occasions, you'll need to change a parameter that can't be set in the Administrative Console. In this case, you'll need to export the configuration file, edit it, and then import it using the command-line Client dbutility.

To export the client configuration file

  1. From the data sources page, select Advanced > Export Client Configuration.

Note

Passwords in the Client configuration file are automatically encoded when using the export command to export the file.

A new text data source configuration file (dbridge.ini) is created from the binary configuration file (dbridge.cfg).

Unload, Reload, and Remove Data Source

This section describes when to use the Unload Data Source, Reload Data Source, and Remove Data Source commands.

Unloading/reloading a data source

The Unload Data Source command is used to back up the Client control tables when they're in a good working state. When you use this command, enter a filename, and use optional command-line commands. You can use this back up copy to restore the Client control tables as needed by using the Reload Data Source command and entering the same filename used with the Unload Data Source command.

The file created by the Unload Data Source command is intended only for the program's use. When you report a problem to Micro Focus Customer Support, they may ask you to provide an unload file.

Removing a data source

The Remove Data Source command deletes the data tables (that is, the cloned data) and the Client control table entries of a data source. After you select the command, you have the option to remove the working directory and all associated files for the data source. It is recommended that the data tables are deleted after testing configuration features on a new data source before cloning for a production environment.

It is recommended to delete just the data tables after testing configuration features on a new data source or before cloning it for real-world production.

Process (with options)

The Process With Options command opens a dialog that allows the user to add command-line options to the DBClient process command before sending the request to launch a process command. the Process command in the Actions drop-down for data sources launches the process command with no command-line options.

You can select as many options as needed by moving the enabling the corresponding options. When you are done, select OK to launch the Process command.

Getting there

  • From the Client Manager select Advanced > Process (with options)

Options

Toggle "Defer Fixups" parameter (-c option)

Adds the "-c" option to the DBClient command-line, which causes the Client to toggle the defer_fixup_phase parameter. When the resulting value of defer_fixup_phase parameter is True (enabled), the process command does not enter the fixup phase at the end of data extraction. Instead of issuing a request to the Databridge Server to initiate the fixup phase, the Databridge Client terminates. The next process command then picks up where the clone command left off.

Use BCP for data extractions (-l option)

(SQL Server only) Adds "-l" option to the DBClient command-line, which forces the Client to use the bcp utility instead of the BCP API to load the tables during the data extraction phase.

Toggle "Use DBWait parameter (-w option)

Adds the "-w" option to the DBClient command-line, which causes the Client to toggle the use_dbwait parameter. When the resulting value of use_dbawait parameter is True, the Client uses the DBWAIT RPC and the DBREAD RPC when it is set to False. The DBREAD RPC returns an Audit Unavailable status to the Client, which stops the replication when the Databridge Engine reaches the end of the current audit file or if it cannot open the current audit file as the Engine READ ACTIVE AUDIT parameter is set to False. The DBWAIT RPC enters a wait and retry loop instead.

Reclone all data sets with mode 11 or 12 (-y option)

Adds the "-y"option to the DBClient command-line, which causes the Client to re-clone data sets whose ds_mode column in the DATASETS Client control table is set to 10, 11, or 12.

Reclone all active datasets (-Y option)

Adds the "-Y reclone_all" option to the DBClient command-line, which causes the Client to re-clone all data sets whose active column is 1 in the DATASETS Client control table.

Enable default tracing (-d option)

Adds the "-d" option to the DBClient command-line, which enables default tracing for the process command.

Note

If Micro Focus Customer Support asks you for a trace, use this option, unless you are told otherwise.

Run command in read-only mode (-z option)

Adds the "-z" option to the DBClient command-line, which runs the process command in read-only mode. No updates are made to the relational database. This command is useful if you want to determine how fast the client can run. If you are not sure why the replication is running slow, this option provides a way to determine if the overhead is in the relational database or somewhere else.

Warning

This option is intended for troubleshooting in a test environment. Do not enable this option in a production environment.

Clone Data Set

Use the Clone Data Set option to clone specific data sets in a data source and track updates. Before you clone a data source, make sure that you've completed all customizations to the data source.

Steps to Clone Data Sets

  1. In the data sources page of the Client Manager, select Advanced > Clone Data Sets from the drop-down menu.

  2. Select the available data sets that will be cloned from the list and set additional parameters as needed.

    Additional Settings Description
    Clone all data sets except the ones selected (-x option) When enabled, the Databridge Client clones all active data sets that are not selected in the data set list view.
    Toggle "Defer Fixups" parameter (-c option) Toggles the defer_fixup_phase configuration file parameter. When you use this option, the dbutility clone does not enter the fixup phase at the end of data extraction. Instead of issuing a request to the Databridge Server to initiate the fixup phase, the Databridge Client terminates. The ds_mode values of all cloned data sets remain set to 1 with all of the necessary stateinfo stored in the Client control tables (for example, audit_filenum, audit_block, and host_info). The next process command then picks up where the clone command left off.
    Enable default tracing (-d option) This option enables full tracing.
    Use BCP for data extractions (-l option) (SQL Server only) Enable this parameter to force the client to use the bcp utility instead of the BCP API.

  3. Select Clone.

    During the initial clone, DMSII data for the data source is extracted and cloned to the relational database.

    After the data source is cloned, you can run the Clone Data Set command anytime you want to update the relational database. The Clone Data Set command tracks DMSII updates by reading the audit trail and synchronizes the received data to mirror the DMSII database. To schedule updates to occur automatically, use the Scheduling parameters in the Configure command. For more information on scheduling see the Processing - Schedule.

Log Control Tables

This command is the equivalent of the command-line Client's display command. It writes the control tables entries to the DBClntCfgServer program's log file for the data source. The log file resides in the data sources logs folder and has a name of "prefix_cfgMMDDYYY.log". Where prefix is "db" unless you it has been changed using the Configure command in the Settings menu for the data source, and MMDDYYYY is the date when the log file was created. See the Databridge Client Administrator's Guide for a description of the Client control tables and a list of the abbreviations used in the display command output.

None of the output is directed to the Administrative Console as the display command reports are large.

Redefine (with options)

The Redefine (with options) command opens a dialog that allows the user to add command-line options to the Redefine command before sending the request to run a redefine command to the DBClntCfgServer program. The Define/Redefine command in the Actions drop-down on the data source pages launches the Redefine command with no command-line options.

Getting there

  • From the Client Manager select Advanced > Redefine (with options)

Options

Redefine all data sets (-R option)

Forces all data sets to be redefined. Use this option if you made a change using the Customize command that requires all data sets to be redefined.

Toggle use of user scripts (-r option)

Enables the parameter use_dbconfig. If this parameter is enabled, the command will revert to using user scripts. Use this option if you have created the users scripts by running the Create User Scripts command from the Advanced button drop-down for the data source and customizations are not working as expected. Running a Redefine command with this option and the Redefine all data sets options would restore the control tables to their original state from the Create Scripts command.

Override warnings (-u option)

Enabling this option will override conditions that the DBClient would otherwise interpret as a possible user error. This can happen when mixing Customize and Redefine commands. It is safe to run a Redefine command if you have not run a Customize command since the last time a Process command was run to process updates. If you get into a situation where the Redefine cannot be ran, as the unload file used to back up the Client Control table was created by the Customize command, using this option will solve the problem. However, any customization made since the unload file was created will be lost.

The reason for this difference is that the Customize command can be run on demand, but the Redefine command does not allow you to run the command more than once, unless you restore the control tables from the unload file it creates. Starting with a Customize command causes the Redefine command to restore from a backup, which would lead to lost updates from the Customize command.

Generate All Scripts

Enabling this option initiates a Generate Scripts command "-u" option on the command-line, which causes the command to generate the scripts for all the tables to be generated. This command has no dialog, as you can add a single option to the command. The Generate Scripts command in the Actions button drop-down for the data source only generates the scripts for the tables whose scripts are not current.

Getting there

  • From the Client Manager select Advanced > Generate all scripts

Refresh Data Sets

Getting there

  • From the Client Manager select Advanced > Refresh Data Set

Enabling this command should not be common. When enabled, this command will drop the stored procedures associated with the tables mapped from a data set. The Reorganize command is closely related to this command, as it is used when the relational database tables' layout has changed as a result of a DMSII reorganization, or from user initiated changes that affect the table layout. The most common situation where you would need this command is when a user alters the stored procedures associated with the tables for a specific data set.

This command can be applied to a single data set or all data sets. When refreshing more than one data set you will need to run the command multiple times.

Options

Refresh all data sets

Select this option to refresh all data sets.

Refresh data set

Select a specific data set to refresh by using the drop-down list of data sets.

Reorg (Multi-source, 2nd source)

This is a special form of the Reorganize command used for multi-source data sources with merged tables. This command allows multiple DMSII databases whose DASDLs are identical to be replicated to a single relational database. When DMSII reorganizations occur in these environments, you cannot run a Reorganize command that alters the tables for each data source, as there is only one set of tables. Ensure that all the Clients for the various DMSII data sources are caught up with the reorganizations before you can run a Reorganize command. Once the command is run the tables will be altered. This command adds the -n option to the command-line for the command, which inhibits the running of scripts to alter the tables, but does everything else the Reorg command does. Refer to the Databridge Client Administrator's Guide for more information.

Create and Run User Scripts

You can save customizations to the relational database table layout as user scripts. If the system fails, the define command automatically uses these user scripts to rebuild the client control tables.

When modifying relational database table layouts from the Customize option, it is recommended that changes are saved as user scripts for backup purposes. If a hard disk or system failure occurs, user scripts can be used to recover customized table layouts.

After the console copies the existing user scripts to the user scripts archive directory, it creates a new set of user script files in the user scripts directory. This information can be seen in the console output located at the bottom of the Administrative Console.

Note

You do not need to archive user scripts from previous versions of the Databridge Client/Administrative Console. The Windows installer provides you with an option of copying the configuration files and user scripts from the previous version's working directory to the new working directory.

To create user scripts from the Administrative Console

  • With the data source selected in the data sources page, select Advanced > Create User Scripts.

    Following a customization of a data set, configure the user script with the options below and select OK.

    The script will be saved in the scripts directory.

Do not backup old user scripts

When enabled, this command removes all the customization user scripts and recreates them while preserving any other scripts that the user might have created (for example cerate table scripts).

Include data source name in user scripts

Enable this option to include the selected data source name in the user scripts.

Run User Scripts

To run a user script

  • With the data source selected in the data sources page, select Advanced > Run Script.

Run History

When enabled, the monitor will maintain a table with the run history of the last 10 runs. This includes the start and end times for the runs, the ending state information values, and the exit codes. This command is only available when there is no active run.

To see the Run History

  • With the data source selected in the data sources page, select Advanced > Run History.