Tracing the CLI driver by using the db2cli.ini file

To turn on a CLI trace, you can enable a set of CLI configuration keywords in the db2cli.ini file.

About this task

Procedure

To obtain a CLI trace:

  1. Update the db2cli.ini file with CLI configuration keywords.

    You can update the db2cli.ini file by either manually editing the db2cli.ini file or by issuing the UPDATE CLI CFG command.

    • To manually edit the db2cli.ini file:
      1. Locate the db2cli.ini file. For more location of the db2cli.ini file, see db2cli.ini initialization file.
      2. Open the db2cli.ini file in a plain text editor.
      3. Add the following section to the db2cli.ini file or, if the [COMMON] section exists, append the CLI trace keywords in the following example:
        [COMMON]
        Trace=1
        TracePathName=path
        TraceComm=1
        TraceFlush=1
        TraceTimeStamp=1
        
        If you use the TracePathName keyword, ensure that the path that you specify exists and that it has global read and write permission.
        Note:
        • Because CLI trace keywords are in the [COMMON] section of the db2cli.ini file, their values apply to all database connections that are made through the CLI driver.
        • CLI trace keywords are not case-sensitive. However, path and file name keyword values might be case-sensitive on some operating systems, such as UNIX operating systems.
        • If a CLI trace keyword in the db2cli.ini file is invalid, the CLI trace utility ignores the CLI trace keyword. If you specify a valid CLI keyword with an invalid value, the default value for that trace keyword is used instead.
        • Unless you set the TraceRefreshInterval keyword, CLI trace keywords are read from the db2cli.ini file only once, at application initialization time. If you set the TraceRefreshInterval keyword, the Trace and TracePIDList keywords are reread from the db2cli.ini file at the specified interval and applied, as appropriate, to the currently running application.
      4. Add at least one blank line at the end of the file. Addition of a blank line prevents some parsing errors.
      5. Save the file.
    • To use the UPDATE CLI CFG command to update the CLI configuration keywords:
      1. Issue the following commands:
        db2 UPDATE CLI CFG FOR SECTION COMMON USING Trace 1
        db2 UPDATE CLI CFG FOR SECTION COMMON USING TracePathName path
        db2 UPDATE CLI CFG FOR SECTION COMMON USING TraceComm 1
        db2 UPDATE CLI CFG FOR SECTION COMMON USING TraceFlush 1
        db2 UPDATE CLI CFG FOR SECTION COMMON USING TraceTimeStamp 3
        If you use the TracePathName keyword, ensure that the path that you specify exists and that it has global read and write permission.
      2. Verify the CLI trace keywords in the db2cli.ini configuration file by issuing the following command:
        db2 GET CLI CFG FOR SECTION COMMON
      Note:
      • The IBM® Data Server Driver Package and IBM Data Server Driver for ODBC and CLI installations do not contain the Db2® command line processor. To change the settings of trace configuration keywords, you can modify the db2cli.ini file manually.
  2. To enable the CLI trace, restart the application. If you are tracing a CLI stored procedure, restart the Db2 instance

    The db2cli.ini file is read only on application initialization, unless the TraceRefreshInterval keyword is set.

  3. Capture the error:
    1. Run the application until the error is generated. To reduce the trace size, if possible, run only the application that is required to replicate the problem.
    2. Terminate the application.
  4. Disable the CLI trace setting in one of the following ways:
    • Set the Trace keyword to a value of 0 in the [COMMON] section of the db2cli.ini file.
    • Issue the following command:
      db2 UPDATE CLI CFG FOR SECTION COMMON USING Trace 0
  5. To disable the tracing, restart the application.

Results

The CLI trace files are written to the path that you specified for the TracePathName keyword. The file names have a format of ppidttid.cli. The pid value is the process ID that the operating system assigns, and the tid value is a numeric counter (starting at 0) for each thread that is generated by the application process. An example of the file name is p1234t1.cli.

What to do next

The CLI trace facility has significant effect on performance of all applications currently running on the instance. Therefore, it is important to turn off the CLI trace after the required information is gathered.

If you are working with IBM Service to diagnose a problem, gather all of the files that are present in the trace path.