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