TRACE CT command (z/OS IRLM)

The TRACE CT command starts, stops, or modifies a diagnostic trace for the internal resource lock manager (IRLM) of Db2.

IRLM does not support all the options available on the TRACE command.

Environment for TRACE CT

This command can be issued only from a z/OS® console.

Data sharing scope: Member

Authorization for TRACE CT

This command requires an appropriate level of operating system authority.

The syntax diagram and option descriptions for this command are purposely incomplete.

Syntax for TRACE CT

Option descriptions for TRACE CT

CT

Specifies the component trace. (Do not use other trace options available on the z/OS TRACE command).

WTRSTART= parmlibmem

Identifies the member that contains source JCL. That JCL executes the CTRACE writer and defines the data set to which it writes the trace buffers. This member can be a procedure cataloged in SYS1.PROCLIB or a job.

WRAP: Specifies that when the system reaches the end of the group of data sets, it writes over the oldest data at the beginning of the first data set in the group. The system uses only the primary extents of the data sets.
NOWRAP: Specifies that the system stops writing to the data sets when they are all full. The system uses the primary and secondary extents of the data sets.

WTRSTOP= jobname

Stops the CTRACE writer for a trace that is running. The system also closes the data sets that the writer used.

jobname identifies the trace, either by:

Member name, if the source JCL is a procedure
Job name, if that appears on a JOB statement in the source JCL

ON

Turns on the trace.

COMP= irlmssnm

Gives the IRLM subsystem name.

SUB= subname

Specifies the type of sublevel trace. Start of change

Traces INT, EXP, RLE, and XIT are ON by default. You cannot turn off traces INT, EXP, or RLE. End of change

If you do not specify a subname type on the TRACE command, the trace is performed on all subname types that you control. Specifying one subname type restricts the traces to that trace plus the EXP, INT, and RLE traces.

Start of change If you specify a subname type on the TRACE command, that subname type is not affected by commands that do not specify that subname type until IRLM is recycled. End of change

Use:: To trace:
DBM: Interactions with the identified DBMS
EXP: Any exception condition
INT: Member and group events outside normal locking activity
SLM: Interactions with the z/OS locking component
XCF: All interactions with z/OS cross-system coupling services
XIT: Only asynchronous interactions with the z/OS locking component

OFF

Turns off the trace. If IRLM is connected to a CTRACE writer for the component trace, the system disconnects it.

Usage notes for TRACE CT

Include the IRLM load module in the z/OS link list: This command uses z/OS component trace services. Include the IRLM load module DXRRL183, which contains a routine for stopping and starting, in the z/OS link list.

Displaying a trace: To display a trace, use the z/OS DISPLAY command:

D TRACE,COMP=IRLM

The z/OS DISPLAY TRACE command output is incorrect for IRLM unless you use TRACE CT commands to inform z/OS of the TRACE status. IRLM initializes it's own traces and writes them in CTRACE format, but IRLM has no interface to z/OS to inform it of the status. If you want to know the true status of the traces without using TRACE CT commands to inform z/OS, use the MODIFY irlmproc,STATUS,TRACE command.

Monitoring a trace: To monitor a trace, use the z/OS MODIFY irlmproc,STATUS,TRACE command.

Setting the number of trace buffers: To set the number of trace buffers used by traces, use the z/OS MODIFY irlmproc,SET command.

Sample procedure for the CTRACE writer: This procedure identifies the data set to which the next sample procedure writes data. The external trace writer must be executed at the same or higher dispatch priority as IRLM. This allows the I/O to keep up with the filling of the trace buffers.

//CTWTR    PROC
//         EXEC PGM=ITTTRCWR
//TRCOUT01 DD   DSNAME=SYS1.WTR1,DISP=OLD
//TRCOUT02 DD   DSNAME=SYS1.WTR2,DISP=OLD

Sample procedure to start and stop a DBM trace to the CTRACE writer: These commands start and stop an IRLM DBM trace. The trace data is written to an external writer data set that is identified in procedure CTWTR.

TRACE CT,WTRSTART=CTWTR
TRACE CT,ON,COMP=IRLM,SUB=(DBM)
⋮
  (z/OS asks for a reply)
⋮
R 15,WTR=CTWTR,END
TRACE CT,OFF,COMP=IRLM,SUB=(DBM)
⋮
  (Wait to make sure trace buffers are externalized.)
TRACE CT,WTRSTOP=CTWTR

Sample procedure to start and stop traces in wrap-around mode: Traces captured in this procedure are saved in a limited number of buffers that are provided by IRLM. Each buffer is reused when the previous buffer is filled. To start the trace in this wrap-around mode, enter the following commands:

TRACE CT,ON,COMP=IRLM
⋮
  (z/OS asks for a reply)
⋮
R 15,END
⋮
TRACE CT,OFF,COMP=IRLM

Impact of setting TRACE CT,ON: Each active subname type requires up to 0.7 MB of ECSA. Because IRLM initializes its own traces when it starts, the DISPLAY TRACE command shows that all traces are off. Start of change After you issue the TRACE CT,ON command, the reports are accurate except for the three subname types, INT, EXT, and RLE, which cannot be turned off. End of change

Start of change Turning off traces that are enabled by TRACE=YES in the irlmproc: IRLM initializes its own traces and has no interface to inform z/OS of the status. The TRACE CT,OFF command does not drive IRLM because the z/OS status is that the traces are off. To turn off a trace, first issue the TRACE CT,ON command and issue a reply. Then issue the TRACE CT,OFF command. End of change