Trace control XPI function

There is one XPI trace control function. This is the DFHTRPTX call TRACE_PUT.

DFHTRPTX calls cannot be used in any exit program invoked from any global user exit point in the:

The TRACE_PUT call

TRACE_PUT writes a trace entry to the active trace destinations. You should only make a TRACE_PUT call when UEPTRON indicates that tracing is active for the function containing the exit program (see UEPTRON in DFHUEPAR). You may prefer to make "exception" trace entries, in case of serious errors, without testing UEPTRON.

If you use TRACE_PUT to write exception trace entries, you should identify these so they are highlighted as exception trace entries by the trace formatting utility program. To identify an exception trace entry, enter the literal string ‘USEREXC’ in the DATA1 block descriptor field on the DFHTRPTX call. See the CICS® Problem Determination Guide for details of how an exception trace entry is interpreted.

TRACE_PUT

DFHTRPTX [CALL,]
      [CLEAR,]
      [IN,
      FUNCTION(TRACE_PUT),
      POINT_ID(literalconst | name2 | (Rn)),
      [DATA1(block-descriptor),]
      [DATA2(block-descriptor),]
      [DATA3(block-descriptor),]
      [DATA4(block-descriptor),]
      [DATA5(block-descriptor),]
      [DATA6(block-descriptor),]
      [DATA7(block-descriptor),]
      [RETURN_ADDR(expression | name4 | (Ra)),]]
      [OUT,
      RESPONSE(name1 | *)]

Start of changeThis command is threadsafe.End of change

DATAn(block-descriptor)
specifies up to seven areas to be included in the data section of the trace entry. For a description of valid block-descriptors, see block-descriptor. If you specify any given DATAn, then DATA1 through DATA(n-1) must be coded before DATAn. The specified DATA items are printed in the trace output in the order specified, that is, in order of DATA1 through DATAn. A 2-byte length field is printed before the data field itself. The maximum total length of the data that can be traced in one call is 4040 - (2 * n) bytes, where n is the number of data fields that you specify.
POINT_ID(literalconst|name2|(Rn))
specifies the trace entries made as a result of this request. Every TRACE_PUT call within a calling domain should specify a unique POINT_ID. This enables you to locate the origin of a trace call when examining a formatted trace. The POINT_IDs must be in the range decimal 256 through 511 (X'100' through X'1FF'). This range is not used in CICS modules, but is reserved for user exits.
literalconst
A number in the form of a literal, containing the ID
name2
The name of a 2-byte field containing the ID
(Rn)
A register, the two low-order bytes of which contain the ID.
RETURN_ADDR(expression|name4|(Ra))
specifies the value that appears in the return address field of the trace entry.
expression
A valid assembler-language expression that results in the address
name4
The name of a fullword containing the address
(Ra)
A register containing the address.

RESPONSE values for TRACE_PUT

The RESPONSE field is never set for the TRACE_PUT function. This is for performance reasons. It is not considered that any useful purpose could be served by testing for this value. Note, however, that the syntax requires that RESPONSE is always specified as a parameter on the call. It is recommended that RESPONSE(*) is always used.

Related concepts
Overview of the XPI
Global user exit XPI examples, showing the use of storage
Related tasks
Making an XPI call
Writing global user exit programs
Writing a task-related user exit program
Related reference
The XPI functions
[[ Contents Previous Page | Next Page Index ]]