Parameters

The display tells the operator to use the DISPLAY TRACE command to obtain status for system and component trace.

nnnK

The amount of preferred, central storage in K bytes set aside for system trace table entries for each processor. You can specify for nnn any decimal number from 1 to 999. As the minimum trace table size for a processor is 1M, any request between 1-999K is interpreted as a request for 1M.

nnnM

The amount of preferred, central storage in M bytes set aside for system trace table entries for each processor. You can specify for nnn any decimal number from 1 to 999.

nG

The amount of preferred, central storage in G bytes set aside for system trace table entries for each processor. You can specify for n any decimal number from 1 to 9.

Remember: Supply a reasonable value to the nnnM or nG parameter after considering the available central storage and the actual storage required for system trace. Supplying a large value for nnnM or nG might cause a shortage of pageable storage in the system.

If you omit the nnnM or nG parameter, the system assumes 1M for each processor, or the size established by the last TRACE command that specified a table size during the IPL. If the value specified exceeds a system determined safe amount, the command will be rejected and message IEA135I will display the maximum amount allowed per processor. The maximum value depends on real frame usage at the time the TRACE command is issued, and can vary each time the TRACE command is issued.

BR=ON or OFF

The system is to turn on or turn off the branch tracing function of system trace. The address space and explicit tracing functions remain on as long as system trace remains on. If you omit this parameter, the system assumes that the status of branch tracing remains unchanged.

BR=ON is intended for use in system software problem determination and diagnosis situations only. Branch tracing consists of tracing these four types of branches:

• Branch and stack (BAKR)
• Branch and link (BALR)
• Branch and save (BASR)
• Branch and save and set mode (BASSM)

Restriction: You cannot specify the BR= parameter if you specify ST=OFF.

Attention: Turning branch tracing ON tends to affect your system performance and use very large amounts of storage. Do not use branch tracing as the default for system tracing on your system. Only use it for short periods of time to solve a specific problem. The default system tracing does not include branch instructions.

You can run the SYSTRACE_BRANCH check to make sure that your installation does not run with BR=ON for longer than desired. See SYSTRACE_BRANCH in IBM Health Checker for z/OS User's Guide.

MODE=ON or OFF

The system is to turn on or turn off the mode tracing function of system trace. Mode tracing consists of recording occurrences of entering and leaving 64-bit mode. The specification of branch tracing and mode tracing is separated. Therefore, the BR= parameter will not have any effect on mode tracing.

Restriction: You cannot specify the MODE= parameter if you specify ST=OFF.

Attention: Turning mode tracing ON tends to affect your system performance and use very large amounts of storage. Do not use mode tracing as the default for system tracing on your system. Only use it for short periods of time to solve a specific problem. The default system tracing does not include mode tracing.

You can run the SYSTRACE_MODE check to make sure that your installation does not run with MODE=ON for longer than desired. See SYSTRACE_MODE in IBM Health Checker for z/OS User's Guide.

BUFSIZE|BUFSIZ=nnnnnK or nnnnnM or nnnG

The system is to specify the total storage for all trace buffers in kilobytes (K), megabytes (M), or gigabytes (G). The size specified is divided by the number of installed CPUs and rounded up to the next megabyte to arrive at trace storage required per CPU.

Note: The total trace buffer size allocated can exceed the BUFSIZE specified in the TRACE command because of this rounding.

Remember: Supply a reasonable value to the BUFSIZE parameter after considering the available central storage and the actual storage required for system trace. Supplying a large value for BUFSIZE can cause shortage of pageable storage in the system.

OFF

The system is to stop system trace and free the system trace table. The system does not terminate the TRACE address space. Therefore, if you start system trace again while the TRACE address space is still active, the on or off status of the different system trace functions and the size of the system trace table return to the values they had the last time system trace was on.

nnnK

The master trace table size you want the system to use. You can specify for nnn any decimal number from 16 to 999. If a master trace table already exists, this new table replaces it. If you omit this parameter, the system assumes a table size of 24K.

OFF

The system is to stop master trace.

WTRSTART=membername

Identifies the name of the member that contains the source JCL that invokes a component trace external writer. The membername is 1 to 7 characters. The system also opens the data sets the writer uses. The member can be a SYS1.PROCLIB cataloged procedure or a job. Many installations use a cataloged procedure in SYS1.PROCLIB.

After you enter a TRACE CT,WTRSTART command, you should turn the trace on and connect the writer with a WTR parameter in the reply for a TRACE CT command or in a parmlib member, if specified.

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.

WTRSTOP=jobname

Identifies the name of the job for a currently running component trace external writer that the system is to stop. The jobname is 1 to 7 characters. 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

If you specify or default FLUSH, the writer will stop when it has finished writing out its current buffers. If you specify NOFLUSH, the writer stops immediately.

Before you enter a TRACE CT,WTRSTOP command, you must either:

• Turn the trace off, or
• Disconnect the component trace external writer from the trace leaving the trace on.

To disconnect the external writer while leaving the trace on enter the TRACE CT,ON command with WTR=DISCONNECT in the reply or in a CTncccxx parmlib member, if specified.

If the trace is not turned off or disconnected from the writer, message ITT121I informs the operator of the condition and the writer will not stop.

ON

If the component trace is currently off, a TRACE CT,ON command turns it on. If the component trace is currently on and can be changed, a TRACE CT,ON command changes the trace options. An installation-supplied application trace can also have head level and sublevel traces, if specified in the CTRACE DEFINE 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 DEFINE macro). If this is the case, the trace is really just a place holder for options for other traces.

nnnnK

nnnnM

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

nnnnK is the buffer size in kilobytes, where nnnn is a decimal number from 1 to 9999. nnnnM is 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 the size specified in a CTncccxx parmlib member.

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

OFF

The system is to turn off tracing for the component. If the component is connected to a component trace external writer, the trace will be implicitly disconnected from the writer.

Some components do not turn tracing completely off. Instead, they reduce the tracing activity to the minimum required for serviceability data in a dump. If the CTRACE DEFINE macro that defined the trace specified the MINOPS parameter, tracing is reduced to a minimum and component trace writes a message to the operator.

If a component level trace has sublevel traces that are defined with the LIKEHEAD parameter on the CTRACE DEFINE macro, the sublevel traces will either be reduced to the minimal tracing or turned off, in the same manner as their head level component trace.

COMP=name

Identifies the component trace affected by the command. name is the external name for the component trace; it is provided for an IBM-supplied component and must be provided by a system programmer for an installation-supplied application trace. This parameter is required.

SUB=(subname)

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

The SUB parameter is limited to a single subname; multiple subnames are not supported.

If the sublevel trace name contains any national characters ($ # @), you must enclose the name in quotation marks. Otherwise, quotation marks are not required. In all cases you may specify the alphabetic characters in upper or lower case.

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 the reply to this command. Therefore, the options you specify for a head level can affect many sublevel traces.

Omitting the SUB parameter for a head level that is defined with HEADOPTS=YES affects all sublevel traces with the LIKEHEAD attribute.

PARM=mem

Identifies a parmlib member that contains the options to be used for tracing. Using a parmlib member allows the operator to initiate the trace, change it, or stop it without a message prompting for options.

Any option specified on the TRACE command overrides the option specified in the parmlib member.