To use DFHTRAP services, there’s a CICS-supplied field engineering transaction called CSFE. You can use it to activate DFHTRAP in the CICS system or to deactivate it. The format of the command to activate DFHTRAP is CSFE DEBUG,TRAP=ON. The corresponding command to deactivate it is CSFE DEBUG,TRAP=OFF. If IBM has instructed you to use DFHTRAP during CICS initialization, code TRAP=ON in the SIT, or as a CICS start-up override in the CICS JCL.
It may be that a version of DFHTRAP needs to be replaced while CICS is active. If so, you can use CSFE to turn the trap off, then use CEMT to SET PROGRAM(DFHTRAP) NEWCOPY and pick up the updated version from a target library. Then, you can reissue CSFE DEBUG, TRAP=ON to begin invoking the new version of DFHTRAP.
DFHTRAP Input and Output Data
The DFHTRADS DSECT contains a series of addresses the CICS Trace Domain passes to DFHTRAP. The most important address fields are the Common System Area (CSA), Task Control Area (TCA), an RSA for DFHTRAP to use, and the most recently written CICS trace entry, which is provided for the trap to analyze. If DFHTRAP is invoked early during CICS start-up, there may be no CSA within the system, meaning its address passed to DFHTRAP will be zeroes. Likewise, not all tasks within CICS have a TCA environment, so there may not be an address to pass to DFHTRAP either.
The parameter list also addresses an 80-byte work area for use by DFHTRAP. An MVS GETMAIN issued by the Trace Domain acquires this; its contents are initialized to binary zeroes when the trap is activated. The work area and its contents then persist until the trap is deactivated. This work area is formatted in both a CICS transaction dump and CICS system dump for offline analysis.
CICS will invoke DFHTRAP for trace entries issued under its various Task Control Blocks (TCBs), but the Trace Domain serializes the trace entries themselves (and use of DFHTRAP).
When DFHTRAP executes, it may or may not need to notify CICS to perform certain actions as a result of its online analysis. The global trap/trace exit parameter list also provides the address of a return-action flag byte. DFHTRAP can set this to indicate what actions should be performed when control returns from it to CICS. The possible actions are:
- The trap may elect for CICS to do nothing. This is the normal result of using a trap. Nearly every invocation doesn’t result in a problem being detected, so the trap has no work to do in gathering diagnostic information.
- The trap may tell CICS to issue a further trace entry, passing data items of interest to be traced by this new trace call (the trace point ID is TR 0103). Note that if a TR 0103 trace entry is made, it will follow the trace entry that caused the trap to run and generate it.