Updated: 11 December 1998

OpenVMS Programming Concepts Manual

When an exception occurs, control is passed to the operating system's exception-dispatching routine. The exception dispatcher searches for a condition-handling routine invoking the first handler it finds and passes the information to the handler about the condition code and the state of the program when the condition code was signaled. If the handler resignals, the operating system searches for another handler; otherwise, the search for a condition handler ends.

The operating system searches for condition handlers in the following sequence:

1. Primary exception vectors---Four vectors (lists) of one or more condition handlers; each vector is associated with an access mode. By default, all of the primary exception vectors are empty. Exception vectors are used primarily for system programming, not application programming. The debugger uses the primary exception vector associated with user mode.
   When an exception occurs, the operating system searches the primary exception associated with the access mode at which the exception occurred. To enter or cancel a condition handler in an exception vector, use the SYS$SETEXV system service. Condition handlers that are entered into the exception vectors associated with kernel, executive, and supervisor modes remain in effect until they are canceled or until you log out. Condition handlers that are entered into the exception vector associated with user mode remain in effect until they are canceled or until the image that entered them exits.
2. Secondary exception vectors---A set of exception vectors with the same structure as the primary exception vectors. Exception vectors are primarily used for system programming, not application programming. By default, all of the secondary exception vectors are empty.
3. Call frame condition handlers---Each program unit can establish one condition handler (the address of the handler is placed in the call frame of the program unit). The operating system searches for condition handlers established by your program, beginning with the current program unit. If the current program unit has not established a condition handler, the operating system searches for a handler that was established by the program unit that invoked the current program unit, and so on back to the main program.
4. Traceback handler---If you do not establish any condition handlers and link your program with the /TRACEBACK qualifier of the LINK command (the default), the operating system finds and invokes the traceback handler.
5. Catchall handler---If you do not establish any condition handlers and you link your program with the /NOTRACEBACK qualifier to the LINK command, the operating system finds and invokes the catchall handler. The catchall handler is at the bottom of the user stack and in the last-chance exception vector.
6. Last-chance exception vectors---A set of exception vectors with the same structure as the primary and secondary exception vectors. Exception vectors are used primarily for system programming, not application programming. By default, the user- and supervisor-mode last-chance exception vectors are empty. The executive- and kernel-mode last-chance exception vectors contain procedures that cause a bugcheck (a nonfatal bugcheck results in an error log entry; a fatal bugcheck results in a system shutdown). The debugger uses the user-mode last-chance exception vector, and DCL uses the supervisor-mode last-chance exception vector.

The search is terminated when the dispatcher finds a condition handler. If the dispatcher cannot find a user-specified condition handler, it calls the condition handler whose address is stored in the last-chance exception vector. If the image was activated by the command language interpreter, the last-chance vector points to the catchall condition handler. The catchall handler issues a message and either continues program execution or causes the image to exit, depending on whether the condition was a warning or an error condition, respectively.

You can call the catchall handler in two ways:

• If the last-chance exception vector returns to the dispatcher or if the last-chance exception vector is empty, the last-chance exception vector calls the catchall condition handler and exits with the return status code SS$_NOHANDLER.
• If the exception dispatcher detects an access violation, it calls the catchall condition handler and exits with the return status code SS$_ACCVIO.

Figure 15-4 illustrates the exception dispatcher's search of the call stack for a condition handler.

Figure 15-4 Searching the Stack for a Condition Handler

In cases where the default condition handling is insufficient, you can establish your own handler by one of the mechanisms described in Section 15.2.1. Typically, you need condition handlers only if your program must perform one of the following operations:

• Respond to condition values that are signaled rather than returned, such as an integer overflow error. ( Section 15.14.3 describes the system-defined handler LIB$SIG_TO_RET that allows you to treat signals as return values; Section 15.4.2 describes other useful system-defined handlers for arithmetic errors.)
• Modify part of a condition code, such as the severity. See Section 15.5.2 for more information. If you want to change the severity of any condition code to a severe error, you can use the run-time library procedure LIB$STOP instead of writing your own condition handler.
• Add messages to the one associated with the originally signaled condition code or log the messages associated with the originally signaled condition code.

On VAX systems, the argument list passed to the condition handler is constructed on the stack and consists of the addresses of two argument arrays, signal and mechanism, as illustrated in Section 15.8.2 and Section 15.8.3.

On Alpha systems, the arrays are set up on the stack, but any argument is passed in registers.

On VAX systems, you can use the $CHFDEF macro instruction to define the symbolic names to refer to the arguments listed in Table 15-9.

Table 15-9 $CHFDEF Symbolic Names and Arguments on VAX Systems

Symbolic Name	Related Argument
CHF$L_SIGARGLST	Address of signal array
CHF$L_MCHARGLST	Address of mechanism array
CHF$L_SIG_ARGS	Number of signal arguments
CHF$L_SIG_NAME	Condition name
CHF$L_SIG_ARG1	First signal-specific argument
CHF$L_MCH_ARGS	Number of mechanism arguments
CHF$L_MCH_FRAME	Establisher frame address
CHF$L_MCH_DEPTH	Frame depth of establisher
CHF$L_MCH_SAVR0	Saved register R0
CHF$L_MCH_SAVR1	Saved register R1

On Alpha systems, you can use the $CHFDEF2 macro instruction to define the symbolic names to refer to the arguments listed in Table 15-10.

Table 15-10 $CHFDEF2 Symbolic Names and Arguments on Alpha Systems

Symbolic Name	Related Argument
CHF$L_SIGARGLST	Address of signal array
CHF$L_MCHARGLST	Address of mechanism array
CHF$IS_SIG_ARGS	Number of signal arguments
CHF$IS_SIG_NAME	Condition name
CHF$IS_SIG_ARG1	First signal-specific argument
CHF$IS_MCH_ARGS	Number of mechanism arguments
CHF$IS_MCH_FLAGS	Flag bits <63:0> for related argument mechanism information
CHF$PH_MCH_FRAME	Establisher frame address
CHF$IS_MCH_DEPTH	Frame depth of establisher
CHF$PH_MCH_DADDR	Address of the handler data quadword if the exception handler data field is present
CHF$PH_MCH_ESF_ADDR	Address of the exception stack frame
CHF$PH_MCH_SIG_ADDR	Address of the signal array
CHF$IH_MCH_SAVR nn	Contains a copy of the saved integer registers at the time of the exception
CHF$FH_MCH_SAVF nn	Contains a copy of the saved floating-point registers at the time of the exception

15.8 Signaling

Signaling can be initiated when hardware or software detects an exception condition. In either case, the exception condition is said to be signaled by the routine in which it occurred. If hardware detects the error, it passes control to a condition dispatcher. If software detects the error, it calls one of the run-time library signal-generating routines: LIB$SIGNAL or LIB$STOP. The RTL signal-generating routines pass control to the same condition dispatcher. When LIB$STOP is called, the severity code is forced to severe, and control cannot return to the routine that signaled the condition. See Section 15.12.1 for a description of how a signal can be dismissed and how normal execution from the point of the exception condition can be continued.

When a routine signals, it passes to the OpenVMS Condition Handling facility (CHF) the condition value associated with the exception condition, as well as optional arguments that can be passed to a condition handler. The CHF uses these arguments to build two data structures on the stack:

• The signal argument vector. This vector contains the information describing the nature of the exception condition.
• The mechanism argument vector. This vector describes the state of the process at the time the exception condition occurred.

These two vectors become the arguments that the CHF passes to condition handlers.

These argument vectors are described in detail in Section 15.8.2 and Section 15.8.3.

After the signal and mechanism argument vectors are set up, the CHF searches for enabled condition handlers. A condition handler is a separate routine that has been associated with a routine in order to take a specific action when an exception condition occurs. The CHF searches for condition handlers to handle the exception condition, beginning with the primary exception vector of the access mode in which the exception condition occurred. If this vector contains the address of a handler, that handler is called. If the address is 0 or if the handler resignals, then the CHF repeats the process with the secondary exception vector. Enabling vectored handlers is discussed in detail in the OpenVMS Calling Standard. Because the exception vectors are allocated in static storage, they are not generally used by modular routines.

If neither the primary nor secondary vectored handlers handle the exception condition by continuing program execution, then the CHF looks for stack frame condition handlers. It looks for the address of a condition handler in the first longword of the routine stack frame on VAX systems, or in the procedure descriptor (in which the handler valid bit is set) for the routine stack frame on Alpha systems where the exception condition occurred. At this point, several actions are possible, depending on the results of this search:

• If this routine has not set up a condition handler, the CHF continues the stack scan by moving to the previous stack frame (that is, the stack frame of the calling routine).
• If a condition handler is present, the CHF then calls this handler, which may resignal, continue, or unwind. See Section 15.10.

The OpenVMS Condition Handling facility searches for and calls condition handlers from each frame on the stack until the frame pointer is zero (indicating the end of the call sequence). At that point, the CHF calls the vectored catchall handler, which displays an error message and causes the program to exit. Note that, normally, the frame containing the stack catchall handler is at the end of the calling sequence or at the bottom of the stack. Section 15.9 explains the possible actions of default and user condition handlers in more detail.

Figure 15-5 illustrates a stack scan for condition handlers in which the main program calls procedure A, which then calls procedure B. A stack scan is initiated when a hardware exception condition occurs or when a call is made to LIB$SIGNAL or LIB$STOP.

Figure 15-5 Sample Stack Scan for Condition Handlers

When software detects an exception condition, the software normally calls one of the run-time library signal-generating routines, LIB$SIGNAL or LIB$STOP, to initiate the signaling mechanism. This call indicates to the calling program that the exception condition has occurred. Your program can also call one of these routines explicitly to indicate an exception condition.

LIB$SIGNAL Routine

You can signal a condition code by invoking the run-time library procedure LIB$SIGNAL and passing the condition code as the first argument. (The OpenVMS RTL Library (LIB$) Manual contains the complete specifications for LIB$SIGNAL.) The following statement signals the condition code contained in the variable STATUS:

CALL LIB$SIGNAL (%VAL(STATUS))

When an error occurs in a subprogram, the subprogram can signal the appropriate condition code rather than return the condition code to the invoking program unit. In addition, some statements also signal condition codes; for example, an assignment statement that attempts to divide by zero signals the condition code SS$_INTDIV.

When your program wants to issue a message and allow execution to continue after handling the condition, it calls the standard routine, LIB$SIGNAL. The calling sequence for LIB$SIGNAL is the following:

LIB$SIGNAL condition-value [,condition-argument...] [,condition-value-n [,condition-argument-n...]...]

Only the condition-value argument must be specified; other arguments are optional. A description of the arguments is as follows:

condition-value

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	read only
mechanism:	by value

OpenVMS 32-bit condition value. The condition-value argument is an unsigned longword that contains this condition value. Section 15.5 explains the format of a condition value.

condition-argument

OpenVMS usage:	varying_arg
type:	unspecified
access:	read only
mechanism:	by value

As many arguments as are required to process the exception specified by condition-value. These arguments are also used as FAO (formatted ASCII output) arguments to format a message.

condition-value-n

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	read only
mechanism:	by value

OpenVMS 32-bit condition value. The optional condition-value-n argument is an unsigned longword that contains this condition value. The calling routine can specify additional conditions to be processed by specifying condition-value-2 through condition-value-n, with each condition value followed by any arguments required to process the condition specified. However, the total number of arguments in the call to LIB$SIGNAL must not exceed 253.

condition-argument-n

OpenVMS usage:	varying_arg
type:	unspecified
access:	read only
mechanism:	by value

As many arguments as required to create the message reporting the exception specified by condition-value-n.

LIB$STOP

When your program wants to issue a message and stop execution unconditionally, it calls LIB$STOP. The calling sequence for LIB$STOP is as follows:

LIB$STOP condition-value [,number-of-arguments] [,FAO-argument....]

Only the condition-value argument must be specified; other arguments are optional. The condition-value argument is an OpenVMS 32-bit condition value. The condition-value argument is an unsigned longword that contains this condition value.

The number-of-arguments argument, if specified, contains the number of FAO arguments that are associated with condition-value. The optional number-of-arguments argument is a signed longword integer that contains this number. If omitted or specified as zero, no FAO arguments follow.

The FAO-argument argument is an optional FAO (formatted ASCII output) argument that is associated with the specified condition value.

The condition-value argument indicates the condition that is being signaled. However, LIB$STOP always sets the severity of condition-value to SEVERE before proceeding with the stack-scanning operation.

The FAO arguments describes the details of the exception condition. These are the same arguments that are passed to the OpenVMS Condition Handling facility as part of the signal argument vector. The system default condition handlers pass them to SYS$PUTMSG, which uses them to issue a system message.

Unlike most routines, LIB$SIGNAL and LIB$STOP preserve R0 and R1 as well as the other registers. Therefore, a call to LIB$SIGNAL allows the debugger to display the entire state of the process at the time of the exception condition. This is useful for debugging checks and gathering statistics.

The behavior of LIB$SIGNAL is the same as that of the exception dispatcher that performs the stack scan after hardware detects an exception condition. That is, the system scans the stack in the same way, and the same arguments are passed to each condition handler. This allows a user to write a single condition handler to detect both hardware and software conditions.

For more information about the RTL routines LIB$SIGNAL and LIB$STOP, see OpenVMS RTL Library (LIB$) Manual.

15.8.2 Signal Argument Vector

Signaling a condition value causes both VAX and Alpha systems to pass control to a special subprogram called a condition handler. The operating system invokes a default condition handler unless you have established your own. The default condition handler displays the associated error message and continues or, if the error is a severe error, terminates program execution.

The signal argument vector contains information describing the nature of the hardware or software condition. Figure 15-6 illustrates the open-ended structure of the signal argument vector, which can be from 3 to 257 longwords in length.

The format of the signal argument array and the data it returns is the same on VAX systems and Alpha systems, with the exception of the processor status (PS) returned on Alpha systems and the processor status longword (PSL) returned on VAX systems. On Alpha systems, it is the low-order 32 bits of the PS.

On Alpha systems, CHF$IS_SIG_ARGS and CHF$IS_SIG_NAME are aliases for CHF$L_SIG_ARGS and CHF$L_SIG_NAME, as shown in Figure 15-6, and the PSL field for VAX systems is the processor status (PS) field for Alpha systems.

Figure 15-6 Format of the Signal Argument Vector

Fields of the Signal Argument Vector

SIGARGS(1)

An unsigned integer (n) designating the number of longwords that follow in the vector, not counting the first, including PC and PSL. (On Alpha systems, the value used for the PSL is the low-order half of the Alpha processor status [PS] register.) For example, the first entry of a 4-longword vector would contain a 3.

SIGARGS(2)

On both VAX systems and Alpha systems, this argument is a 32-bit value that uniquely identifies a hardware or software exception condition. The format of the condition code, which is the same for both VAX systems and Alpha systems, is shown and described in Figure 15-3. However, Alpha systems do not support every condition returned on VAX systems, and Alpha systems define several new conditions that cannot be returned on VAX systems. Table 15-2 lists VAX system condition codes that cannot be returned on Alpha systems.

If more than one message is associated with the error, this is the condition value of the first message. Handlers should always check whether the condition is the one that they expect by examining the STS$V_COND_ID field of the condition value (bits <27:3>). Bits <2:0> are the severity field. Bits <31:28> are control bits; they may have been changed by an intervening handler and so should not be included in the comparison. You can use the RTL routine LIB$MATCH_COND to match the correct fields. If the condition is not expected, the handler should resignal by returning false (bit <0> = 0). The possible exception conditions and their symbolic definitions are listed in Table 15-1.

SIGARGS(3 to n --1)

Optional arguments that provide additional information about the condition. These arguments consist of one or more message sequences. The format of the message description varies depending on the type of message being signaled. For more information, see the SYS$PUTMSG description in the OpenVMS System Services Reference Manual. The format of a message sequence is described in Section 15.11.

SIGARGS(n)

The program counter (PC) of the next instruction to be executed if any handler (including the system-supplied handlers) returns with the status SS$_CONTINUE. For hardware faults, the PC is that of the instruction that caused the fault. For hardware traps, the PC is that of the instruction following the one that caused the trap. The error generated by LIB$SIGNAL is a trap. For conditions signaled by calling LIB$SIGNAL or LIB$STOP, the PC is the location following the CALLS or CALLG instruction. See the VAX Architecture Reference Manual or Alpha Architecture Reference Manual for a detailed description of faults and traps.

SIGARGS(n+1)

On VAX systems the processor status longword (PSL), or on Alpha systems the processor status (PS) register, of the program at the time that the condition was signaled.

For information about the PSL on VAX systems, and the PS on Alpha systems, see the VAX Architecture Reference Manual and the Alpha Architecture Reference Manual.

The formats for some conditions signaled by the operating system and the run-time library are shown in Figure 15-7 and Figure 15-8. These formats are the same on VAX systems and Alpha systems, except for the PSL, or on Alpha systems, the PS register.

Figure 15-7 Signal Argument Vector for the Reserved Operand Error Conditions

Figure 15-8 Signal Argument Vector for RTL Mathematics Routine Errors

The caller's PC is the PC following the calling program's JSB or CALL to the mathematics routine that detected the error. The PC is that following the call to LIB$SIGNAL.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

5841PRO_041.HTML