- The trap can instruct CICS to take a system dump of the CICS region if a problem is discovered. The system dump code is TR0103.
Typically, discovery of a problem and the request for a system dump is coupled with a trap also instructing CICS to disable the global trap/trace exit so DFHTRAP is no longer invoked by CICS on subsequent trace entries. This occurs because, if the problem persists, then any subsequent invocations of DFHTRAP would also detect the problem and request further system dumps be taken, which would be unnecessary and have a detrimental effect on the running CICS system.
Some problems are so serious that a DFHTRAP may elect to tell CICS to terminate itself when they’re detected. This action is accompanied by message DFHTR1000. It’s rare that such action is necessary, but the functionality is provided in case it’s ever required.
You can select these return actions in any combination; a given DFHTRAP can elect to set all, some, or no actions when it returns control to CICS.
Often, a DFHTRAP will issue a WTO when it has detected the corruption or problem it was searching for. This is a useful means of identifying the problem occurrence to the CICS systems programmer and ties in with the dump and trace diagnostics that may also be generated by CICS upon return from DFHTRAP.
The CICS system dump formatter VERBX for the TR (Trace) Domain formats information relating to the DFHTRAP being used by CICS and the trap environment. For example, the 80-byte work area contents are formatted as part of the VERBX data.
If using DFHTRAP results in a system dump when a problem is detected, it’s sufficient to just have CICS internal trace active (with a suitably large internal trace table size) because the dump contains the preceding trace entries of interest. Conversely, if DFHTRAP is used to generate additional trace entries, CICS tracing to auxiliary or GTF destinations is more appropriate.
DFHTRAP Usage Models
The DFHTRAP logic can examine the most recently issued trace entry and see whether it’s of interest for problem determination. Some supplied DFHTRAPs only choose to perform further analysis if they’re being driven for particular trace entries. This may be because it’s only relevant to examine certain parts of CICS if certain events are occurring. Another reason may be to limit the overhead of executing a particular version of DFHTRAP to certain trace entries. It might be that a particular problem investigation requires DFHTRAP to run down a great many chained control blocks. This sort of operation might be too expensive in terms of CPU and elapsed time, were the function to be performed on every trace entry. For that reason, DFHTRAPs are often provided with logic to perform their analysis only when invoked for specific trace entries or, for example, when a task switch occurs. In this way, the overhead of using DFHTRAP can be minimized. This approach has to be tempered by appreciating the fact that if the window between successive DFHTRAP invocations is too large, there’s a corresponding increase in the time during which the problem being investigated may occur. The shorter the period between DFHTRAP analysis points, the easier it is to isolate the cause of a problem. This is because there’s less activity within the CICS system to have to consider between the points in time when DFHTRAP last performed its analysis and this invocation.
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.