SET TRACEDEST

Description

CICS can write trace entries to three possible destinations: the CICS internal trace table, the auxiliary trace data set, and the MVS™ Generalized Trace Facility (GTF). You can use the SET TRACEDEST command to specify which destinations receive trace entries. You also can use it to change the size of the trace table and to switch auxiliary trace data sets.

Two other commands, SET TRACEFLAG and SET TRACETYPE, and a CICS-supplied transaction, CETR, can be used to control the number and type of trace entries.

Changes made with this command are not recorded in the CICS catalog. Therefore the options affected are always reset to the corresponding system initialization values at CICS startup. These are TRTABSZ (for internal tracing), AUXTR and AUXTRSW (auxiliary tracing), and GTFTR (GTF tracing).

Options

AUXSTATUS(cvda)

Specifies whether auxiliary tracing takes place; that is, whether trace entries are written to the active CICS auxiliary trace data set. (See the SWITCHACTION option for more about auxiliary trace data sets.) CVDA values are as follows:

AUXPAUSE

CICS stops writing entries, but leaves the data set open at its current position. A subsequent AUXSTART request will resume writing entries immediately after those that preceded the AUXPAUSE request. You can specify AUXPAUSE only when auxiliary tracing is currently active.

AUXSTART

CICS starts writing entries. The data set is opened first if it is currently closed.

AUXSTOP

CICS stops writing entries. The data set is closed if it is open. A subsequent AUXSTART request causes CICS to write new entries at the start of the data set, overwriting the previous contents, unless there are two auxiliary trace data sets and they are switched between the AUXPAUSE and AUXSTART.

GTFSTATUS(cvda)

Specifies whether trace entries are sent to the MVS Generalized Tracing Facility (GTF). CVDA values are as follows:

GTFSTART

Entries are sent.

GTFSTOP

Entries are not sent.

Note: A value of GTFSTART is necessary but not sufficient for recording CICS trace entries on GTF. In addition, CICS must be initialized with GTF support (the GTFTR system initialization option), and GTF must be started in MVS with the TRACE=USR option.

INTSTATUS(cvda)

Specifies whether internal tracing occurs; that is, whether non-exception trace entries are recorded in the internal trace table. (Exception entries are always recorded.) CVDA values are as follows:

INTSTART

Entries are recorded.

INTSTOP

Entries are not recorded.

SWITCHACTION(cvda)

Specifies that CICS must switch the auxiliary trace data sets.

If your system supports auxiliary tracing, it has either one or two auxiliary trace data sets. One is active, which means it receives trace entries when auxiliary tracing is turned on, and the other, if there are two, is a standby.

When there are two, you can reverse their roles by specifying SWITCH. This causes CICS to close the current active data set, open the standby, and reverse the designation of which is active and which is a standby.

If there is only one auxiliary trace data set (or none), SWITCH causes an exception condition, because CICS attempts to open a data set that is not defined.

The CVDA value is as follows:

SWITCH

CICS performs a switch.

Note: If you request AUXSTATUS and SWITCHACTION in the same command, AUXSTATUS is set first.

SWITCHSTATUS(cvda)

Specifies the action CICS takes when the current active auxiliary trace data set fills. When this occurs, CICS cannot continue auxiliary tracing unless a switch or an AUXSTOP-AUXSTART sequence takes place (see the SWITCHACTION and AUXSTATUS options). CVDA values are as follows:

NOSWITCH

CICS takes no action.

SWITCHALL

CICS switches every time the active data set fills.

SWITCHNEXT

CICS switches when the current data set is full, but only once; thereafter NOSWITCH is in effect.

TABLESIZE(data-value)

Specifies, as a fullword binary value, the size of the internal trace table in kilobytes. If you specify a value that is different from the current trace table size, CICS suspends internal tracing while the change is made, and data in the old table is deleted.

The table is allocated in multiples of 4 KB, with a minimum size of 16 KB. If you specify a value that is not a multiple of the page size (4 KB), it is rounded up to the next multiple of 4 KB. If you specify less than 16 KB, the value is rounded up to 16 KB. The maximum size is 1048576 KB (1 GB).

CICS uses 64-bit (above-the-bar) storage for the internal trace table. The value of TABLESIZE must be less than the value of the z/OS® MEMLIMIT parameter, and you must also allow for other facilities in the CICS region that use 64-bit storage. See Estimating, checking, and setting MEMLIMIT.

Conditions

INVREQ

RESP2 values:

1

INTSTATUS has an invalid CVDA value.

2

A TABLESIZE value of < -1 has been specified.

3

AUXSTATUS has an invalid CVDA value.

4

SWITCHSTATUS has an invalid CVDA value.

5

GTFSTATUS has an invalid CVDA value.

6

AUXPAUSE was specified, but auxiliary tracing is not active.

11

SWITCHACTION has an invalid CVDA value.

IOERR

RESP2 values:

10

A SWITCH request or a SET AUXSTART request resulted in an “open” error for the trace data set.

NOSPACE

RESP2 values:

7

There is insufficient space for the new trace table.

NOSTG

RESP2 values:

8

There is insufficient space for an auxiliary trace buffer.

9

There is insufficient space for a GTF trace buffer.

NOTAUTH

RESP2 values:

100

The user associated with the issuing task is not authorized to use this command.