Setting up auxiliary trace data sets

CICS® trace entries can be directed to auxiliary trace data sets, which are CICS-owned BSAM data sets. If you want to use auxiliary trace, you must create the data sets before you start CICS; you cannot define them while CICS is running.

About this task

You can choose from a number of destinations for trace data that is handled by the CICS trace domain. Any combination of these destinations can be active at any time:

The internal trace table, in main storage in the CICS address space.
The auxiliary trace data sets, defined as BSAM data sets on disk or tape.
The z/OS® generalized trace facility (GTF) data sets.
The JVM server trace file in z/OS Unix System Services

Auxiliary trace has the following advantages:

You can collect large amounts of trace data, if you initially define large enough trace data sets. For example, you might want to do this to trace system activity over a long period of time, perhaps to solve an unpredictable storage violation problem.
You can use the auxiliary switch (AUXTRSW system initialization parameter) to specify that auxiliary trace data cannot be overwritten by subsequent trace data. With the internal trace table, when the end of the table is reached subsequent entries overwrite those at the start of the table, and diagnostic information is lost.
Auxiliary trace can be particularly useful if you are using CICS trace during startup, because of the high volume of trace entries that are written when CICS is initializing.

Auxiliary trace is held in one or two sequential data sets, on either disk or tape. The DD names of the auxiliary trace data sets are defined by CICS as DFHAUXT and DFHBUXT. If you define a single data set only, its DD name must be DFHAUXT.

Trace entries are of variable length, but the physical record length (block size) of the data that is written to the auxiliary trace data sets is fixed at 4096 bytes. As a rough guide, each block contains an average of 40 trace entries, although the actual number of trace entries depends on the processing that is being performed.

Procedure

Decide whether to define one or two sequential data sets for auxiliary trace.
If you want to specify automatic switching for your auxiliary trace data sets, you must define two data sets. If you specify automatic switching for auxiliary trace, but define only one data set, auxiliary trace is stopped and a system dump is generated.
Decide on the location of the auxiliary trace data sets.
If you use tape for recording auxiliary trace output, use unlabeled tape. Using standard-labeled tape, whether on a single tape drive or on two tape drives, stops you processing the contents of any of the volumes with the DFHTU730 utility until after the CICS step has been completed. If you have to use standard-labeled tape, make sure all the output produced in the CICS run fits on the one (or two) volumes mounted.
You cannot catalog data sets that are on unlabeled tapes.
If you are defining auxiliary trace data sets on disk, allocate and catalog the auxiliary trace data sets before you start CICS. Use one of the following methods:
- Use the sample job shown in Sample job to allocate auxiliary trace data sets to allocate and catalog the data sets.
- Use the supplied job DFHDEFDS to create the auxiliary trace data sets. For more information, see Creating the CICS data sets.
If you are using tape for the auxiliary data sets, and you want auxiliary trace to be active from CICS startup, assign tape units and mount the tapes before you start CICS.
If you plan to start auxiliary trace by entering a command when CICS is running, ensure the tapes are mounted before you enter the command.
Optional: If you want to encrypt the data sets, see Encrypting data sets.
Define the auxiliary trace data sets to CICS in the startup job stream.
1. For auxiliary trace data sets on disk, use the following DD statements:
```
//DFHAUXT  DD  DSN=CICSTS56.CICS.applid.DFHAUXT,DCB=BUFNO=n,DISP=SHR
//DFHBUXT  DD  DSN=CICSTS56.CICS.applid.DFHBUXT,DCB=BUFNO=n,DISP=SHR
```
  If you specify BUFNO greater than 1, you can reduce the I/O overhead involved in writing auxiliary trace records. A value between 4 and 10 can greatly reduce the I/O overhead when running with auxiliary trace on. DISP=SHR allows the simultaneous processing of a data set by the DFHTU730 offline utility program after a switch to the other data set has taken place.
2. For auxiliary trace data sets on unlabeled tapes, use the following sample DD statements:
```
//DFHAUXT  DD  DSN=CICSTS56.CICS.applid.DFHAUXT,UNIT=3400,VOL=SER=volid,
//         DISP=(NEW,KEEP),LABEL=(,NL)
//DFHBUXT  DD  DSN=CICSTS56.CICS.applid.DFHBUXT,UNIT=3400,VOL=SER=volid,
//         DISP=(NEW,KEEP),LABEL=(,NL)
```