DFHTRAP: Assisting the CICS Systems Programmer

by Andy Wright, Brian Johnson
March 1, 2005

CICS provides the CETR transaction, which lets the user dynamically control many aspects of CICS trace activity. This includes switching on and off CICS internal and auxiliary tracing, setting the levels of component tracing for the various functional areas in CICS, and using selective tracing for specific transactions and terminals. In addition to the use of CETR, the CICS system initialization parameters, STNTR and SPCTR, can be used to control the initial trace settings. STNTRxx and SPCTRxx can be used to control individual component tracing at CICS start-up.

Selecting higher levels of the standard component tracing is a useful diagnostic tool for determining a problem in a particular CICS domain or component. Likewise, using CICS selective tracing can be helpful when debugging CICS application problems; it provides detailed trace information for a specific program environment.

If DFHTRAP is active, the Trace Domain will also pass control to it as part of the trace operation. This occurs after the trace entry is written (say to internal trace). The Trace Domain provides the exit with a parameter list of information. The supplied DSECT DFHTRADS maps this parameter list.

DFHTRAP is a CICS-supplied assembler program. CICS supplies a sample version containing a basic skeleton of some limited functionality in both the load-module form and also as a source file (in the SDFHMAC library).

It is worth noting that DFHTRAP is not a SLIP trap, nor a trap the operating system or related subsystems provide. It’s shipped with CICS, and (unless activated) is never executed as part of normal CICS function. If the trap hasn’t been activated, the CICS Trace Domain will return control to its caller—having written the trace data without invoking DFHTRAP. This is expected behavior.

You should use the global trap/trace exit only with the guidance of IBM’s service personnel. There are certain restrictions on what operations DFHTRAP may perform. Using DFHTRAP may result in an adverse performance impact on a CICS system if the trap has to execute many instructions to perform its analysis. Also, DFHTRAP can generate a variety of side effects such as requesting CICS system dumps or requesting a system termination. Clearly, it’s a powerful tool and its use should be limited to specific requirements. Typically, these are to detect the occurrence of an error that can’t be diagnosed by another means of problem determination. Some forms of CICS storage overlays, timing windows leading to data corruption, or randomly occurring events leading to specific types of failures, may all require use of DFHTRAP to further IBM analysis.

DFHTRAP is intended to provide the ability to execute some specific code purely to help with the understanding and diagnosis of a particular CICS problem or situation. DFHTRAP is designed so a detailed piece of online diagnosis may be performed as part of normal CICS operations. Having such a diagnostic exit within the Trace Domain is ideal because it lets the trap perform its analysis during the flow of execution from all parts of the CICS system. DFHTRAP is intended to be used in this way without the need to have to stop and then restart the CICS system under investigation, thus making it as transparent to use as possible.