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

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.

If you are using both data sets, you can use the auxiliary switch (AUXTRSW system initialization parameter) to specify that auxiliary trace data cannot be overwritten by subsequent trace data.

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.

For an overview of CICS auxiliary trace, see CICS auxiliary trace and auxiliary trace data sets.

Procedure

  1. 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.
  2. 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 CICS trace utility program, DFHTUnnn 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.
  3. 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:
  4. 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.
  5. Optional: If you want to encrypt the data sets, see Encrypting data sets.
  6. Define the auxiliary trace data sets to CICS in the startup job stream.
    For auxiliary trace data sets on disk
    For auxiliary trace data sets on disk, use the following DD statements as examples. In the example DD statements, the data set names have prefixes that reflect the release of CICS TS, and the release level is assumed to be CICS TS 6.2. 
    //DFHAUXT  DD  DSN=CICSTS62.CICS.applid.DFHAUXT,DCB=BUFNO=n,DISP=SHR
//DFHBUXT  DD  DSN=CICSTS62.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 CICS trace utility program, DFHTUnnn after a switch to the other data set has taken place. DFHTUnnn is an offline utility program that has a unique release identifier in its name. For example, it is DFHTU750 for CICS TS 6.2.
    For auxiliary trace data sets on unlabeled tapes
    For auxiliary trace data sets on unlabeled tapes, use the following sample DD statements. In the sample, the data set names have prefixes that reflect the release of CICS TS, and the release level is assumed to be CICS TS 6.2.
    //DFHAUXT  DD  DSN=CICSTS62.CICS.applid.DFHAUXT,UNIT=3400,VOL=SER=volid,
//         DISP=(NEW,KEEP),LABEL=(,NL)
//DFHBUXT  DD  DSN=CICSTS62.CICS.applid.DFHBUXT,UNIT=3400,VOL=SER=volid,
//         DISP=(NEW,KEEP),LABEL=(,NL)

Sample job to allocate auxiliary trace data sets

If you are defining auxiliary trace data sets on disk, you can use this sample job to allocate and catalog them before you run CICS.

The DCB subparameters shown in this sample job specify the required DCB attributes for the CICS auxiliary trace data sets. As an alternative to this job, you can specify (NEW,CATLG) on the DD statements in the CICS startup job stream, omit the DCB parameter, and let CICS open the data sets with the same default values.

Change the space allocations in this sample job stream to suit your installation's needs.

In the sample job stream, the high level qualifier (CICSTSnn.CICS) assumes the release level of CICS TS 6.2. You must adapt it for your own CICS release.

Figure 1. Sample job to define auxiliary trace data sets on disk
//DEFTRCDS JOB (accounting information),
//             MSGCLASS=A,MSGLEVEL=(1,1),
//             CLASS=A,NOTIFY=userid
//*********************************************************************
//*            Create auxiliary trace data sets
//*********************************************************************
//ALLOCDS  EXEC PGM=IEFBR14
//DFHAUXT  DD  DSN=CICSTS62.CICS.applid.DFHAUXT,UNIT=3380,VOL=SER=volid,
//         DISP=(NEW,CATLG),DCB=(BLKSIZE=4096,RECFM=F,LRECL=4096),  
//              SPACE=(CYL,(25))                                   
//DFHBUXT  DD  DSN=CICSTS62.CICS.applid.DFHBUXT,UNIT=3380,VOL=SER=volid,
//         DISP=(NEW,CATLG),DCB=(BLKSIZE=4096,RECFM=F,LRECL=4096),  
//              SPACE=(CYL,(25))                                   
//