Statements and 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.

ON

If the component trace is off, the parmlib member turns on the trace. If the component trace is 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.

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

A head trace might 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 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.

Note: 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.

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 1 - 9999.
nnnnM: The buffer size in megabytes, where nnnn is a decimal number 1 - 2047.

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

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

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 that are separated by commas. An empty job list, JOBNAME(), turns off filtering by jobs. In the JOBNAME parameter, list all jobs to be traced; jobs that are specified for previous traces are not traced unless listed.

OPTIONS(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 that are 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.

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 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.

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 reduces tracing to a minimum if the head level is defined with MINOPS. All sublevel traces with the LIKEHEAD attribute 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 are also turned off. An installation-supplied application trace can have head level and sublevel traces, if specified in the CTRACE macro that defined the trace.

PRESET(DEFINE | DELETE)

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 overrides the tracing options set up at initialization and instead uses the options in the CTncccxx parmlib member with the PRESET.

The PRESET parameter is valid only in a parmlib member that is 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 is 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 that are 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.

DELETE

Deletes the existing preset.

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 that are 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 that is 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, or a job name.

Default: None

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.

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.
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 the WTRSTART parameter specifies WRAP or omits the parameter, the system uses only the primary extent or extents.

Default: WRAP

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.