Compaq COBOL AAQ2G1FTK - Manual (Page 478)

Using Compaq COBOL in the Alpha Common Language Environment
13.5 Establishing and Removing User Condition Handlers (OpenVMS)
new-handler
Specifies the name of the routine to be set up as a condition handler.
old-handler
Receives the address of the previously established condition handler.
The GIVING phrase is optional.
LIB$ESTABLISH moves the address of the condition-handling routine into the
appropriate process context and returns the address of a previously established
condition handler.
The handler itself could be a user-written routine, or a library routine. The
following example shows how a call to establish a user-written handler might be
coded:
01 HANDLER PIC S9(9) COMP VALUE EXTERNAL HANDLER_ROUT.
01 OLD-HANDLER PIC S9(9) COMP.
.
.
.
CALL "LIB$ESTABLISH" USING BY VALUE HANDLER GIVING OLD-HANDLER.
In the preceding example, HANDLER_ROUT is the name of a program that is
established as the condition handler for the program unit containing these source
statements. A program unit can remove an established condition handler in two
ways:
• Issue another LIB$ESTABLISH call which specifies a different handler.
• Issue the LIB$REVERT call.
The LIB$REVERT call has no arguments:
CALL "LIB$REVERT".
This call removes the condition handler established in the current program unit.
Note that the LIB$ESTABLISH and LIB$REVERT routines only affect user
condition handlers, not the default Compaq COBOL condition handler. When
an exception occurs, the user condition handler, if one exists, is executed first,
followed by the Compaq COBOL condition handler, if the user condition handler
could not handle the exception.
When a program unit returns to its caller, the condition handler associated with
that program unit is automatically removed (the program unit’s stack frame,
which contains the condition handler address, is removed from the stack).
Example 13–1 illustrates a user written condition handling routine that
determines the reason for a system service failure. The example handler handles
only one type of exception, system service failures. All other exceptions are
resignalled, allowing them to be handled by the system default handlers. This
handler is useful because the system traceback handler indicates only that a
system service failure occurred, not which specific error caused the failure.
LIB$ESTABLISH is used by the main program, SSCOND, to establish the user
written condition handler, SSHAND. System service failure mode is enabled so
that errors in system service calls will initiate a search for a condition handler.
13–16 Using Compaq COBOL in the Alpha Common Language Environment