DB2 10.5 for Linux, UNIX, and Windows

Tracing the CLI driver by using the db2trc on -cli command

You can trace the CLI function calls dynamically with the db2trc on -cli command.

About this task

The formatted DB2® trace file that is generated with the db2trc fmt -cli command is similar to that of the CLI trace. By using the db2trc on -cli command, you can:

Dynamically enable and disable the trace without having to restart the application.
Specify the trace output path and file name.
Trace a specific process ID or list of process IDs.
You can obtain the details of all statement handles that were allocated by the CLI driver prior to enabling the DB2 trace with the -dumpstmt option.
You can format the trace into separate text files that are based on the thread ID of a process if an existing directory is specified for the trace format command.

Important: Do not run the trace unless you must diagnose a problem. Tracing reduces the overall performance of your system.

Procedure

Enable the CLI trace by issuing one of the following commands:
- To trace the CLI driver activities into the trace memory buffer:
```
db2trc on -cli
```
- To trace the CLI driver activities into a binary trace dump file:
```
db2trc on -cli -f dumpFile
```
  where dumpFile is the name of the binary dump file. You can qualify the file name with the directory path, as shown in the following example:
```
db2trc on -cli -f c:\temp\clitrace\dump.file
```
  If you do not qualify the file name with the directory path, the file is generated in the path where you issue the db2trc command.
- To trace only one specific process ID:
```
db2trc on -cli -p pid
```
  To trace only one specific process ID to a file:
```
db2trc on -cli -p pid -f dumpFile
```
  To trace multiple specific process IDs:
```
db2trc on -cli -p pid,pid,...
```
  To trace multiple specific process IDs to a file:
```
db2trc on -cli -p pid,pid,... -f dumpFile
```
  where pid is the process ID of a CLI application, as shown in the following example:
```
db2trc on -cli -p 6860,6888 -f c:\temp\clitrace\dump.file
```
- To trace the CLI driver activities and obtain the details of all statement handles that were allocated by the CLI driver prior to enabling DB2 trace, issue one of the following commands:
```
db2trc on -cli -dumpstmt
db2trc on -cli -dumpstmt -f dumpFile
```
Run the application scenario that you want to investigate.
Turn off the tracing in one of the following ways.
- If you enabled the trace without specifying the -f dumpFile parameter, issue the following commands:
```
db2trc dump dumpFile
db2trc off
```
  where dumpFile is the name of the binary trace dump file. You can qualify the file name with the directory path.
- If you enabled the trace by specifying the -f dumpFile parameter, issue the following command:
```
db2trc off
```
Format the binary file into a CLI trace by issuing the following command:
```
db2trc fmt -cli CLItraceName
```
CLItraceName can be one of the following objects:
- The name of the formatted trace file that is to be created.
```
db2trc fmt –cli c:\temp\clitrace\dump.file clitrcfile.txt
```
- The name of the formatted trace file with the path name.
```
db2trc fmt –cli c:\temp\clitrace\dump.file c:\temp\clitrace\Clitrace.cli
```
- An existing directory that you have write permission for.
```
db2trc fmt –cli c:\temp\clitrace\dump.file c:\temp
```
If the CLItraceName directory exists and you have write permission to the directory, the trace is formatted into separate text files that are based on the thread ID of a process. If there is a directory with the same name as the CLItraceName value and you do not have write permission to the directory, an error is returned. The name of the trace files in the CLItraceName directory consists of p<pid>t<tid>.cli.