TRACE CT command (z/OS IRLM)

The z/OS® command TRACE CT 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

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

Data sharing scope: Member

Authorization

This command requires an appropriate level of operating system authority.

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

Syntax

Option descriptions

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. Traces INT, EXP, and XIT are ON by default. You cannot turn off traces INT and EXP. If you do not specify a subname on the TRACE command, the trace is performed on all subnames that you control. Specifying one subname restricts the traces to that trace plus the EXP and INT traces.

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

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. After you issue the TRACE ON command, the reports are accurate except for the two subname types, INT and EXT, which cannot be turned off.