Statements/parameters for CTncccxx

To determine if the component to be traced allows the following parameters, see component traces in z/OS MVS Diagnosis: Tools and Service Aids.

TRACEOPTS

Specifies the component tracing options for an MVS™ component or an application.

WTRSTART(membername){WRAP|NOWRAP}

Identifies a member containing source JCL for a started task that the system uses to start the component trace external writer and to open the data sets that the writer uses.

You must also specify the WTR parameter.

WRAP or NOWRAP

If you specify WRAP, when the system reaches the end of the data set or group of data sets, it writes over the oldest data at the start of the data set or the start of the first data set. If you specify NOWRAP, the system stops writing to the data set or sets when the data set or sets are full.

If the WTRSTART parameter on the CTncccxx parmlib member or TRACE CT command specifies NOWRAP, the system uses the primary and secondary extents of the data set or sets. If the WTRSTART parameter specifies WRAP or omits the parameter, the system uses only the primary extent or extents.

Default: WRAP

SUB(subname)

Identifies a sublevel trace for a component or application with multiple traces. The subname is defined by the component or installation-supplied application.

If subname is a head level, all of the head's sublevel traces that are defined with a LIKEHEAD=YES parameter inherit the options specified in this parmlib member. Therefore, the options you specify for a head level can affect many sublevel traces.

If you specified the SUB parameter on the parmlib member to activate these trace options, the operator should not specify the SUB parameter on the TRACE CT command.

SUB(subname) cannot be specified in a parmlib member activated during system initialization.

The SUB parameter must be followed by a PRESET, ON, OFF, or LIKEHEAD parameter.

Value Range: Specify the sublevel trace as it was defined through the CTRACE macro as:

A name
An ASID
A job name.

Default: None.

PRESET(DEFINE | DELETE)

PRESET(DEFINE) specifies that the component trace options established in the CTncccxx member are to be remembered until the component trace is defined. When a CTRACE macro later defines the trace, the preset information is used to set the options.

Use the PRESET parameter to set up the trace options in anticipation of a job entering the system or an address space being run. Later, when the CTRACE macro is invoked in the job or address space, the system will override the tracing options set up at initialization and instead use the options in the CTncccxx parmlib member with the PRESET.

The PRESET parameter is valid only in a parmlib member specified on the TRACE CT command; the PRESET parameter is ignored if specified from the CTRACE macro.

To use the preset options, a sublevel trace (SUB) can be defined as either ASID or JOBNAME. If there are both ASID and JOBNAME presets, the system uses only the ASID preset.

Once the information established through the preset has been used for a trace, the preset no longer exists.

If you specified a valid preset and then a CTRACE macro is issued with a PARM option, the system ignores the information in the parmlib member specified by the CTRACE macro and, instead, uses the preset information. But, if your preset was not valid, the system will issue an error message and then proceed to process the trace options specified on the CTRACE macro; the preset information is then deleted.

You can change the preset options by using the TRACE CT command with the PARM parameter and specifying PRESET(DEFINE) in the parmlib member.

PRESET(DELETE) deletes the existing preset.

ON

If the component trace is currently off, the parmlib member turns the trace on. If the component trace is currently on and can be changed, the parmlib member changes the trace. An installation-supplied application trace can be changed if the CTRACE macro that defined the trace contained a MOD=YES parameter.

When a head trace that was defined with HEADOPTS=YES is turned on, all sublevel traces currently defined as LIKEHEAD are also turned on. An installation-supplied application trace can also have head and sublevel traces, if specified in the CTRACE macro that defined the trace.

Whenever a trace that has sublevel traces is changed, all sublevel traces currently in the LIKEHEAD state will also be changed. Therefore, a change may cascade down a number of levels.

A head trace may have been defined so that it is not allowed to be changed (HEADOPTS=NO on the CTRACE macro). If this is the case, the trace is really just a place holder for options for other traces.

ASID(asid-list)

Specifies the address space identifiers (ASIDs) of address spaces to be used as a filter for tracing. Events in these ASIDs are to be recorded by the component trace.

Value Range: A list of 0 to 16 hexadecimal ASIDs separated by commas. An empty ASID list, ASID(), turns off filtering by address spaces. In the ASID parameter, list all address spaces to be traced; address spaces specified for previous traces will not be traced unless listed.

JOBNAME(jobname-list)

Specifies the names of jobs to be used as a filter for tracing. Events in these jobs are to be recorded by the component trace.

Value Range: A list of 1 to 16 job names separated by commas. An empty job list, JOBNAME(), turns off filtering by jobs. In the JOBNAME parameter, list all jobs to be traced; jobs specified for previous traces will not be traced unless listed.

BUFSIZE(nnnnK | nnnnM)

Specifies the size, in kilobytes (K) or megabytes (M), of the trace buffer you want the system to use.

Value Range:

nnnnK: The buffer size in kilobytes, where nnnn is a decimal number from 1 to 9999.
nnnnM: The buffer size in megabytes, where nnnn is a decimal number from 1 to 2047.

When the size is not specified, the system uses the component-defined default or, for some components, the size specified in a TRACE CT command.

The size specified for an installation-supplied application trace must be within the range specified on the CTRACE macro for the trace; see the programmer for the size value.

OPTIONS

Specifies component-specific options for tracing.

For the component options that support component tracing, see the topic on component trace in z/OS MVS Diagnosis: Tools and Service Aids.

Value Range: A list of component-specific options with each option enclosed in quotation marks and the options separated by commas. For example:

OPTIONS('optionA','optionB','optionN')

The options for some IBM-supplied component traces can be changed while the trace is running; to change the options for others, stop the trace and restart it with the new options. An installation-supplied application trace, defined with MOD=YES in the CTRACE macro, can be changed while running.

The options for a head level defined with HEADOPTS=NO cannot be changed. When a head level that was defined with HEADOPTS=YES is changed, all of the sublevel traces currently in LIKEHEAD status will also be changed. Therefore, a change may cascade down a number of levels.

Omit OPTIONS to allow the component to use its default options.

WTR(membername|DISCONNECT)

Connects or disconnects the component trace external writer and the trace. The member name identifies the member that contains the source JCL that invokes the external writer. The membername in the WTR parameter must match the membername in the WTRSTART parameter.

WTR(DISCONNECT) disconnects the writer and the trace. The component continues tracing and placing the trace records in the address-space buffer, but stops passing trace records to the external writer.

You must also specify a WTRSTART or WTRSTOP parameter to start or stop the writer.

OFF

The system is to stop tracing for the component. If the component is connected to a component trace external writer, the system forces an implicit disconnect.

Some components do not stop tracing completely but reduce the tracing activity to the minimum required for serviceability data in a dump. An installation-supplied application trace will reduce tracing to a minimum if the head level is defined with MINOPS. All sublevel traces with the LIKEHEAD attribute will also reduce tracing to the minimum. Component trace writes a message to the operator when tracing is reduced to the minimum.

A head level defined with HEADOPTS=NO cannot be turned off.

When a head level defined with HEADOPTS=YES is turned off, all sublevel traces currently defined as LIKEHEAD will also be turned off. An installation-supplied application trace can have head level and sublevel traces, if specified in the CTRACE macro that defined the trace.

LIKEHEAD

Specifies that the trace specified in the SUB parameter is to use the options that are defined to that sublevel trace's head level.

If you use the TRACE CT command to change a trace that is currently ON or OFF to LIKEHEAD, be aware of the following:

The attributes of the sublevel trace must match the head level trace.
The sublevel trace inherits the state (ON or OFF) and the options (ASID, JOBNAME, OPTIONS, and BUFSIZE) of the head level.
The head level must have been defined with HEADOPTS=YES.

Component traces are defined by the IBM-supplied component; for components that use heads and subheads, see information about the component trace in z/OS MVS Diagnosis: Tools and Service Aids. Application traces are defined by the application using the CTRACE macro; for more information, see the documentation for the application.

WTRSTOP(jobname)

Identifies the name of the job for a currently running component trace external writer that the system is to stop. The system also closes the data sets the writer used. The jobname is either:

Member name, if the source JCL is a procedure
Job name, if provided on a JOB statement within the source JCL

You must also specify the WTR parameter. Otherwise, traces connected to the writer remain connected after the system stops it.