DFHTRAP: Assisting the CICS Systems Programmer

by Andy Wright, Brian Johnson
March 1, 2005

A problem investigation may require DFHTRAP to be used over several iterations with the trap logic being refined each time to be more selective as to when the trap executes as the failing environment is better identified. This can reduce the performance impact to CICS when running the trap.

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.