Design overview

The controlling program (DFHDU640, DFHTRDUF, DFHTRPRA, or DFHTRPRG) is responsible for acquiring the trace formatting control area (TRFCA), which is used for communication between the different routines.

As far as possible, the necessary code is constructed of routines that can run in all four environments. Subroutines required by the common code that cannot themselves be common (such as the line print subroutine) have their addresses placed in the TRFCA by the controlling program.

The controlling routines are:

DFHDU640
The dump utility program used to print transaction dumps. Invokes DFHTRFPB for each internal table block.
DFHTRDUF
The system dump formatting routine for the trace domain. Invokes DFHTRFPB for each internal table block.
DFHTRPRA
The main routine of the trace utility program DFHTU640 used to print an auxiliary trace data set. Invokes DFHTRFPP to encode selective print parameters. Invokes DFHTRFPB for each auxiliary trace block.
DFHTRPRG
The main routine of the GTF format appendage for CICS® entries (format ID X'EF') AMDUSREF (alias DFHTR640). Invokes DFHTRFPP to encode selective print parameters. Invokes DFHTRFFE for each trace entry.

A noncommon subroutine required in all four environments is:

TRFPRL
Print a specified character buffer. This is contained in the controlling program.

The common routines required in more than one environment are:

DFHTRFPP
Process parameters. Passed a character string, encodes the string as selective print parameters into the TRFCA (for DFHTRPRA and DFHTRPRG only). See the CICS Operations and Utilities Guide for details of the selective print parameters.
DFHTRFPB
Process block. Processes a trace block from a dump or auxiliary trace data set, calling DFHTRFFE for each entry in the block.
DFHTRFFE
Format entry. Passed a trace entry, it calls DFHxxTRI, TRFPRL, and DFHTRFFD to produce the formatted entry.
DFHTRFFD
Format data. To format and print the trace data fields of a particular entry in hex and character form. Calls TRFPRL to print each line.
DFHxxTRI
The interpretation routine for the xx domain. Builds the interpretation string for a particular entry given the trace point ID and the data fields from the entry. The AP domain routine DFHAPTRI calls one of the interpretation routines DFHAPTRx. Each of these is responsible for a functional component of the AP domain.
DFHTRIB
The interpretation build program. Adds printable data to the interpretation buffer in the TRFCA as requested by the interpretation routine.
DFHCDCON
The interpretation of some trace entries requires analysis of domain call parameter lists. Converts a hexadecimal parameter list into a printable list of keywords. If the resulting interpretation string would have been more than 1024 bytes long if all keywords were included, the warning ‘<<INTERPRETATION OVERFLOWED>>’ is printed with the string.
DFHxxyyT
The data file for an xxyy format parameter list that is used by DFHCDCON to translate the hexadecimal parameter list into a printable list of keywords.

The components of the trace formatting function are shown in Figure 89.

Figure 89. Trace formatting components
 This is a technical drawing showing the components of trace formatting and their relationships to each other.

Segmented entries on GTF

GTF entries with the CICS format ID X'EF' are written from parts of CICS that run asynchronously with the mainline code, as well as from the trace domain itself. The source of the entry is identified by the type byte in TREN_TYPE in the entry header. See DFHTREN in the CICS Data Areas manual for a full description of the trace entry header.

Type      Source of entry
 00         TR domain
 01         not used
 02         DFHMNSVC
 03         ‘normal’ CICS VTAM exit
 04         CICS VTAM LERAD/SYNAD exit
 05         CICS VTAM TPEND exit
 06         CICS VTAM HPO exit
 07         CICS VTAM HPO LERAD/SYNAD exit

For trace formatting, the different types run on different MVS™ threads. Because CICS entries can be split into several GTF entries due to the 256-byte restriction on GTF entry length, it is possible that header and continuation entries of the different types may be interleaved on the GTF data set. DFHTRPRG allows for this by having 4KB buffers for each type in which it can reconstruct segmented entries. This is made all the more relevant when it is recognized that there could be several CICS regions writing to the GTF data set at the same time. Not only may different types become interleaved, but also records of the same type but from different CICS regions. For each type there can be up to five 4KB buffers for reconstructing the segmented entries to ensure that all the entries for any region are formatted completely and correctly. This makes the segmenting of the entries transparent in a formatted GTF trace, although they appear in order of completion and so may be out of time sequence.

[[ Contents Previous Page | Next Page Index ]]