SET TRACEDEST

Change tracing options.

Syntax

Warning: System commands are powerful as they provide information about the state of the system and allow changes to be made to it. System commands should be used only by authorized applications and users.

Activate security checks on commands by specifying the XCMD system initialization parameter and by ensuring that command security checking is active for the transaction (either by specifying CMDSEC(YES) on the TRANSACTION resource definition or by specifying ALWAYS on the CMDSEC system initialization parameter).

SET TRACEDEST

Read syntax diagramSkip visual syntax diagramSET TRACEDESTAUXSTATUS(cvda)AUXPAUSEAUXSTARTAUXSTOPGTFSTATUS(cvda)GTFSTARTGTFSTOPINTSTATUS(cvda)INTSTARTINTSTOPSWITCHACTION(cvda)SWITCHSWITCHSTATUS(cvda)NOSWITCHSWITCHNEXTSWITCHALLTABLESIZE(data-value)

Conditions: INVREQ, IOERR, NOSPACE, NOSTG, NOTAUTH

This command is threadsafe.

NOHANDLE, RESP, and RESP2 are common options that can be added to all EXEC CICS commands to process error conditions. They are not explicitly included in the command syntax diagram and option descriptions. For information about these common options and EXEC CICS command syntax, see EXEC CICS command format and programming considerations. For more information about the use of CVDAs, see CICS-value data areas (CVDAs).

Description

CICS® can write trace entries to three possible destinations: the CICS internal trace table, the auxiliary trace data set, and the z/OS® 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 trace), and GTFTR (GTF trace).

Options

AUXSTATUS(cvda)
Specifies whether auxiliary trace 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 trace 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 z/OS with the TRACE=USR option.
INTSTATUS(cvda)
Specifies whether internal trace 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 trace, it has either one or two auxiliary trace data sets. One is active, which means it receives trace entries when auxiliary trace 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.
SWITCHNEXT
CICS switches when the current data set is full, but only once; thereafter NOSWITCH is in effect.
SWITCHALL
CICS switches every time the active data set fills.
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 trace 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 and checking 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 trace 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.

Examples

EXEC CICS SET TRACEDEST
              SWITCH
              NOSWITCH

The SWITCH option tells CICS to switch now from the active auxiliary trace data set (which is not necessarily full) to the alternate auxiliary trace data set. The NOSWITCH option tells CICS not to switch when the new active data set fills.