2.19 pdclttrc (Acquire SQL trace dynamically)

Organization of this section
(1) Function
(2) Executor
(3) Format
(4) Options
(5) Rules
(6) Notes

(1) Function

The pdclttrc command acquires an SQL trace for a client executing SQL statements. The SQL trace information is output to the client.

You can determine the server name and process ID subject to acquisition of the SQL trace from the client's IP address and UAP identification information in the pdls -d prc command's execution results.

(2) Executor

HiRDB administrator

(3) Format

 pdclttrc [-s server-name] [-p process-ID] [-e] [-l PDUAPREPLVL-value]

        [-m maximum-length-of-?-parameter-and-search-data]

        [-n output-operation-codes-count] [-o SQL-trace-file-size]

(4) Options

(a) -s server-name ~<identifier> ((1-8))

Specifies the name of the server to which the client subject to acquisition of the SQL trace is connected. Specify the name of the single server or a front-end server.

When this option is omitted, the command acquires an SQL trace for all processes connected to all HiRDB servers (single or front-end servers).

For a single server, specifying an invalid server name does not result in an error.

(b) -p process-ID ~<unsigned integer> ((1-10))

Specifies the process ID of the server to which the client subject to acquisition of the SQL trace is connected.

For a HiRDB parallel server configuration, this option must be specified together with the -s option. For a HiRDB single server configuration, the -s option is optional.

When this option is omitted, the command acquires an SQL trace for all processes connected to the single server or front-end server.

(c) -e

Stops acquisition of SQL traces.

Rules
  1. When the connection has been broken or SQL trace acquisition has stopped because the -n option value was reached, specifying this option does not result in an error.
  2. If only this option is specified, the command stops acquisition of SQL traces for all processes that are connected to all HiRDB servers (single or front-end servers).
  3. When this option is specified together with the -s option, the command stops acquisition of the SQL traces for all processes connected to the specified server.
  4. When this option is specified together with the -p option, the command stops acquisition of the SQL trace for the specified process.
  5. A stop request to the client is executed by the next SQL statement. If an internal operation is executed in the meantime, SQL trace information may be output even after its acquisition is stopped by the -e option. For details about internal operations, see the operation codes in 14.4.3 Record formats of DAT-format files.
(d) -l PDUAPREPLVL-value

To output UAP statistical report information in addition to SQL trace information, specifies the UAP statistical report information that is to be output (value of the PDUAPREPLVL client environment definition). For details about the specification values and information output destination, see the HiRDB Version 9 UAP Development Guide.

When the inter-process memory communication facility is used, this option is ignored, if specified. The command displays the messages during process-to-process memory communication.

When this option is specified together with the -e option, this option is ignored.

(e) -m maximum-length-of-?-parameter-and-search-data ~<unsigned integer> ((4-32008))

Specifies in bytes the maximum length of the search data and ? parameter information that is to be output to the SQL trace.

This option provides the same function as when INOUT is specified in the PDPRMTRC client environment definition.

When this option is specified together with the -e option, this option is ignored.

(f) -n output-operation-codes-count ~<unsigned integer> ((0-10000)) <<0>>

Specifies the number of operation codes to be output to the SQL trace file. SQL trace acquisition stops when information has been output for the specified number of operation codes.

When this option is omitted, the command outputs SQL trace information until a pdclttrc command with the -e option specified is executed or until DISCONNECT is executed.

When this option is specified together with the -e option, this option is ignored.

(g) -o SQL-trace-file-size ~<unsigned integer> ((0,4096-2000000000)) <<32768>>

Specifies in bytes the size of the SQL trace file.

When 0 is specified, the maximum file size is assumed.

When this option is specified together with the -e option, this option is ignored.

(5) Rules

  1. The pdclttrc command can be executed only when HiRDB is running.
  2. The pdclttrc command must be executed at the server machine that contains the single server or where the system manager is located.
  3. The pdclttrc command acquires a SQL trace only if the connected client version is 07-01 or later.
  4. When the pdclttrc command is executed, it starts acquisition of the SQL trace for the SQL statement that is currently being processed; however, the command does not display the following information for this SQL statement:
    • SQL start time
    • SQL runtime that is displayed when PDSQLEXECTIME=YES is specified in the client environment definition
    • SQL runtime and differential information, which are output to the UAP statistical report for each SQL statement
  5. The SQL trace file and UAP statistical report are output to the directory specified in the PDCLTPATH client environment definition. When PDCLTPATH is omitted, the SQL trace file is output to the directory that is the current directory for UAP execution.
    If both the -l option and the PDREPPATH client environment definition are specified, the SQL trace file is output to the directory specified in PDREPPATH.
    The following table shows the output destination of an SQL trace file when the -l option is specified:
    PDCLTPATHPDREPPATHOutput destination of SQL trace file
    OmittedOmittedCurrent directory
    SpecifiedOmittedDirectory specified in PDCLTPATH
    OmittedSpecifiedDirectory specified in PDREPPATH
    SpecifiedSpecified
  6. When the -l option is specified, the command does not output information from prior to the command's execution because the information for each UAP statement begins with the beginning of the command.
  7. For details about the names of the trace files produced during command execution, see SQL tracing in the HiRDB Version 9 UAP Development Guide.
  8. If an SQL trace has already been acquired at the client, the pdclttrc command is ignored, if executed.
  9. If the pdclttrc command is executed while another pdclttrc command is executing, a message is displayed indicating that an SQL trace is being acquired for the current process.
  10. The output format for SQL traces acquired by this command depends on the value of the PDSQLTRCFMT client environment variable. Output format 2 is used when PDSQLTRCFMT is omitted.

(6) Notes

  1. If connection is broken for a reason such as a communication error or DISCONNECT, or if SQL trace information has been output for the number of operation codes specified in the -n option, SQL trace acquisition terminates automatically.
  2. The following are the pdclttrc command's return codes:
    0: Normal termination
    8: Error termination