Trace domain’s specific gates

Table 108 summarizes the trace domain’s specific gates. It shows the level-1 trace point IDs of the modules providing the functions for the gates, the functions provided by the gates, and whether or not the functions are available through the exit programming interface (XPI).

Table 108. Trace domain’s specific gates
Gate Trace Function XPI
TRPT
None
TRACE_PUT
YES
TRSR
TR 0201
TR 0202
SET_INTERNAL_TABLE_SIZE
START_INTERNAL_TRACE
STOP_INTERNAL_TRACE
INQUIRE_INTERNAL_TRACE
START_AUXILIARY_TRACE
STOP_AUXILIARY_TRACE
PAUSE_AUXILIARY_TRACE
SET_AUX_TRACE_AUTOSWITCH
SWITCH_AUXILIARY_EXTENTS
INQUIRE_AUXILIARY_TRACE
START_GTF_TRACE
STOP_GTF_TRACE
INQUIRE_GTF_TRACE
ACTIVATE_TRAP
DEACTIVATE_TRAP
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO

TRPT gate, TRACE_PUT function

This function is invoked to write a trace entry to the active trace destinations.

Input parameters

POINT_ID
is a number, unique within the calling domain, that identifies the trace entries made from this call.
[DATA1] through [DATA7]
are BLOCK descriptions of up to seven areas to be included in the data section of the trace entry. They appear in numerical order in the entry, each preceded by a 2-byte length field.

The maximum total length of data that can be traced in one call is as described below:

Length of trace table block                4096
less length of trace table block header  -   24
less length of trace entry header        -   32
                                         ------
Maximum space for data + length fields     4040
For each DATA field specified, 2 bytes must be
subtracted to allow for the length field.
Maximum space for actual data  =  4040 - (2 * n)
where 'n' is the number of DATA fields specified.
[RETURN_ADDR]
is used by DFHTRP to give a return address in the trace entry from the calling module rather than in DFHTRP.

Output parameters

RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
Note:
No response is returned when the TRACE_PUT request is handled by module DFHTRPX without involving the trace domain.

TRSR gate, SET_INTERNAL_TABLE_SIZE function

The SET_INTERNAL_TABLE_SIZE function of the TRSR gate is used to change the size of the internal trace table during a CICS® run.

Input parameters

TABLE_SIZE
is the required table size, specified as a number of KB (KB equals 1024 bytes). This is rounded up to the nearest multiple of 4KB. The lower limit is 16KB. The upper limit is set only by the amount of storage available. If the table is being made larger, the existing table is freed and a variable MVS™ GETMAIN issued for the required size. The actual length of the new table can be determined by issuing an INQUIRE_INTERNAL_TRACE command. If the table is being made smaller, part of the existing table is freed.

Output parameters

RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is INVALID. Possible values are:
RESPONSE Possible REASON values
INVALID
INVALID_TABLE_SIZE
NO_SPACE
Note:
INVALID_TABLE_SIZE indicates that the value of TABLE_SIZE is less than 16KB.

NO_SPACE indicates that the variable GETMAIN for the new trace table failed to obtain even the minimum trace table size. In this situation, the trace domain retains an amount equal to the minimum table size from the old table to use.

TRSR gate, START_INTERNAL_TRACE function

The START_INTERNAL_TRACE function of the TRSR gate is used to activate tracing to the internal trace table.

Input parameters

None.

Output parameters

RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED

TRSR gate, STOP_INTERNAL_TRACE function

The STOP_INTERNAL_TRACE function of the TRSR gate is used to deactivate tracing to the internal trace table.

Input parameters

None.

Output parameters

RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED

TRSR gate, INQUIRE_INTERNAL_TRACE function

The INQUIRE_INTERNAL_TRACE function of the TRSR gate is used to return the status of the internal trace and the current size of the internal trace table.

Input parameters

None.

Output parameters

RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
TABLE_SIZE
is the size of the current internal trace table in KB (KB equals 1024 bytes).
INTERNAL_STATUS
indicates whether internal trace is active (STARTED) or inactive (STOPPED).

TRSR gate, START_AUXILIARY_TRACE function

The START_AUXILIARY_TRACE function of the TRSR gate is used to open the current auxiliary trace extent (if it is closed) and start tracing to it.

Input parameters

None.

Output parameters

RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
CANT_GET_AUX_BUFFER
DFHTRAO_NOT_AVAILABLE
OPEN_FAILED
Note:
CANT_GET_AUX_BUFFER indicates that MVS had insufficient free storage to satisfy the request for a buffer below the 16MB line.

DFHTRAO_NOT_AVAILABLE indicates that the request to the CICS loader to acquire the auxiliary trace output program, DFHTRAO, has failed.

OPEN_FAILED indicates that the MVS open of the auxiliary trace data set has failed.

TRSR gate, STOP_AUXILIARY_TRACE function

The STOP_AUXILIARY_TRACE function of the TRSR gate is used to stop auxiliary tracing and close the currently active auxiliary trace extent.

Input parameters

None.

Output parameters

RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED

TRSR gate, PAUSE_AUXILIARY_TRACE function

The PAUSE_AUXILIARY_TRACE function of the TRSR gate is used to stop auxiliary tracing without closing the currently active extent.

Input parameters

None.

Output parameters

RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION. It has this value:
AUX_TRACE_STOPPED

meaning that the pause is allowed only if auxiliary trace is not stopped.

TRSR gate, SET_AUX_TRACE_AUTOSWITCH function

The SET_AUX_TRACE_AUTOSWITCH function of the TRSR gate is used to allow the autoswitch facility for the CICS auxiliary trace data set to be enabled or disabled.

Input parameters

AUTOSWITCH_STATUS
Indicates whether or not an automatic switch to the inactive CICS auxiliary extent is to occur once only when the current extent fills up, or that such automatic switching should occur "continuously" whenever the current extent fills up. It can have any one of these values:
OFF|ONCE|CONTINUOUS

Output parameters

RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION. It has this value:
INVALID_AUTOSWITCH_STATUS

meaning that an incorrect value was passed for AUTOSWITCH_STATUS.

TRSR gate, SWITCH_AUXILIARY_EXTENTS function

The SWITCH_AUXILIARY_EXTENTS function of the TRSR gate allows switching from one auxiliary trace extent to the other.

Input parameters

None.

Output parameters

RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION. It has this value:
OPEN_FAILED

meaning that the attempt to open the new auxiliary extent failed.

TRSR gate, INQUIRE_AUXILIARY_TRACE function

The INQUIRE_AUXILIARY_TRACE function of the TRSR gate is used to return the current state of the auxiliary trace.

Input parameters

None.

Output parameters

AUXILIARY_STATUS
Indicates the current status of auxiliary trace. It can have any one of these values:
STARTED|STOPPED|PAUSED
EXTENT
indicates the currently active CICS auxiliary trace extent; that is, the extent that is already in use or is used if CICS auxiliary tracing is started. It can have either of these values:
DFHAUXT|DFHBUXT
AUTOSWITCH_STATUS
Indicates whether or not an automatic switch to the inactive CICS auxiliary extent is to occur once only when the current extent fills up, or that such automatic switching should occur "continuously" whenever the current extent fills up. It can have any one of these values:
OFF|ONCE|CONTINUOUS
RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED

TRSR gate, START_GTF_TRACE function

The START_GTF_TRACE function of the TRSR gate is used to start the tracing of CICS activity to GTF. It is the responsibility of the user to ensure that GTF has been started in MVS with at least TRACE=USR. If it has not, CICS issues the GTF calls but they are ignored by GTF.

Input parameters

None.

Output parameters

RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION. It has this value:
CANT_GET_GTF_BUFFER

meaning that there was insufficient storage for a buffer to be used in constructing continuation records when an individual entry is longer than 256 bytes.

TRSR gate, STOP_GTF_TRACE function

The STOP_GTF_TRACE function of the TRSR gate is used to stop tracing of CICS activity to GTF.

Input parameters

None.

Output parameters

RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED

TRSR gate, INQUIRE_GTF_TRACE function

The INQUIRE_GTF_TRACE function of the TRSR gate is used to return the current state of the GTF trace.

Input parameters

None.

Output parameters

GTF_STATUS
indicates whether CICS tracing to GTF is active (STARTED) or inactive (STOPPED).
RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED

TRSR gate, ACTIVATE_TRAP function

The ACTIVATE_TRAP function of the TRSR gate is used to activate the FE global trap/trace exit (DFHTRAP).

Input parameters

None.

Output parameters

RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
DFHTRAP_NOT_FOUND
DFHTRAP_UNUSABLE
Note:
DFHTRAP_NOT_FOUND indicates that the request to the CICS loader to acquire the FE global trap/trace exit program, DFHTRAP, has failed.

DFHTRAP_UNUSABLE indicates that the trap was already active, but marked as unusable because a program check had previously occurred when DFHTRAP was in control.

TRSR gate, DEACTIVATE_TRAP function

The DEACTIVATE_TRAP function of the TRSR gate is used to deactivate the FE global trap/trace exit (DFHTRAP).

Input parameters

None.

Output parameters

RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[[ Contents Previous Page | Next Page Index ]]