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

TRAP(ON) must be in effect for the ABTERMENC run-time option to have effect.

This option is similar to the STAE | NOSTAE run-time option currently offered by COBOL, C, and PL/I, and the SPIE | NOSPIE option offered by C and PL/I:

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)

Syntax

                  .-ON--.     .-SPIE---.        .-OVR----.      
>>-TRAP--=--(--(--+-OFF-+--,--+-NOSPIE-+--)--,--+-NONOVR-+--)--><

ON

Fully enables the Language Environment condition handler.

OFF

Prevents language condition handlers or handlers registered by CEEHDLR from being notified of abends or program checks; 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 ignore when specified with the OFF suboption.

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 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.

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

• Restriction: TRAP(OFF) is not supported for AMODE 64 applications.
• The SPIE | NOSPIE runtime option 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 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 acquired by Language Environment are not freed.
  • Files 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 abends or 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

• See ABTERMENC for more information about the ABTERMENC runtime option.
• See z/OS Language Environment Programming Reference for more information about the CEESGL callable service, or the CEEHDLR callable service.
• See z/OS Language Environment Programming Guide for more information about the CEEBXITA assembler user exit.