TRAP

TRAP specifies how Language Environment® programs handle abends and program interrupts.

TRAP(ON) must be in effect for the ABTERMENC runtime option to have effect.

This option is similar to the STAE | NOSTAE runtime option that is offered by COBOL, C, and PL/I, and the SPIE | NOSPIE option offered by C and PL/I:

Table 1. TRAP runtime option settings
If Then
A single option is specified in input, TRAP is set according to that option, TRAP(OFF) for NOSTAE or NOSPIE, TRAP(ON) for STAE or SPIE.
Both options are specified in input, TRAP is set ON, unless both options are negative. TRAP is set OFF if both options are negative.
STAE is specified in one #pragma runopts statement, and NOSPIE in another, The option in the last #pragma runopts determines the setting of TRAP.
Multiple instances of STAE | NOSTAE are specified, TRAP is set according to the last instance only. All others are ignored.
Multiple instances of SPIE | NOSPIE are specified, TRAP is set according to the last instance only. All others are ignored.
An options string has TRAP(ON) or TRAP(OFF) together with SPIE | NOSPIE, and/or STAE | NOSTAE, The TRAP setting takes preference over all others.

CEESGL is unaffected by this option.

Non-CICS® default
TRAP=((ON,SPIE),OVR)
CICS default
TRAP=((ON,SPIE),OVR)
Amode 64 default
TRAP=((ON,SPIE),OVR)
Read syntax diagramSkip visual syntax diagram TRAP = ( ( ONOFF , SPIENOSPIE ) , OVRNONOVR )
ON
Fully enables the Language Environment condition handler. ON is the default.
OFF
Prevents language condition handlers or handlers that are registered by CEEHDLR from being notified of abends or program checks. It also prevents application of POSIX signal handling semantics for abends and program checks.
SPIE
SPIE specifies that Language Environment issue an ESPIE macro to handle program interrupts. The SPIE suboption is ignored when specified with the OFF suboption. SPIE is the default.
NOSPIE
NOSPIE specifies that Language Environment will not issue the ESPIE macro. When you specify the ON suboption, Language Environment handles program interrupts and abends by using an ESTAE. The NOSPIE suboption is ignored when specified with the OFF suboption.

Due to the restrictions and side effects when running TRAP(OFF) stated in Usage notes, IBM® highly recommends running TRAP(ON,SPIE) in all environments.

OVR
Specifies that the option can be overridden. OVR is the default.
NONOVR
Specifies that the option cannot be overridden.

CICS considerations

Because Language Environment never sets a SPIE or STAE, the SPIE|NOSPIE suboption is ignored on CICS.

z/OS UNIX considerations

The TRAP option applies to the entire enclave and all threads within.

Usage notes

  • TRAP(OFF) is not supported for AMODE 64 applications.
  • The SPIE | NOSPIE runtime option that is offered by C and PL/I does not affect the TRAP suboptions SPIE and NOSPIE.
  • Use TRAP(OFF) only when you need to analyze a program exception before Language Environment handles it.
  • When you specify TRAP(OFF) in a non-CICS environment, an ESPIE is not issued, but an ESTAE is issued. Language Environment does not handle conditions that are raised by program interrupts or abends initiated by SVC 13 as Language Environment conditions, and does not print messages for such conditions.
  • Running with TRAP(OFF) (for exception diagnosis purposes) can cause many side effects because Language Environment uses condition handling internally and requires TRAP(ON). When you run with TRAP(OFF), you can get side effects even if you do not encounter a software-raised condition, program check, or abend. If you do encounter a program check or an abend with TRAP(OFF) in effect, the following side effects can occur:
    • Fixed-point overflow exceptions are not ignored when the PSW mask is ON. C/C++ and COBOL language semantics expect the exceptions to be ignored. When PL/I is part of the application, the PSW mask is ON.
    • The ABTERMENC runtime option has no effect.
    • The ABPERC runtime option has no effect.
    • Resources that are acquired by Language Environment are not freed.
    • Files that are opened by HLLs are not closed by Language Environment, so records might be lost.
    • The abnormal termination exit is not driven for enclave termination.
    • The assembler user exit is not driven for enclave termination.
    • User condition handlers are not enabled.
    • The debugger is not notified of the error.
    • No storage report or runtime options report is generated.
    • No Language Environment messages or Language Environment dump output is generated.
    • In z/OS UNIX, POSIX signal handling semantics are not enabled for the abend.
    The enclave terminates abnormally if such conditions are raised.
  • TRAP(ON) must be in effect when you use the CEEBXITA assembler user exit for enclave initialization to specify a list of abend codes that Language Environment percolates.
  • When TRAP(ON) is in effect, and the abend code is in the CEEAUE_A_AB_CODES list in CEEBXITA, Language Environment percolates the abend. Normal Language Environment condition handling is never invoked to handle these abends. This feature is useful when you do not want Language Environment condition handling to intervene for certain abend. It is also useful when you want to prevent invocation of the abnormal termination exit for certain abends, such as when IMS issues a user abend code 777.
  • When TRAP(ON,NOSPIE) is specified, Language Environment will handle program interrupts and abends via an ESTAE. This feature is useful when you do not want Language Environment to issue an ESPIE macro. If you do not want Language Environment to issue an ESPIE, you must specify TRAP(OFF).

    When TRAP(OFF), (TRAP(OFF,SPIE) or TRAP(OFF,NOSPIE) is specified and there is a program interrupt, the user exit for termination is not driven.

C++ considerations
TRAP(ON) must be in effect in order for the z/OS® C++ try/throw/catch condition handling mechanisms to work.

For more information