DFHTRAP: Assisting the CICS Systems Programmer

by Andy Wright, Brian Johnson
March 1, 2005

Receiving Updates to DFHTRAP

If IBM requests you run a version of DFHTRAP to generate additional diagnostic information, the CICS Change Team or Level 2 service personnel will provide you with an updated version of the code containing the specific instructions necessary to analyze the particular areas of interest and carry out the required diagnostics. This may be in the form of a usermod containing a ++MOD for DFHTRAP’s object module; alternatively, the changes may be provided as a source delta in ++MACUPD format. A source delta can be applied to the source version of DFHTRAP as originally supplied in SDFHMAC and reassembled ready for use in CICS.

Only one DFHTRAP may exist in a CICS system at any time. In the unlikely event that more than one problem needs to be trapped, a composite DFHTRAP would be required to investigate the problems.

Managing DFHTRAP

To use DFHTRAP services, there’s a CICS-supplied field engineering transaction called CSFE. You can use it to activate DFHTRAP in the CICS system or to deactivate it. The format of the command to activate DFHTRAP is CSFE DEBUG,TRAP=ON. The corresponding command to deactivate it is CSFE DEBUG,TRAP=OFF. If IBM has instructed you to use DFHTRAP during CICS initialization, code TRAP=ON in the SIT, or as a CICS start-up override in the CICS JCL.

It may be that a version of DFHTRAP needs to be replaced while CICS is active. If so, you can use CSFE to turn the trap off, then use CEMT to SET PROGRAM(DFHTRAP) NEWCOPY and pick up the updated version from a target library. Then, you can reissue CSFE DEBUG, TRAP=ON to begin invoking the new version of DFHTRAP.

DFHTRAP Input and Output Data

The DFHTRADS DSECT contains a series of addresses the CICS Trace Domain passes to DFHTRAP. The most important address fields are the Common System Area (CSA), Task Control Area (TCA), an RSA for DFHTRAP to use, and the most recently written CICS trace entry, which is provided for the trap to analyze. If DFHTRAP is invoked early during CICS start-up, there may be no CSA within the system, meaning its address passed to DFHTRAP will be zeroes. Likewise, not all tasks within CICS have a TCA environment, so there may not be an address to pass to DFHTRAP either.

The parameter list also addresses an 80-byte work area for use by DFHTRAP. An MVS GETMAIN issued by the Trace Domain acquires this; its contents are initialized to binary zeroes when the trap is activated. The work area and its contents then persist until the trap is deactivated. This work area is formatted in both a CICS transaction dump and CICS system dump for offline analysis.

CICS will invoke DFHTRAP for trace entries issued under its various Task Control Blocks (TCBs), but the Trace Domain serializes the trace entries themselves (and use of DFHTRAP).

When DFHTRAP executes, it may or may not need to notify CICS to perform certain actions as a result of its online analysis. The global trap/trace exit parameter list also provides the address of a return-action flag byte. DFHTRAP can set this to indicate what actions should be performed when control returns from it to CICS. The possible actions are: