Command Reference

db2trc - Trace

Activates DB2 trace facility tracing. DB2 uses its trace facility to trace events, dump trace data to a file, and format trace data into a readable form. Only use the trace facility when directed by DB2 Customer Service or by a technical support representative.

Authorization

On UNIX based systems, one of the following:

• sysadm

• sysctrl

• sysmaint

On OS/2 or the Windows operating system, no authorization is required.

Required Connection

None

Command Syntax

>>-db2trc--+----------------------------------------------------+->
           |     .- ------------------------------------------. |
           |     V                                            | |
           +-on-----+--------------------------------------+--+-+
           |        |     .-.----------------------------. |    |
           |        |     V                              | |    |
           |        +--m----+-*-----------------------+--+-+    |
           |        |       |  .-,------------------. |    |    |
           |        |       |  V                    | |    |    |
           |        |       '------num--+------+----+-'    |    |
           |        |                   '--num-'           |    |
           |        +--e--max_sys_errors-------------------+    |
           |        +--r--max_record_size------------------+    |
           |        +--f--filename-------------------------+    |
           |        +-+--l--+--------------+-+-------------+    |
           |        | |     '-buffer_size--' |             |    |
           |        | '--i--+--------------+-'             |    |
           |        |       '-buffer_size--'               |    |
           |        '--t-----------------------------------'    |
           +-off------------------------------------------------+
           +-dump--filename-------------------------------------+
           +-flw--dump_file--output_file------------------------+
           '-fmt--dump_file--output_file------------------------'
 
>--------------------------------------------------------------><
 

Command Parameters

on

Use this parameter to start the DB2 trace facility. See the next section for information about the options for this parameter.

dump

After reproducing the error, dump the trace information to a file. The following command will put the information in the current directory in a file called db2trc.dmp:

   db2trc dump db2trc.dmp

Specify a file name with this parameter. The file is saved in the current directory unless the path is explicitly specified.

off

After the trace is dumped to a file, turn the trace off by typing:

   db2trc off

flw | fmt

After the trace is dumped to a binary file, confirm that it is taken by formatting it into an ASCII file. Use either the flw option (to sort by process or thread), or the fmt option (to list every event chronologically). For either option, specify the name of the dump file and the name of the output file that will be generated. For example:

   db2trc flw db2trc.dmp db2trc.flw

Starting a DB2 Trace

To use the trace facility, first turn it on using db2trc on. Unless instructed otherwise by DB2 Customer Service, use the command without options. The default trace option values are:

• mask = * (trace everything)

• max_sys_errors = -1 (collect all)

• max_record_size = 16KB

• Trace destination = -s (shared memory)

• Records to retain = -l (last)

• buffer_size = 64KB if the trace destination is shared memory, or 1MB if the trace destination is a file.

If instructed to specify options to tailor the trace, use the following options as directed by DB2 Customer Service:

-m mask

Specifies trace record types to focus the search. The mask variable consists of four one-byte masks separated by periods. The byte-masks act as a filter to accept or reject the trace record sent by DB2 for each event based on its ID. The four one-byte masks correspond to products, event types, components, and functions, respectively.

-e max_sys_errors

Limits the number of DB2 internal system errors the trace will hold to max_sys_errors.

-r max_record_size

Limits the size of trace records to max_record_size bytes. Longer trace records are truncated.

-f filename

Specifies trace buffer location in shared memory or a file.

-l [ buffer_size] | -i [buffer_size]

'-l' ("l" as in "lucky") specifies that the last trace records are retained (that is, the first records are overwritten when the buffer is full). '-i' specifies that the initial trace records are retained (that is, no more records are written to the buffer once it is full). Use either of these options to specify the buffer size.

-t

Includes time stamps. Applicable to UNIX environments only, where the logging of time stamps affects performance.

Examples

For additional information about db2trc, including trace examples, see the Troubleshooting Guide.

Usage Notes

The db2trc command must be issued several times to turn tracing on, produce a dump file, format the dump file, and turn tracing off again. The parameter list shows the order in which the parameters should be used.

[ DB2 List of Books | Search the DB2 Books ]