CICS / WebSphere

DFHTRAP: Assisting the CICS Systems Programmer

5 Pages

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.

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.

5 Pages