Trace formatting
This reference describes the code used to interpret and format CICS® trace entries when they are processed offline.
- Internal trace, which is written to the main storage in the CICS region.
- Auxiliary trace, which is written to BSAM data sets managed by CICS.
- GTF trace, which is written to the z/OS®-defined destination for generalized trace facility (GTF) records.
In this context, formatting refers to the overall process of producing a report, suitable for viewing or printing, from trace data in a dump or trace data set. Interpretation is the process of taking just the point ID and the data fields from a trace entry and producing a character string describing what the entry represents.
- Internal trace in transaction dump
- Internal trace in system dump
- Printing auxiliary trace data set
- Printing GTF trace data set or processing GTF records in an SDUMP
| Transaction dump printout | System dump printout | Auxiliary trace printout | GTF trace printout | |
|---|---|---|---|---|
| CICS trace type | Internal | Internal | Auxiliary | GTF |
| Data set | DFHDMPx | SYS1.DUMPnn | DFHxUXT | SYS1.DUMPnn or SYS1.TRACE |
| Controlling program | DFHDUnnn 1 | DFHTRDUF | DFHTRPRA | DFHTRPRG |
| Load module name | DFHDUnnn 1 | DFHPDnnn 2 | DFHTUnnn 3 | AMDUSREF (alias DFHTRnnn 4 ) |
1 DFHDUnnn is the dump utility program, where nnn is a release identifier. For example, it is DFHDU760 for CICS TS 6.3. See Dump utility program.
2 DFHPDnnn is the dump formatting program, where nnn is a release identifier. For example, it is DFHPD760 for CICS TS 6.3. See System dump formatting program.
3 DFHTUnnn is the trace utility program, where nnn is a release identifier. For example, it is DFHTU760 for CICS TS 6.3.
4 DFHTRnnn is the GTF trace print program, where nnn is a release identifier. For example, it is DFHTR760 for CICS TS 6.3.
Design overview
The controlling program (DFHDUnnn, 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.
- DFHDUnnn
- The dump utility program used to print transaction dumps. It invokes DFHTRFPB for each internal table block.
- DFHTRDUF
- The system dump formatting routine for the trace domain. It invokes DFHTRFPB for each internal table block.
- DFHTRPRA
- The main routine of the trace utility program, DFHTUnnn, used to print an auxiliary trace data set. It invokes DFHTRFPP to encode selective print parameters. It 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 DFHTRnnn). It invokes DFHTRFPP to encode selective print parameters. It invokes DFHTRFFE for each trace entry.
A non-common subroutine required in all four environments is TRFPRL, which prints a specified character buffer. This is contained in the controlling program.
- DFHTRFPP: Process parameters
- DFHTRFPB: Process block
- DFHTRFFE: Format trace entry
- DFHTRFFD: Format data
- DFHxxTRI: The interpretation routine for the xx domain
It 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
- DFHCDCON: The parameter list decode routine
- 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
Control blocks
The trace formatting control area (TRFCA) is used as a communication area between the routines that go to make up each of the four trace formatting load modules. See Data areas for details of DFHTRFCA.
Modules
- Table 2 lists the controlling programs.
- Table 3 lists the common routines.
- Table 4 lists the trace interpretation routines.
| Module | Description |
|---|---|
| DFHDUnnn | Internal trace in transaction dump |
| DFHTRDUF | Internal trace in system dump |
| DFHTRPRA | Auxiliary trace |
| DFHTRPRG | GTF trace |
| Module | Description |
|---|---|
| DFHTRFPB |
Process trace block DFHTRFPB processes a trace block from a dump or auxiliary trace data set, calling DFHTRFFE for each entry in the block. |
| DFHTRFPP |
Process selective print parameters Passed a character string, DFHTRFPP encodes the string as selective print parameters into the TRFCA (for DFHTRPRA and DFHTRPRG only). See Dump utilities (DFHDUnnn and DFHPDnnn) for details of the selective print parameters. |
| DFHTRFFE |
Format trace entry Passed a trace entry, DFHTRFFE calls DFHxxTRI, TRFPRL, and DFHTRFFD to produce the formatted entry. |
| DFHTRFFD |
Format data from entry DFHTRFFD is used to format and print the trace data fields of a particular entry in hex and character form. It calls TRFPRL to print each line. |
| DFHTRIB |
Interpretation build routine DFHTRIB adds printable data to the interpretation buffer in the TRFCA as requested by the interpretation routine. |
| DFHCDCON |
Parameter list decode routine The interpretation of some trace entries requires analysis of domain call parameter lists. DFHCDCON 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. |
| Module | Description |
|---|---|
| DFHAPTRA | MRO entries |
| DFHAPTRB | XRF entries |
| DFHAPTRC | User exit management entries |
| DFHAPTRD | DFHAPDM/DFHAPAP entries |
| DFHAPTRE | Data tables entries |
| DFHAPTRF | SAA communications and resource recovery entries |
| DFHAPTRG | ZC exception and z/OS Communications Server exit entries |
| DFHAPTRI | Application domain entries (router) |
| DFHAPTRJ | ZC z/OS Communications Server interface entries |
| DFHAPTRL | CICS OS/2 LU2 mirror entries. CICS OS/2 is no longer supported. |
| DFHAPTRN | Autoinstall terminal model manager entries |
| DFHAPTRO | LU6.2 application request logic entries |
| DFHAPTRP | Program control entries |
| DFHAPTRR | Partner resource manager entries |
| DFHAPTRS | DFHEISR trace entries |
| DFHAPTRV | DFHSRP trace entries |
| DFHAPTRW | Front End Programming Interface feature entries |
| DFHAPTR0 | Old-style entries |
| DFHAPTR2 | Statistics entries |
| DFHAPTR4 | Transaction manager entries |
| DFHAPTR5 | File control entries |
| DFHAPTR6 | DBCTL entries |
| DFHAPTR7 | Transaction routing entries |
| DFHAPTR8 | Security entries |
| DFHAPTR9 | Interval control entries |
| DFHCCTRI | Local and global catalog domain entries |
| DFHDDTRI | Directory manager entries |
| DFHDMTRI | Domain manager domain entries |
| DFHDSTRI | Dispatcher domain entries |
| DFHDUTRI | Dump domain entries |
| DFHKETRI | Kernel domain entries |
| DFHLDTRI | Loader domain entries |
| DFHLGTRI | Log Manager domain entries |
| DFHL2TRI | Log Manager domain entries |
| DFHLMTRI | Lock manager domain entries |
| DFHMETRI | Message domain entries |
| DFHMNTRI | Monitoring domain entries |
| DFHNQTRI | Enqueue domain entries |
| DFHPATRI | Parameter manager domain entries |
| DFHPGTRI | Program manager domain entries |
| DFHRMTRI | Recovery Manager domain entries |
| DFHSMTRI | Storage manager domain entries |
| DFHSNTRI | Sign-on entries |
| DFHSTTRI | Statistics domain entries |
| DFHTITRI | Timer domain entries |
| DFHTRTRI | Trace domain entries |
| DFHTSITR | Temporary Storage domain entries |
| DFHUSTRI | User domain entries |
| DFHXMTRI | Transaction manager domain entries |
| DFHXSTRI | Security domain entries |
Exits
Global user exit points are not applicable to offline utilities.