The requirements for the caller are:

An application using component trace must have an installation-written start/stop exit routine to start, stop, or modify tracing for the application.

None.

After the caller issues the macro, the system might use some registers as work registers or might change the contents of some registers. When the system returns control to the caller, the contents of these registers are not the same as they were before the caller issued the macro. Therefore, if the caller depends on these registers containing the same value before and after issuing the macro, the caller must save these registers before issuing the macro and restore them after the system returns control.

The caller must ensure that register 13 points to a standard 72-byte save area.

All component traces use system resources and will have some impact on performance. You should evaluate the impact of using either a single trace or multiple traces and determine which trace will provide the information you need with the least effect on performance. For information about multiple and single traces, see z/OS Problem Management

The standard form of the CTRACE macro is written as follows:

The parameters are explained as follows:

DEFINE

DELETE

The required parameter that either defines the application to or deletes the application from component trace.

When you specify DEFINE:

• You must specify NAME.
• You cannot specify DELSUBS or IFNOSUBS.

All other parameters are optional with DEFINE.

When an application is using multiple traces, the application must issue CTRACE DEFINE separately for each trace.

When you specify DELETE:

• You must specify NAME.
• SUB, DELSUBS, IFNOSUBS, RSNCODE, RC, COM, and MF are optional parameters.

You cannot specify any other parameters with DELETE.

,NAME=name

The required parameter that specifies the name of the application or head node to be defined or deleted. The name must begin with an alphabetic or national character and can contain up to eight alphanumeric or national characters. The first three letters must not be SYS because SYS is reserved for IBM® use. NAME is required for both DEFINE and DELETE.

The operator uses this name on the TRACE CT command (COMP parameter), and IPCS uses this name on the CTRACE subcommand (COMP parameter).

,STARTNAM=sname

Specifies the name of the application's start/stop exit routine. This routine receives control to start, stop, or modify tracing for the application. The application must have at least one start/stop routine. In the case of multiple traces, the application might have a start/stop routine for the head node and for each sublevel trace.

This routine must be a reentrant load module in the LNKLST or LPA.

You must code STARTNAM whenever you code CTRACE DEFINE, unless you code HEADOPTS=NO with HEAD=YES. If you code HEADOPTS=NO with HEAD=YES, STARTNAM is not valid.

,DISPNAM=dname

Specifies the name of the application's display exit routine. This routine receives control to provide status information about the component trace for the DISPLAY TRACE operator command.

This routine must be a reentrant load module in the LNKLST or LPA.

You may code DISPNAM whenever you code CTRACE DEFINE, unless you code HEADOPTS=NO with HEAD=YES. If you code HEADOPTS=NO with HEAD=YES, DISPNAM is not valid.

,PARM=parm

,PARM=NOPARM

Specifies the name of a parmlib member that contains the options to be used for tracing. A parmlib member specified on the CTRACE macro can contain tracing options for only one trace. Consult z/OS MVS Initialization and Tuning Reference for information on how to set up one or more component trace (CTncccxx) parmlib members.

The default is PARM=NOPARM.

,ASIDS=YES

,ASIDS=NO

Allows you to request trace filtering by ASIDs. A single trace that uses multiple address spaces can use this parameter as a filter to ensure that a trace is done only in certain address spaces. With ASIDS=YES, you can specify up to 16 ASIDs in a parmlib member on the PARM parameter, or the operator can specify up to 16 ASIDs. With ASIDS=NO, which is the default, neither you nor the operator can request trace filtering by ASIDs.

,JOBS=YES

,JOBS=NO

Allows you to request trace filtering by JOBNAMEs. With JOBS=YES, you can specify up to 16 JOBNAMEs in a parmlib member on the PARM parameter, or the operator can specify up to 16 JOBNAMEs. With JOBS=NO, which is the default, neither you nor the operator can request trace filtering by JOBNAMEs.

,MINOPS=options

,MINOPS=NONE

Specifies a list of user-defined options that are in effect when the trace is off or no other options are specified. These options cannot be turned off by the operator. The character string for the options list must not exceed 255 bytes. The individual options must be separated by commas. See z/OS Problem Management for information about planning and setting up user-defined options for your application. The default is MINOPS=NONE.

,MOD=NO

,MOD=YES

Specifies whether an application's trace must be stopped before changes are made to the application's tracing options. If you code MOD=YES, you allow the tracing options to be modified without stopping the trace. The default is MOD=NO.

,FMTTAB=fmtabs

,FMTTAB=NONE

Specifies the name of the load module that contains the CTRACE format table for the application. Use the ITTFMTB macro, described in z/OS MVS Programming: Authorized Assembler Services Reference EDT-IXG to create this CTRACE format table. See z/OS MVS IPCS Customization for further details about how to create a CTRACE format table.

The default,FMTTAB=NONE, specifies that IPCS is not to format the trace.

Note that specifying either the FMTTAB=fmtabs and USERDATA=userdata parameters cause information to be placed in the SQA. If SQA is not dumped, the information supplied by CTRACE DEFINE will not enable formatting to proceed. You may supply a CTRACE statement in parmlib member BLSCUSER to enable formatting to commence in this situation, but the buffer find routine supplied by your component will be supplied with userdata of zeros.

,USERDATA=userdata

,USERDATA=NOUSERDATA

Specifies an optional 16-byte input/output area used by the application to contain any data that it wants to associate with this trace. When control is passed to the trace's start/stop routine, this user data field is passed in the CTSS. Similarly, the user data field is passed in the CTXI to the trace's IPCS exit routines. Suggested uses include placing the address (and optionally, the ALET) of either of the following into this field:

• The application's control information
• The application's first trace buffer.

Note that specifying either the FMTTAB=fmtabs and USERDATA=userdata parameters cause information to be placed in the SQA. If SQA is not dumped, the information supplied by CTRACE DEFINE will not enable formatting to proceed. You may supply a CTRACE statement in parmlib member BLSCUSER to enable formatting to commence in this situation, but the buffer find routine supplied by your component will be supplied with userdata of zeros.

,HEAD=NO

,HEAD=YES

When using multiple traces, use this parameter to specify whether the trace you are defining is a head node. If you specify HEAD=YES, you can define sublevel traces (SUB parameter) on subsequent invocations of CTRACE DEFINE that share the options, attributes, and state of this head node.

If you specify both HEAD=YES and SUB=sub on the same invocation of CTRACE DEFINE, both of the following are true:

• The trace you are defining is a head node for sublevel traces to be defined on subsequent invocations of CTRACE DEFINE.
• The trace you are defining is a sublevel trace for a head node that was defined on a previous invocation of CTRACE DEFINE.

If you specify HEAD=NO (or take the default), you cannot define sublevel traces under this trace.

,HEADOPTS=NO

,HEADOPTS=YES

Specifies that the application supports options for the head node that is being defined. This parameter is valid only if you specify HEAD=YES.

When you specify HEADOPTS=YES, you can define sublevel traces on subsequent invocations of CTRACE DEFINE with the LIKEHEAD parameter and those traces will have the same options, attributes, and state as the HEAD. When any of the options or the state of the head are changed, all of the sublevel traces that are defined LIKEHEAD are also changed.

If you specify HEADOPTS=YES, you must specify a start/stop routine.

If you specify HEADOPTS=NO, you define a head node whose sublevel traces will be independent of the head node. You will not be able to turn on the trace at the head node, but only at the sublevels. Consequently, if HEADOPTS=NO, you cannot specify a start/stop routine.

HEADOPTS=NO is the default.

,SUB=subname

,SUB=NOSUB

When using multiple traces, use this parameter to specify that the trace you are defining is a sublevel trace, and specifies the name of the sublevel trace. Specify a sublevel trace name in one of the following ways:

• A 1- to 18-character name that begins with a letter, A-Z, or the characters $, #, or @ and consists of a combination of the characters A-Z, 0-9, and the characters $, #, and @. If you enclose the name in quotation marks, you can also use lowercase letters, a-z, and the underscore character (_).
• The keyword ASID or JOBNAME. For example, for job ABC running in address space ASID(05), you can code either of the following for the same result:
  • SUB=JOBNAME(ABC)
  • SUB=ASID(05)

If you define multiple sublevel traces on one path of the trace structure, you can specify up to five sublevel trace names separated by periods; for example:

CTRACE DEFINE,NAME=APPLABC,SUB=ASID(13).FACILITY12.SUBA.SUBB.SUBC,...

,LIKEHEAD=NO

,LIKEHEAD=YES

When using multiple traces, use this parameter to specify whether the sublevel trace you are defining is to use the options, attributes, and state of its head node (defined on a previous invocation of the CTRACE macro.) The default is LIKEHEAD=NO.

You cannot specify LIKEHEAD=YES with the following:

• HEADOPTS=NO
• PARM=parm
• Any of the attributes keywords (ASIDS, JOBS, MINOPS, MOD, BUFFER, BUFMIN, BUFMAX, BUFDFLT, BUFDEFIN, and WTR).

,MANYSUBS=NO

,MANYSUBS=YES

Specifies whether you expect the head node you are defining to have more than 15 sublevel traces directly associated with it. For example, a head node with NAME=APPLABC might have 20 sublevel traces specified on subsequent invocations of CTRACE DEFINE that are directly associated with APPLABC:

CTRACE DEFINE,NAME=APPLABC,SUB=SUB1,...
CTRACE DEFINE,NAME=APPLABC,SUB=SUB2,...
CTRACE DEFINE,NAME=APPLABC,SUB=SUB3,...
⋮
CTRACE DEFINE,NAME=APPLABC,SUB=SUB20,...

In this case, code MANYSUBS=YES when you define the head node.

The default is MANYSUBS=NO.

,DELSUBS

,IFNOSUBS

When using multiple traces, use this parameter to restrict which traces will be deleted.

When you issue CTRACE DELETE to delete a trace, and you specify IFNOSUBS, the system does the following:

• If the trace is not a head node, the system deletes the trace.
• If the trace is a head node with no sublevel traces associated with it, the system deletes the trace.
• If the trace is a head node with sublevel traces, the system issues return code X'0C' with reason code X'2B' and does not delete the trace.

When you issue CTRACE DELETE to delete a trace, and you specify DELSUBS, the system deletes the trace. If the trace is a head node with sublevel traces associated with it, the system also deletes the sublevel traces. DELSUBS is the default.

,BUFFER=NO

,BUFFER=YES

Restricts how you can specify the application's trace buffer size. If you code BUFFER=YES, you can specify the trace buffer size in a parmlib member on the CTRACE macro, or the operator can specify the trace buffer size.

If you code BUFFER=NO, which is the default:

• You cannot specify a trace buffer size in a parmlib member on the CTRACE macro.
• The operator cannot specify a trace buffer size.
• You cannot specify BUFDEFIN, BUFMIN, BUFMAX, or BUFDFLT.

,BUFDEFIN=NO

,BUFDEFIN=YES

If you code BUFDEFIN=YES, a buffer size can be specified only on a parmlib member with the PRESET option, or in a parmlib member that you specify on the PARM parameter of CTRACE DEFINE. If you specify BUFDEFIN=YES you must also specify BUFFER=YES. BUFDEFIN=NO is the default.

,BUFMIN=minsize

Specifies the minimum buffer size allowed. The default is 1024 bytes. If you specify less than the default, the default will be used. If you specify BUFMIN, you must also specify BUFFER=YES.

,BUFMAX=maxsize

Specifies the maximum buffer size allowed. BUFMAX cannot be less than BUFMIN. The default is 2147483647 bytes. If you specify BUFMAX, you must also specify BUFFER=YES.

,BUFDFLT=dfltsize

,BUFDFLT=NODFLT

Specifies the default buffer size to be used if you do not specify a buffer size in a parmlib member on the PARM parameter, or if the operator does not specify a buffer size. dfltsize cannot be less than BUFMIN or more than BUFMAX.

If you specify BUFDFLT=dfltsize and also specify a buffer size in a parmlib member or on an operator command, the dfltsize is overridden.

To specify BUFDFLT=dfltsize, you must also specify BUFFER=YES.

BUFDFLT=NODFLT is the default.

,WTR=NO

,WTR=YES

Specifies whether the application's trace supports writing trace data to DASD or tape through the component trace external writer. If you specify WTR=YES, you must also specify WTRMODE.

The default, WTR=NO, means an external writer is not used for this trace.

,WTRMODE=PAGEABLE

,WTRMODE=DREF

,WTRMODE=FIXED

Indicates the type of storage the application's trace buffers are in when you issue the CTRACEWR macro to write the trace buffers to DASD or tape. This parameter is required when you specify WTR=YES.

When you code WTRMODE=PAGEABLE, the application's trace buffers can be in either fixed, disabled reference (DREF), or pageable storage at the time you issue CTRACEWR.

Note: IBM recommends you keep your trace buffers in pageable storage, which will not deplete your system's central storage.

When you code WTRMODE=DREF, the application's trace buffers can be in either fixed or DREF storage at the time you issue CTRACEWR. Regular page faults are not allowed.

When you code WTRMODE=FIXED, the application's trace buffers must be in fixed storage at the time you issue CTRACEWR.

,SSRC=ss_retcode

Specifies the name of a 4-byte output area to contain the return code set by the start/stop routine.

,SSRSNC=ss_rsncode

Specifies the name of a 4-byte output area to contain the reason code from the start/stop routine.

,RC=retcode

Specifies the location where the system is to store the return code. The return code is also in general purpose register (GPR) 15.

,RSNCODE=rsncode

Specifies the location where the system is to store the reason code. The reason code is also in GPR 0. CTRACE provides a reason code if the return code is other than 0 or 4.

,COM=comment

,COM=NULL

Allows you to include a comment string in the macro block comment before the macro invocation. If the comment contains any lowercase characters, it must be enclosed in quotation marks.

,MF=(S)

Specifies the standard form of the CTRACE macro.

The following table identifies abend code and reason code combinations, and a description of what each means:

When control returns from CTRACE, GPR 15 (and retcode, if you coded RC) contains one of the following return codes. The third byte of GPR 0 (and rsncode, if you coded RSNCODE) might contain one of the following reason codes.