Enabling a Trace

Note: Enable trace options only when directed to do so by Attachmate Technical Support. Specifically, do not routinely enable full tracing, SQL tracing, protocol tracing, or API tracing. The volume of logging data is so large that it may dramatically slow down the performance of the dbutility commands and fill up your hard disk.

Compress files using a compression utility before you send them to Attachmate Technical Support for analysis. Very large trace files should be broken into manageable pieces with the splitter utility before they're compressed. For help on running the splitter utility, type splitter with no parameters.

The trace option controls the volume and type of information written to the trace file.

To enable a trace using dbutility

  1. Determine the type of trace you want. Then, add the value for each tracing option (see the table below), and use the result for nnnn.
  2. Specify the -t nnn option using the following syntax:

    dbutility -t nnnn command

    where nnnn is a bit mask that specifies the tracing option.

    If you are not sure which tracing masks to use, use the -d option, which is the equivalent of -t 8191. Both ‑t 8191 and ‑d trace everything.

    You can enter other command line options, such as -U, -P, and -D, with the trace option. For example, you can specify your own file prefix and directory via the -T fileprefix option. The order is not important as long as all dash (-) options precede each command line argument.

  3. (Optional) To analyze performance, you can use an additional command line option, -m. This option includes a five-digit millisecond timer in all output messages. The timer is appended to the timestamp as (mmmmm).
  4. (Optional) To change the trace option when the DATABridge Client is running, use the commands explained in Controlling and Monitoring dbutility.

To enable a trace from the Client Console

  1. Do one of the following:
    • If the client isn't running, in the Explorer view, right-click the data source, select Advanced > Trace and Log Options, and select the trace options you want. When you start the client, the service will supply the appropriate trace options.
    • If the client is running, right-click the run and select Trace and Log Options. Select the tracing options you want and click OK.
  2. To stop tracing, clear your selections in the Trace and Log Options dialog box.

Trace Options

Decimal

Hexadecimal

Description

0

0

Tracing is disabled.

1

0x1

Writes log messages to the trace file in addition to trace information.

2

0x2

SQL trace that logs all SQL commands as the DATABridge Client passes them to the relational database. Typically, these messages are SELECT or UPDATE SQL statements and stored procedure calls.

4

0x4

DBServer or DBEnterprise communications message tracing. It logs key actions associated with DATABridge on the host, including RPC calls such as DB_SELECT and DB_READ and their responses.

8

0x8

Load tracing. This logs information on the DATABridge Client control tables as they are loaded from the relational database.

16

0x10

Relational database API tracing, which logs calls from the DATABridge Client to the ODBC, OCI or CLI APIs.

32

0x20

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

64

0x40

Traces information exchanged between the DBServer on the host or DBEnterprise 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 (.).

128

0x80

Traces all messages that are routed through the Client service (primarily messages from the Client Console and Client Configurator to the client, DBClient).

256

0x100

Traces debugging output that is temporarily added to the DATABridge Client (primarily engineering releases).

512

0x200

Displays the configuration file parameters as they are processed.

1024

0x400

Traces information exchanged between DBClient (or DBClntCfgServer) and the service. The output looks like a DBServer protocol trace, except for the fact that all the data is ASCII.

2048

0x800

Enables SQL tracing while running user scripts during define and redefine commands.

4096

0X1000

Controls whether or not the Read_CB exit line is printed in the trace file. This option is useful only for determining when the execution of a SQL statement ends because the start of the subsequent wait for TCP input is not traced.

Examples

Following are different ways you can set the logging options.

Log Option Example
(Decimal and Hexadecimal)

Result

dbutility -t 7
dbutility -t 0x7

Traces log data (1), SQL (2) and host events (4)

dbutility -t 8191
dbutility -t 0x1FF
dbutility -d

Traces all events listed in the table on the previous page