CICS / WebSphere

DFHTRAP: Assisting the CICS Systems Programmer

5 Pages

The sample version of DFHTRAP provided in the SDFHMAC library shows an example of how to request a further trace entry from CICS when control returns from it to CICS. This TR 0103 trace data is written to the currently active trace destinations in the same way as other trace points that are written on the CICS system.

It may be that the analysis DFHTRAP performs results in a program check. With corrupted pointers in CICS, care must be taken that the trap logic doesn’t rely upon them. Typically, program checks will be the result of the corruption that the trap is attempting to catch. Likely program check types are S0C1 (operation exception) and S0C4 (protection exception). You may also see S0C7 program checks (data exceptions) if packed decimal data is involved in the area of the problem.

If a program check in DFHTRAP occurs, CICS will mark the trap as unusable to prevent its execution as part of future Trace Domain invocations. Again, this prevents subsequent invocations of the trap from program checking for the same reason. CICS will also perform First Failure Data Capture (FFDC) by issuing a diagnostic message, DFHTR0001, and taking a CICS system dump (dump code TR1001). This will contain the failing DFHTRAP environment, the registers, and the Program Status Word (PSW) at the time of the program check. The documentation should be supplied to IBM in the normal way for further investigation.

One interesting aspect of the use of a supplied version of DFHTRAP is when it’s written to detect a particular example of data corruption or storage overlay. If the problem is consistent and the area of memory that’s being affected is consistently changed from one value to another, then it may be possible for the DFHTRAP to modify the storage contents back to their original value after it detects the corruption. By gathering the necessary FFDC information at the time of corruption, and using the opportunity to address and re-modify the affected piece of storage, a DFHTRAP can perform repair work in addition to generating the information necessary to determine the cause of the corruption. This online self-correction is particularly useful in cases where the corruption could otherwise lead to serious system stability or data integrity concerns. While it must be used with caution, it’s another important example of the type of work DFHTRAP may be called upon to perform when necessary.

DFHTRAP Restrictions

Again, DFHTRAP should be used only under the guidance of IBM’s service personnel. Consider the issue of restricted functions that must not be performed with the global trap/trace exit. For example, the code added to DFHTRAP must not invoke any CICS services, either directly or indirectly. This would lead to recursion within the CICS Trace Domain environment and unpredictable results. Also, the trap logic must not cause the currently dispatched task to lose control. In other words, CICS Dispatcher services must not be invoked and result in a switch of the task currently dispatched in CICS. In addition, the status of the CICS system must not be changed by the use of DFHTRAP. Invoking the trap should be a transparent operation as far as CICS is concerned. Part of this transparency requires that DFHTRAP saves and restores the general purpose register values around its invocation, so the Trace Domain doesn’t pass control back from DFHTRAP with different register values.

DFHTRAP has a requirement to run with AMODE(31) and RMODE(ANY) attributes. Apart from the need to access CICS control blocks and state data above the 16MB line, there’s also the requirement that DFHTRAP always returns control to the CICS Trace Domain in AMODE(31). In addition, DFHTRAP executes in Storage Key 8 and base space environments with respect to storage protection and transaction isolation.

With the introduction of the Open Transaction Environment (OTE), CICS now provides the support for parallel dispatching of different tasks under their own TCBs. CICS now supports OTE-managed “Open” TCBs for use by environments such as Java Virtual Machines (JVMs) and OpenAPI TRUEs running within CICS. These TCBs may be dispatched and execute their own tasks within CICS simultaneously; each TCB may be executing concurrently under its own Central Processor (CP).

Parallel dispatching within CICS does impose a limitation upon some of the operations DFHTRAP may perform. If a trap needs to analyze state data that may be modified by another task running simultaneously on another TCB, then it’s important that the trap recognize this sort of event may occur. It may be necessary for IBM to write the supplied trap to prevent concurrency situations from affecting DFHTRAP to ensure serialization of certain items of state data while the trap is analyzing them. This is non-trivial and underscores the importance of using DFHTRAP only with guidance from IBM’s service personnel.


DFHXCTRA is a user-replaceable program for use in much the same way as DFHTRAP, but for the External CICS Interface (EXCI) environment. It’s invoked whenever an EXCI trace entry is made. Again, the source is provided in the SDFHMAC library. It has a similar role to DFHTRAP, but is provided to perform analysis within the EXCI address space rather than CICS.


This article has explained the CICS diagnostic trap exit, DFHTRAP. We’ve looked at its typical uses and benefits for performing complex online problem determination with guidance from IBM. For more information, see the CICS bibliography at

5 Pages