The TRACE_PUT call

TRACE_PUT writes a trace entry to the active trace destinations.

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 might prefer to make exception trace entries, in case of serious errors, without testing UEPTRON.

If you use TRACE_PUT to write exception trace entries, 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.

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 | *)]

This command is threadsafe.

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 XPI syntax. 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 4000 bytes. The total length of all the data fields and all their 2-byte length fields must be within this limit.
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.


dfha35e.html | Timestamp icon Last updated: Monday, 5 June 2017