Coding the DFHTRAP exit

The source of the skeleton version of the global trap exit DFHTRAP contains comments that explain its use of registers and DSECTs, and the coding required to use the exit.

About this task

The skeleton version of DFHTRAP is supplied in both source and load-module forms. The source of DFHTRAP is cataloged in the CICS720.SDFHMAC library. DFHTRAP runs in AMODE(64).

The 80-byte work area that is provided for the sole use of the global trap exit is in 64-bit storage (storage above the bar). When the global trap exit is activated, the trace domain acquires the storage and initializes it to binary zeros. The working storage exists until the global trap exit is deactivated by the command CSFE DEBUG,TRAP=OFF. In a dump, the DFHTRAP working storage is located as follows:
  • In a CICS transaction dump, the information about DFHTRAP is soon after the CSA optional features list. The 80-byte work area is at the end of the DFHTRAP working storage and is immediately preceded by a 16-byte eye catcher (DFHTRAP_WORKAREA), so that the work area can be located even if it has not been formatted.
  • In a CICS system dump, the DFHTRAP working storage is in the trace domain (TR) section. See Formatting system dumps for details of how to use the TR keyword to format the trace domain information in the dump.

For information about the actions that you can specify for DFHTRAP, see Actions the DFHTRAP exit can take.

Procedure

  • Ensure that the code in DFHTRAP does not use any CICS services, cause the current task to lose control, or change the status of the CICS system.
  • Ensure that DFHTRAP saves and restores the trace domain's registers. The supplied skeleton version contains the code necessary to do this.
    You are strongly advised not to change this code.
  • Ensure that DFHTRAP is specified as AMODE(64) and RMODE(ANY).
    DFHTRAP might switch addressing mode while it is running, but it must always return control to the trace domain in 64-bit mode.
  • Ensure that the library search sequence in the CICS® startup JCL finds the correct version of the load module.