TRAP

TRAP specifies how Language Environment programs handle abends and program interrupts (see Table 1). CEESGL is unaffected by this option.

TRAP(ON) must be in effect for the ABTERMENC runtime option to have effect. This option is similar to options that were offered by earlier versions of COBOL, C, and PL/I runtime libraries:

STAE | NOSTAE runtime option of earlier COBOL, C, and PL/I
SPIE | NOSPIE option offered by earlier C and PL/I

Table 1. TRAP runtime option settings
If ...	Then ...
One 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, or STAE \| NOSTAE	TRAP setting takes preference over all others.

The default value for non-CICS applications is TRAP(ON,SPIE).

The default value for CICS® applications is TRAP(ON,SPIE).

The default value for AMODE 64 applications is TRAP(ON,SPIE).


Syntax

            .-ON--.     .-SPIE---.      
>>-TRAP--(--+-----+--,--+--------+--)--------------------------><
            '-OFF-'     '-NOSPIE-'

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 ignored when specified with the OFF suboption.
NOSPIE: NOSPIE specifies that Language Environment will not issue the ESPIE macro. When you specify the ON, NOSPIE suboption, Language Environment will handle program interrupts and abends via 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 the Usage notes, IBM® highly recommends running TRAP(ON,SPIE) in all environments.

CICS consideration

Since 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

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.
Language Environment requires TRAP(ON) because it uses condition handling internally. As a result, running with TRAP(OFF) for exception diagnosis purposes can cause many side effects. If 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:
- 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.
- The COBOL ON SIZE ERROR clause may be disabled for arithmetic statements.
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.
C++ consideration—TRAP(ON) must be in effect in order for the z/OS® XL C++ try, throw, and catch condition handling mechanisms to work.
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 in a non-CICS environment, 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.
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.

For more information

See ABTERMENC for more information about the ABTERMENC runtime option.
See CEESGL—Signal a condition for more information about the CEESGL callable service.
For more information about the CEEHDLR callable service, see CEEHDLR—Register user-written condition handler.
See z/OS Language Environment Programming Guide, for more information about the CEEBXITA assembler user exit.