SET TRACEDEST

Change tracing options.

Read syntax diagramSkip visual syntax diagramSET TRACEDEST
 
>>-SET TRACEDEST--+-----------------+--+-----------------+------>
                  +-AUXSTATUS(cvda)-+  +-GTFSTATUS(cvda)-+
                  +-AUXPAUSE--------+  +-GTFSTART--------+
                  +-AUXSTART--------+  '-GTFSTOP---------'
                  '-AUXSTOP---------'
 
>--+-----------------+--+--------------------+------------------>
   +-INTSTATUS(cvda)-+  +-SWITCHACTION(cvda)-+
   +-INTSTART--------+  '-SWITCH-------------'
   '-INTSTOP---------'
 
>--+--------------------+--+-----------------------+-----------><
   +-SWITCHSTATUS(cvda)-+  '-TABLESIZE(data-value)-'
   +-NOSWITCH-----------+
   +-SWITCHALL----------+
   '-SWITCHNEXT---------'
 

Conditions: INVREQ, IOERR, NOSPACE, NOSTG, NOTAUTH

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 MVS Generalized Trace Facility (GTF). The SET TRACEDEST command allows you to specify which destinations are to receive the 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: INTSTATUS and TRTABSZ (for internal tracing), AUXTR and AUXTRSW (auxiliary tracing), and GTFSTATUS (GTF tracing). See the CICS® System Definition Guide for more information about these values.

Options

AUXSTATUS(cvda)
specifies whether auxiliary tracing is to occur; that is, whether trace entries are to be written to the active CICS auxiliary trace data set. (See the SWITCHACTION option for more about auxiliary trace data sets.) CVDA values are:
AUXPAUSE
CICS is to stop writing entries, but is to leave 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
Entries are to be written. The data set is to be opened first if currently closed.
AUXSTOP
Entries are not to be written. The data set is to be closed if open. A subsequent AUXSTART request will cause new entries to be written 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 to be sent to the MVS Generalized Tracing Facility (GTF). CVDA values are:
GTFSTART
Entries are to be sent.
GTFSTOP
Entries are not to be 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 is to occur; that is, whether non-exception trace entries are to be recorded in the internal trace table. (Exception entries are always recorded.) CVDA values are:
INTSTART
Entries are to be recorded.
INTSTOP
Entries are not to be recorded.
SWITCHACTION(cvda)
specifies that the auxiliary trace data sets are to be switched.

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 standby.

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

The CVDA value is:

SWITCH
CICS is to perform a switch.
Note:
If you request AUXSTATUS and SWITCHACTION in the same command, AUXSTATUS is set first.
SWITCHSTATUS(cvda)
specifies the action CICS is to take 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:
NOSWITCH
CICS is to take no action.
SWITCHALL
CICS is to switch every time the active data set fills.
SWITCHNEXT
CICS is to switch when the current data set is full, but only once; thereafter NOSWITCH is to be 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, obtains a new table of the requested size, and frees the old one. Data that was in the old table is lost.

The table is allocated in multiples of 4KB, with a minimum size of 16KB. Consequently, the value you specify is increased to the next multiple of 4, and to 16 if you specify less than 16. The maximum size is Start of change 1048576.End of change

Start of changeUse caution when setting TABLESIZE to a very high value because there must be enough MVS page storage to satisfy both the request and DSA sizes. The system command DISPLAY ASM MVS can be used to display current information about status and utilization of all MVS page data sets.End of change

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.

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. The NOSWITCH option tells CICS not to switch when the new active data set fills.

[[ Contents Previous Page | Next Page Index ]]