TRAP - trap signals

`TRAP` - trap signals

SYNOPSIS

<TRAP [CONNRESET=on|off|N] [[SIGNALS=]on|off|N]>

DESCRIPTION
The TRAP directive sets whether to trap signals or not; by default signals are trapped. This directive is for diagnostic purposes and is not typically used by production scripts. The SIGNALS value is a bit-wise ORed integer of the following values:

0x0001: Catch non-ABEND signals (e.g. SIGTERM)
0x0002: Catch ABEND signals (e.g. SIGSEGV)
0x0004: Try to dump core after ABEND via NULL dereference
0x0008: Try to dump core after ABEND via signal return
0x0010: Print registers at ABEND
0x0020: Print 1KB of stack at ABEND
0x0040: Print 16KB of stack at ABEND
0x0080: Print location details (if known) at ABEND
0x0100: Ignore SIGHUP signals (Unix)
0x0200: Treat timeout as ABEND, i.e. try to dump core if 0x0004 set
0x0400: Print command line of signalling PID if known
0x0800: Same info as 0x0400, but also for signalling PPID. If 0x0400 set too, print info for signaller's entire ancestry.
0x1000: Print a backtrace for ABEND signals

The default value "on" is the same as 0x1493; "off" is 0.

The value 0x0080 was added and became part of the default in version 5.00.1088099065 20040624. The value 0x0100 was added in version 5.01.1103822414 20041223. The value 0x0200 was added in version 7.02.1405112000 20140711. The values 0x0400 and 0x0800 were added (and 0x0400 added to default) in version 7.05.1449114000 20151202. The 0x1000 flag was added (and added to default) in version 7.06.1468000000 20160708. The 0x0010 flag was added to the default in version 7.06.1512512000 20171205.

The CONNRESET option was added in version 3.01.989300000 20010507, and controls whether to trap connection-reset on stdout, i.e. when the remote browser prematurely terminates the connection (user hits stop button). Its bit flags are defined as follows:

0x0001: Trap SIGIO SO_ERROR recognized error
0x0002: Trap SIGIO MSG_PEEK recognized error
0x0004: Trap SIGIO MSG_PEEK no data
0x0008: Log truncated standard-out data if possible
0x0010: Debug print on every SIGIO
0x0020: Continue; do not exit if connection-reset detected

The default value "on" is the same as 3; "off" is 0. In versions prior to 8.01.1683743854 20230510 the default was 7.

The TRAP directive can be overridden at run time by the command-line option -x (for the SIGNALS value only; here), which in turn can be overridden by the trap setting of the vxcp function (here).

EXAMPLE

<TRAP off>

<A NAME=main>
  ... script code to analyze ...
</A>

CAVEATS
The <TRAP> directive was added in version 3.0.947100000 20000105.

Turning off signals can cause aberrant behavior, particularly with <EXEC> and <TIMEOUT>.

Not all SIGNALS flags are supported on all platforms; in particular the printing flags.

The bit flags may change in future versions. The values are documented as of version 4.03.

In versions prior to 8.01.1683743854 20230510 the default CONNRESET value was 7.