HP OpenVMS systems documentation

1. Procedure A establishes condition handler HANDLER A. HANDLER A is set up to respond to exceptions caused by failures in system service calls.
2. During its execution, procedure A calls procedure B.
3. Procedure B establishes condition handler HANDLER B. HANDLER B is set up to respond to breakpoint faults.
4. While procedure B is executing, an exception occurs caused by a system service failure (SS$_FAIL).
5. The exception dispatcher gets control and finds the first condition handler (handler b). Handler B is set to handle SS$_BREAK, not SS$_SSFAIL so it returns SS$_RESIGNAL.
6. Upon receiving the SS$_RESIGNAL status from HANDLER B, the exception dispatcher resumes its search for a condition handler. It finds and calls handler a.
7. HANDLER A handles the system service failure exception, corrects the condition, places the return value SS$_CONTINUE in r0 (r8 if this example were run on an I64 system), and returns control to the exception dispatcher, which will, in turn, return control to procedure B. Execution of procedure B resumes at the instruction following the system service failure.

You can debug a condition handler as you would any subprogram, except that you cannot use the DEBUG command STEP/INTO to enter a condition handler. You must set a breakpoint in the handler and wait for the debugger to invoke the handler.

Typically, to trace execution of a condition handler, you set breakpoints at the statement in your program that should signal the condition code, at the statement following the one that should signal, and at the first executable statement in your condition handler.

The SET BREAK debugger command with the /HANDLER qualifier causes the debugger to scan the call stack and attempt to set a breakpoint on every established frame-based handler whenever the program being debugged has an exception. The debugger does not discriminate between standard RTL handlers and user-defined handlers.

9.14 Run-Time Library Condition-Handling Routines

The following sections present information about RTL jacket handlers, and RTL routines that can be either established as condition handlers or called from a condition handler to handle signaled exception conditions.

9.14.1 RTL Jacket Handlers (Alpha and I64 Only)

Many RTLs establish a jacket RTL handler on a frame where the user program has defined its own handler. This RTL jacket does some setup and argument manipulation before actually calling the handler defined by the user. When processing the exception, the debugger sets the breakpoint on the jacket RTL jacket handler, because that is the address on the call stack. If the debugger suspends program execution at a jacket RTL handler, it is usually possible to reach the user-defined handler by entering a STEP/CALL command followed by a STEP/INTO command. Some cases might require that additional sequences of STEP/CALL and STEP/INTO commands be entered. For more information about frame-based handlers, see HP OpenVMS Calling Standard.

If the jacket RTL handler is part of an installed shared image such as ALPHA LIBOTS, the debugger cannot set a breakpoint on it. In this case, activate the RTL as a private image by defining the RTL as a logical name, as in the following example:

$DEFINE LIBOTS SYS$SHARE:LIBOTS.EXE;

On VAX systems, a trap is an exception condition that is signaled after the instruction that caused it has finished executing. A fault is an exception condition that is signaled during the execution of the instruction. When a trap is signaled, the program counter (PC) in the signal argument vector points to the next instruction after the one that caused the exception condition. When a fault is signaled, the PC in the signal argument vector points to the instruction that caused the exception condition. See the VAX Architecture Reference Manual for more information about faults and traps.

LIB$SIM_TRAP can be established as a condition handler or be called from a condition handler to convert a floating-point fault to a floating-point trap. After LIB$SIM_TRAP is called, the PC points to the instruction after the one that caused the exception condition. Thus, your program can continue execution without fixing up the original condition. LIB$SIM_TRAP intercepts only floating-point overflow, floating-point underflow, and divide-by-zero faults.

9.14.3 Changing a Signal to a Return Status

When it is preferable to detect errors by signaling but the calling routine expects a returned status, LIB$SIG_TO_RET can be used by the routine that signals. For instance, if you expect a particular condition code to be signaled, you can prevent the operating system from invoking the default condition handler by establishing a different condition handler. LIB$SIG_TO_RET is a condition handler that converts any signaled condition to a return status. The status is returned to the caller of the routine that established LIB$SIG_TO_RET. You may establish LIB$SIG_TO_RET as a condition handler by specifying it in a call to LIB$ESTABLISH.

On Alpha and I64 systems, LIB$ESTABLISH is not supported, though high-level languages may support it for compatibility.

LIB$SIG_TO_RET can also be called from another condition handler. If LIB$SIG_TO_RET is called from a condition handler, the signaled condition is returned as a function value to the caller of the establisher of that handler when the handler returns to the OpenVMS Condition Handling facility. When a signaled exception condition occurs, LIB$SIG_TO_RET routine does the following:

• Places the signaled condition value in the image of R0 (R8 for I64) that is saved as part of the mechanism argument vector.
• Calls the Unwind (SYS$UNWIND) system service with the default arguments. After returning from LIB$SIG_TO_RET (when it is established as a condition handler) or after returning from the condition handler that called LIB$SIG_TO_RET (when LIB$SIG_TO_RET is called from a condition handler), the stack unwinds to the caller of the routine that established the handler.

Your calling routine can now both test R0 (R8 for I64), as if the called routine had returned a status, and specify an error recovery action.

The following paragraphs describe how to establish and use the system-defined condition handler LIB$SIG_TO_RET, which changes a signal to a return status that your program can examine.

To change a signal to a return status, you must put any code that might signal a condition code into a function where the function value is a return status. The function containing the code must perform the following operations:

• Declare LIB$SIG_TO_RET---Declare the condition handler LIB$SIG_TO_RET.
• Establish LIB$SIG_TO_RET---Invoke the run-time library procedure LIB$ESTABLISH to establish a condition handler for the current program unit. Specify the name of the condition handler LIB$SIG_TO_RET as the only argument.
• Initialize the function value---Initialize the function value to SS$_NORMAL so that, if no condition code is signaled, the function returns a success status to the invoking program unit.
• Declare necessary dummy arguments---If any statement that might signal a condition code is a subprogram that requires dummy arguments, pass the necessary arguments to the function. In the function, declare each dummy argument exactly as it is declared in the subprogram that requires it and specify the dummy arguments in the subprogram invocation.

If the program unit GET_1_STAT in the following function signals a condition code, LIB$SIG_TO_RET changes the signal to the return status of the INTERCEPT_SIGNAL function and returns control to the program unit that invoked INTERCEPT_SIGNAL. (If GET_1_STAT has a condition handler established, the operating system invokes that handler before invoking LIB$SIG_TO_RET.)

FUNCTION INTERCEPT_SIGNAL (STAT, 2 ROW, 2 COLUMN) ! Dummy arguments for GET_1_STAT INTEGER STAT, 2 ROW, 2 COLUMN ! Declare SS$_NORMAL INCLUDE '($SSDEF)' ! Declare condition handler EXTERNAL LIB$SIG_TO_RET ! Declare user routine INTEGER GET_1_STAT ! Establish LIB$SIG_TO_RET CALL LIB$ESTABLISH (LIB$SIG_TO_RET) ! Set return status to success INTERCEPT_SIGNAL = SS$_NORMAL ! Statements and/or subprograms that ! signal expected error condition codes STAT = GET_1_STAT (ROW, 2 COLUMN) END

When the program unit that invoked INTERCEPT_SIGNAL regains control, it should check the return status (as shown in Section 9.5.1) to determine which condition code, if any, was signaled during execution of INTERCEPT_SIGNAL.

9.14.4 Changing a Signal to a Stop

LIB$SIG_TO_STOP causes a signal to appear as though it had been signaled by a call to LIB$STOP.

LIB$SIG_TO_STOP can be enabled as a condition handler for a routine or be called from a condition handler. When a signal is generated by LIB$STOP, the severity code is forced to severe, and control cannot return to the routine that signaled the condition. See Section 9.12.1 for a description of continuing normal execution after a signal.

9.14.5 Matching Condition Values

LIB$MATCH_COND checks for a match between two condition values to allow a program to branch according to the condition found. If no match is found, the routine returns zero. The routine matches only the condition identification field (STS$V_COND_ID) of the condition value; it ignores the control bits and the severity field. If the facility-specific bit (STS$V_FAC_SP = bit <15>) is clear in cond-val (meaning that the condition value is systemwide), LIB$MATCH_COND ignores the facility code field (STS$V_FAC_NO = bits <27:17>) and compares only the STS$V_MSG_ID fields (bits <15:3>).

9.14.6 Correcting a Reserved Operand Condition (VAX Only)

On VAX systems, after a signal of SS$_ROPRAND during a floating-point instruction, LIB$FIXUP_FLT finds the operand and changes it from --0.0 to a new value or to +0.0.

9.14.7 Decoding the Instruction That Generated a Fault (VAX Only)

On VAX systems, LIB$DECODE_FAULT locates the operands for an instruction that caused a fault and passes the information to a user action routine. When called from a condition handler, LIB$DECODE_FAULT locates all the operands and calls an action routine that you supply. Your action routine performs the steps necessary to handle the exception condition and returns control to LIB$DECODE_FAULT. LIB$DECODE_FAULT then restores the operands and the environment, as modified by the action routine, and continues execution of the instruction.

9.15 Exit Handlers

When an image exits, the operating system performs the following operations:

• Invokes any user-defined exit handlers.
• Invokes the system-defined default exit handler, which closes any files that were left open by the program or by user-defined exit handlers.
• Executes a number of cleanup operations collectively known as image rundown. The following is a list of some of these cleanup operations:
  • Canceling outstanding ASTs and timer requests.
  • Deassigning any channel assigned by your program and not already deassigned by your program or the system.
  • Deallocating devices allocated by the program.
  • Disassociating common event flag clusters associated with the program.
  • Deleting user-mode logical names created by the program. (Unless you specify otherwise, logical names created by SYS$CRELNM are user-mode logical names.)
  • Restoring internal storage (for example, stacks or mapped sections) to its original state.

If any exit handler exits using the EXIT (SYS$EXIT) system service, none of the remaining handlers is executed. In addition, if an image is aborted by the DCL command STOP (the user presses Ctrl/Y and then enters STOP), the system performs image rundown and does not invoke any exit handlers. Like the DCL STOP/ID, SYS$DELPRC bypasses all exit handlers, except the rundown specified in the privileged library vector (PLV) privileged shareable images, and deletes the process. (The DCL command EXIT invokes the exit handlers before running down the image.)

When a routine is active under OpenVMS, it has available to it temporary storage on a stack, in a construct known as a stack frame, or call frame. Each time a subroutine call is made, another call frame is pushed onto the stack and storage is made available to that subroutine. Each time a subroutine returns to its caller, the subroutine's call frame is pulled off the stack, and the storage is made available for reuse by other subroutines. Call frames therefore are nested. Outer call frames remain active longer, and the outermost call frame, the call frame associated with the main routine, is normally always available.

A primary exception to this call frame condition is when an exit handler runs. With an exit handler running, only static data is available. The exit handler effectively has its own call frame. Exit handlers are declared with the SYS$DCLEXH system service.

The use of call frames for storage means that all routine-local data is reentrant; that is, each subroutine has its own storage for the routine-local data.

The allocation of storage that is known to the exit handler must be in memory that is not volatile over the possible interval the exit handler might be pending. This means you must be familiar with how the compilers allocate routine-local storage using the stack pointer and the frame pointer. This storage is valid only while the stack frame is active. Should the routine that is associated with the stack frame return, the exit handler cannot write to this storage without having the potential for some severe application data corruptions.

A hang-up to a terminal line causes DCL to delete the master process's subprocesses. However, if the subprocesses's exit handler is in a main image installed with privilege, then that exit handler is run even with the DCL command STOP. Also, if the subprocess was spawned NOWAIT, then the spawning process's exit handler is run as well.

Use exit handlers to perform any cleanup that your program requires in addition to the normal rundown operations performed by the operating system. In particular, if your program must perform some final action regardless of whether it exits normally or is aborted, you should write and establish an exit handler to perform that action.

9.15.1 Establishing an Exit Handler

To establish an exit handler, use the SYS$DCLEXH system service. The SYS$DCLEXH system service requires one argument---a variable-length data structure that describes the exit handler. Figure 9-17 illustrates the structure of an exit handler.

Figure 9-17 Structure of an Exit Handler

The first longword of the structure contains the address of the next handler. The operating system uses this argument to keep track of the established exit handlers; do not modify this value. The second longword of the structure contains the address of the exit handler being established. The low-order byte of the third longword contains the number of arguments to be passed to the exit handler. Each of the remaining longwords contains the address of an argument.

The first argument passed to an exit handler is an integer value containing the final status of the exiting program. The status argument is mandatory. However, do not supply the final status value; when the operating system invokes an exit handler, it passes the handler the final status value of the exiting program.

To pass an argument with a numeric data type, use programming language statements to assign the address of a numeric variable to one of the longwords in the exit-handler data structure. To pass an argument with a character data type, create a descriptor of the following form:

Use the language statements to assign the address of the descriptor to one of the longwords in the exit-handler data structure.

The following program segment establishes an exit handler with two arguments, the mandatory status argument and a character argument:

. . . ! Arguments for exit handler INTEGER EXIT_STATUS ! Status CHARACTER*12 STRING ! String STRUCTURE /DESCRIPTOR/ INTEGER SIZE, 2 ADDRESS END STRUCTURE RECORD /DESCRIPTOR/ EXIT_STRING ! Setup for exit handler STRUCTURE /EXIT_DESCRIPTOR/ INTEGER LINK, 2 ADDR, 2 ARGS /2/, 2 STATUS_ADDR, 2 STRING_ADDR END STRUCTURE RECORD /EXIT_DESCRIPTOR/ HANDLER ! Exit handler EXTERNAL EXIT_HANDLER . . . ! Set up descriptor EXIT_STRING.SIZE = 12 ! Pass entire string EXIT_STRING.ADDRESS = %LOC (STRING) ! Enter the handler and argument addresses ! into the exit handler description HANDLER.ADDR = %LOC(EXIT_HANDLER) HANDLER.STATUS_ADDR = %LOC(EXIT_STATUS) HANDLER.STRING_ADDR = %LOC(EXIT_STRING) ! Establish the exit handler CALL SYS$DCLEXH (HANDLER) . . .

An exit handler can be established at any time during your program and remains in effect until it is canceled (with SYS$CANEXH) or executed. If you establish more than one handler, the handlers are executed in reverse order: the handler established last is executed first; the handler established first is executed last.

9.15.2 Writing an Exit Handler

Write an exit handler as a subroutine, because no function value can be returned. The dummy arguments of the exit subroutine should agree in number, order, and data type with the arguments you specified in the call to SYS$DCLEXH.

In the following example, assume that two or more programs are cooperating with each other. To keep track of which programs are executing, each has been assigned a common event flag (the common event flag cluster is named ALIVE). When a program begins, it sets its flag; when the program terminates, it clears its flag. Because it is important that each program clear its flag before exiting, you create an exit handler to perform the action. The exit handler accepts two arguments, the final status of the program and the number of the event flag to be cleared. In this example, since the cleanup operation is to be performed regardless of whether the program completes successfully, the final status is not examined in the exit routine. (This subroutine would not be used with the exit handler declaration in the previous example.)

CLEAR_FLAG.FOR

SUBROUTINE CLEAR_FLAG (EXIT_STATUS, 2 FLAG) ! Exit handler clears the event flag ! Declare dummy argument INTEGER EXIT_STATUS, 2 FLAG ! Declare status variable and system routine INTEGER STATUS, 2 SYS$ASCEFC, 2 SYS$CLREF ! Associate with the common event flag ! cluster and clear the flag STATUS = SYS$ASCEFC (%VAL(FLAG), 2 'ALIVE',,) IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS)) STATUS = SYS$CLREF (%VAL(FLAG)) IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS)) END

If for any reason you must perform terminal I/O from an exit handler, use appropriate RTL routines. Trying to access the terminal from an exit handler using language I/O statements may cause a redundant I/O error.

9.15.3 Debugging an Exit Handler

To debug an exit handler, you must set a breakpoint in the handler and wait for the operating system to invoke that handler; you cannot use the DEBUG command STEP/INTO to enter an exit handler. In addition, when the debugger is invoked, it establishes an exit handler that exits using the SYS$EXIT system service. If you invoke the debugger when you invoke your image, the debugger's exit handler does not affect your program's handlers because the debugger's handler is established first and so executes last. However, if you invoke the debugger after your program begins executing (the user presses Ctrl/Y and then types DEBUG), the debugger's handler may affect the execution of your program's exit handlers, because one or more of your handlers may have been established before the debugger's handler and so is not executed.

9.15.4 Example of Exit Handler

As in the example in Section 9.15.2, write the exit handler as a subroutine because no function value can be returned. The dummy arguments of the exit subroutine should agree in number, order, and data type with the arguments you specify in the call to SYS$DCLEXH.

In the following example, assume that two or more programs are cooperating. To keep track of which programs are executing, each has been assigned a common event flag (the common event flag cluster is named ALIVE). When a program begins, it sets its flag; when the program terminates, it clears its flag. Because each program must clear its flag before exiting, you create an exit handler to perform the action. The exit handler accepts two arguments: the final status of the program and the number of the event flag to be cleared.

In the following example, because the cleanup operation is to be performed regardless of whether the program completes successfully, the final status is not examined in the exit routine.

! Arguments for exit handler INTEGER*4 EXIT_STATUS ! Status INTEGER*4 FLAG /64/ ! Setup for exit handler STRUCTURE /EXIT_DESCRIPTOR/ INTEGER LINK, 2 ADDR, 2 ARGS /2/, 2 STATUS_ADDR, 2 FLAG_ADDR END STRUCTURE RECORD /EXIT_DESCRIPTOR/ HANDLER ! Exit handler EXTERNAL CLEAR_FLAG INTEGER*4 STATUS, 2 SYS$ASCEFC, 2 SYS$SETEF ! Associate with the common event flag ! cluster and set the flag. STATUS = SYS$ASCEFC (%VAL(FLAG), 2 'ALIVE',,) IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS)) STATUS = SYS$SETEF (%VAL(FLAG)) IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS)) ! Do not exit until cooperating program has a chance to ! associate with the common event flag cluster. ! Enter the handler and argument addresses ! into the exit handler description. HANDLER.ADDR = %LOC(CLEAR_FLAG) HANDLER.STATUS_ADDR = %LOC(EXIT_STATUS) HANDLER.FLAG_ADDR = %LOC(FLAG) ! Establish the exit handler. CALL SYS$DCLEXH (HANDLER) ! Continue with program . . . END ! Exit Subroutine SUBROUTINE CLEAR_FLAG (EXIT_STATUS, 2 FLAG) ! Exit handler clears the event flag ! Declare dummy argument INTEGER EXIT_STATUS, 2 FLAG ! Declare status variable and system routine INTEGER STATUS, 2 SYS$ASCEFC, 2 SYS$CLREF ! Associate with the common event flag ! cluster and clear the flag STATUS = SYS$ASCEFC (%VAL(FLAG), 2 'ALIVE',,) 2 'ALIVE',,) IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS)) STATUS = SYS$CLREF (%VAL(FLAG)) IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS))