Prepare for a specific component trace to trace data sets

The system programmer performs the following tasks:

1. Determine the dispatching priority required for the external writer started task, the server address space for the component's trace:

While component trace runs under the master scheduler address space, you need to verify that the priority of the external writer is at least equal to, and preferably greater than the priority of the component being traced. For example, if you are tracing COMP(SYSXES) for JOBNAME(IRLMA), the dispatching priority of the external writer should be equal to or greater than that assigned to IRLMA. See z/OS MVS Initialization and Tuning Guide for more information on setting priorities.

2. Select How the Operator Is to Request the Trace:

For most component traces, the request can be made by:

A TRACE CT operator command without a PARM parameter, followed by a reply containing the options
A TRACE CT operator command with a PARM parameter that specifies a CTncccxx parmlib member containing the options

If you do not use a parmlib member, tell the operator the options.

3. Create Source JCL for the External Writer:

Create source JCL to invoke an external writer, which will send the component trace output to one or more trace data sets. Add a procedure to the SYS1.PROCLIB system library or a job as a member of the data set in the IEFJOBS or IEFPDSI concatenation.

An external writer is not specific for a component but can be used by any application. So you can use the same source JCL again for other tracing later, if needed.

Concurrent traces for different components must use separate source JCL to place their traces in separate data sets.

Because the writer source JCL specifies data sets, use a different set of source JCL for each system in a sysplex. Several systems cannot share the same data set; attempting to share the same data set will lead to contention problems. If your sysplex uses a common SYS1.PROCLIB, you need to specify a unique writer procedure for each system or use a unique job as the source JCL, when tracing the same component on several systems.

The procedure shown in Figure 1 places trace data on two DASD data sets. The procedure is placed in member WTRD2 of SYS1.PROCLIB.

Figure 1. Example: Cataloged Procedure for an External Writer

//WTDASD2  PROC
//IEFPROC  EXEC PGM=ITTTRCWR,REGION=32M
//TRCOUT01 DD  DSNAME=SYS1.CTRACE1,VOL=SER=TRACE6,UNIT=DASD,
//         SPACE=(CYL,10),DISP=(NEW,KEEP),DSORG=PS
//TRCOUT02 DD  DSNAME=SYS1.CTRACE2,VOL=SER=TRACE7,UNIT=DASD,
//         SPACE=(CYL,10),DISP=(NEW,KEEP),DSORG=PS

Rules for the Source JCL for an External Writer:

The name specified on the TRACE CT command or CTncccxx parmlib member is the member name of the source JCL; in the preceding example, WTRD2. The name is 1 to 7 alphanumeric or national characters, with the first character alphabetic or national. National characters are represented by the following hexadecimal codes (in other languages, the codes represent different characters):
Code

U.S. English EBCDIC Character

X'5B'

$

X'7B'

#

X'7C'

@
The procedure must invoke the external writer program ITTTRCWR. Code the REGION= keyword on the EXEC statement to specify the maximum storage size required by the external writer.
The source JCL can specify up to 16 trace data sets. The DD statements have ddnames of TRCOUTxx, where xx is 01 through 16.
The trace data sets must be sequential data sets. You can use extended format sequential data sets as dump data sets for trace output. Extended format sequential data sets have the following features:
- Have a greater capacity than sequential data sets
- Support striping
- Support compression
To help you manage the trace data sets, establish a naming convention so that the data set name indicates the component trace, the date, and so on.
All of the data sets must be on DASD or tape. Do not mix device classes, such as tape and DASD.
Within a device class, IBM® recommends that you do not mix several types of devices, such as 3380 and 3390. In a mix of device types, the system would use the smallest block size for all the data sets.
Do not specify the following DCB parameters:
- BLKSIZE. The system uses the optimal block size, which is 4096 or larger.
- RECFM. The system uses VB.
- LRECL. The system uses BLKSIZE minus 4.
Do not specify DISP=SHR.
Do not concatenate trace data sets.
Use a separate member for each component's trace, even though you can connect more than one trace to the same member.
Use the same member for all the sublevel traces for a component. This approach reduces the number of data sets you must manage.
Use a separate member for each system's component trace, when a component trace runs in two or more of the systems of a sysplex. If the component traces specify the same cataloged procedure in a shared SYS1.PROCLIB, they will use the same data set or group of data sets; in this case, contention might develop for the data set or sets.
System security may require that you have RACF® SYSHIGH authority to access the trace data sets.

z/OS® V1R7 supports the following types of external media:

DSNTYPE=LARGE data sets
VSAM linear data sets
GTF and CTRACE accept a single VSAM linear data set as output. VSAM's support for striping can increase data rate without the complexity associated with the use of distinct data sets.

For the details of the external data sets guidelines, see Guidelines for defining GTF trace output data sets in a cataloged procedure.

Wrapping DASD Trace Data Sets: If the WTRSTART parameter on the CTncccxx parmlib member or TRACE CT operator command specifies:

WRAP or omits the parameter: 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 first data set.
The system also uses only the primary extent or extents for the data set or sets. To obtain the maximum degree of control over the number of trace entries for which space will be allocated, specify space allocation in units of the BLKSIZE of your trace data set, no secondary space, and use the option for contiguous allocation. For example, if your BLKSIZE is 8192, code the SPACE keyword as follows:
```
SPACE=(8192,(500,0),,CONTIG)
```
NOWRAP: When the data set or sets are full, the system stops writing trace records to the data set or sets. The system continues writing trace records in the address-space buffers.
The system also uses the primary and secondary extents of the data set or sets.

Note: Wrapping is not supported for Extended Format Sequential data sets, which are treated as NOWRAP even if WRAP is specified.

Tape Data Sets: CTRACE writes an end-of-file record. The tape is rewound and unloaded, then a new volume is mounted on the tape unit. If CTRACE has only one tape data set and only one unit for the data set, CTRACE does not write trace records while the tape is unavailable, thus losing trace data. CTRACE can write to multiple tape units in the way that multiple TRCOUTxx DD statements can specify tape data sets. When CTRACE fills one data set, it changes to the next data set.

Note: GTF and CTRACE support placement of NOWRAP traces in cylinder-managed space. WRAP traces placed in VSAM linear data sets can reside in cylinder-managed space too. WRAP traces in non-VSAM data sets cannot be placed in large format data sets, extended format data sets, or cylinder-managed space.

Multiple Trace Data Sets: Use multiple data sets to capture all the trace records, even during spikes of activity. For a SYSRSM trace, which typically produces large numbers of trace records, use multiple data sets to keep from losing records. Multiple trace data sets using different DASD devices can improve performance. To view the trace records in chronological sequence, the system programmer can:

Combine the trace records into one data set, using an IPCS COPYTRC subcommand, then use the CTRACE subcommand to format the records from the data set.
Use an IPCS MERGE subcommand to format the records from multiple data sets.

The system places component trace records into each trace data set in sequence. For example, for three data sets, the system places:

Record 1 into data set 1
Record 2 into data set 2
Record 3 into data set 3
Record 4 into data set 1
Record 5 into data set 2
And so on

Lost Trace Data: Ctrace will give an indication in the next successfully written record of any trace data that did not reach the output medium. If no further records are written, the following message is displayed when the external writer is stopped:

ITT120I SOME CTRACE DATA HAS BEEN LOST.
LAST nnn BUFFERS NOT WRITTEN.