Document revision date: 30 March 2001

This chapter describes the OpenVMS Condition Handling facility and contains the following sections:

Section 9.1 gives an overview of run-time errors.

Section 9.2 gives an overview of the OpenVMS Condition Handling facility, presenting condition-handling terminology and functionality.

Section 9.3 describes VAX system and Alpha system exceptions, arithmetic exceptions, and unaligned access traps on Alpha systems.

Section 9.4 describes how run-time library routines handle exceptions.

Section 9.5 describes the condition value field and the testing and modifying of values.

Section 9.6 describes the exception dispatcher.

Section 9.7 describes the argument list that is passed to a condition handler.

Section 9.8 describes signaling.

Section 9.9 describes types of condition handlers.

Section 9.10 describes types of actions performed by condition handlers.

Section 9.11 describes messages and how to use them.

Section 9.12 describes how to write a condition handler.

Section 9.13 describes how to debug a condition handler.

Section 9.14 describes several run-time library routines that can be established as condition handlers.

Section 9.15 describes how to establish, write, and debug an exit handler.

9.1 Overview of Run-Time Errors

Run-time errors are hardware- or software-detected events, usually errors, that alter normal program execution. Examples of run-time errors are as follows:

• System errors---for example, specifying an invalid argument to a system-defined procedure
• Language-specific errors---for example, in Fortran, a data type conversion error during an I/O operation
• Application-specific errors---for example, attempting to use invalid data

When an error occurs, the operating system either returns a condition code or value identifying the error to your program or signals the condition code. If the operating system signals the condition code, an error message is displayed and program execution continues or terminates, depending on the severity of the error. See Section 9.5 for details about condition values.

When unexpected errors occur, your program should display a message identifying the error and then either continue or stop, depending on the severity of the error. If you know that certain run-time errors might occur, you should provide special actions in your program to handle those errors.

Both an error message and its associated condition code identify an error by the name of the facility that generated it and an abbreviation of the message text. Therefore, if your program displays an error message, you can identify the condition code that was signaled. For example, if your program displays the following error message, you know that the condition code SS$_NOPRIV was signaled:

%SYSTEM-F-NOPRIV, no privilege for attempted operation

9.2 Overview of the OpenVMS Condition Handling Facility

The operating system provides a set of signaling and condition-handling routines and related system services to handle exception conditions. This set of services is called the OpenVMS Condition Handling facility (CHF). The OpenVMS Condition Handling Facility is a part of the common run-time environment of OpenVMS, which includes run-time library (RTL) routines and other components of the operating system.

The OpenVMS Condition Handling facility provides a single, unified method to enable condition handlers, signal conditions, print error messages, change the error behavior from the system default, and enable or disable detection of certain hardware errors. The RTL and all layered products of the operating system use the CHF for condition handling.

See the OpenVMS Calling Standard for a detailed description of OpenVMS condition handling.

9.2.1 Condition-Handling Terminology

This section defines the terms used to describe condition handling.

exception

An event detected by the hardware or software that changes the normal flow of instruction execution. An exception is a synchronous event caused by the execution of an instruction and often means something generated by hardware. When an exception occurs, the processor transfers control by forcing a change in the flow of control from that explicitly indicated in the currently executing process.

Some exceptions are relevant primarily to the current process and normally invoke software in the context of the current process. An integer overflow exception detected by the hardware is an example of an event that is reported to the process. Other exceptions, such as page faults, are handled by the operating system and are transparent to the user.

An exception may also be signaled by a routine (software signaling) by calling the RTL routines LIB$SIGNAL or LIB$STOP.

condition

An informational state that exists when an exception occurs. Condition is a more general term than exception; a condition implies either a hardware exception or a software-raised condition. Often, the term condition is preferred because the term exception implies an error. Section 9.3.1 further defines the differences between exceptions and conditions.

condition handling

When a condition is detected during the execution of a routine, a signal can be raised by the routine. The routine is then permitted to respond to the condition. The routine's response is called handling the condition.

On VAX systems, an address of 0 in the first longword of a procedure call frame or in an exception vector indicates that a condition handler does not exist for that call frame or vector.

On Alpha systems, the handler valid flag bit in the procedure descriptor is cleared to indicate that a condition handler does not exist.

The condition handlers are themselves routines; they have their own call frames. Because they are routines, condition handlers can have condition handlers of their own. This allows condition handlers to field exceptions that might occur within themselves in a modular fashion.

On VAX systems, a routine can enable a condition handler by placing the address of the condition handler in the first longword of its stack frame.

On Alpha systems, the association of a handler with a procedure is static and must be specified at the time a procedure is compiled (or assembled). Some languages that lack their own exception-handling syntax, however, may support emulation of dynamic specified handlers by means of built-in routines.

If you determine that a program needs to be informed of particular exceptions so it can take corrective action, you can write and specify a condition handler. This condition handler, which receives control when any exception occurs, can test for specific exceptions.

If an exception occurs and you have not specified a condition handler, the default condition handler established by the operating system is given control. If the exception is a fatal error, the default condition handler issues a descriptive message and causes the image that incurred the exception to exit.

To declare or enable a condition handler, use the following system services:

• Set Exception Vector (SYS$SETEXV)
• Unwind from Condition Handler Frame (SYS$UNWIND)
• Declare Change Mode or Compatibility Mode Handler (SYS$DCLCMH)

Parallel mechanisms exist for uniform dispatching of hardware and software exception conditions. Exceptions that are detected and signaled by hardware transfer control to an exception service routine in the executive. Software-detected exception conditions are generated by calling the run-time library routines LIB$SIGNAL or LIB$STOP. Hardware- and software-detected exceptions eventually execute the same exception dispatching code. Therefore, a condition handler may handle an exception condition generated by hardware or by software identically.

The Set Exception Vector (SYS$SETEXV) system service allows you to specify addresses for a primary exception handler, a secondary exception handler, and a last-chance exception handler. You can specify handlers for each access mode. The primary exception vector is reserved for the debugger. In general, you should avoid using these vectored handlers unless absolutely necessary. If you use a vectored handler, it must be prepared for all exceptions occurring in that access mode.

9.2.2 Functions of the Condition Handling Facility

The OpenVMS Condition Handling facility and the related run-time library routines and system services perform the following functions:

• Establish and call condition-handler routines
  You can establish condition handlers to receive control in the event of an exception in one of the following ways:
  • On VAX systems, by specifying the address of a condition handler in the first longword of a procedure call frame.
    On Alpha systems, the method for establishing a dynamic (that is, nonvectored) condition handler is specified by the language.
  • By establishing exception handlers with the Set Exception Vector (SYS$SETEXV) system service.
  
  The first of these methods is the preferred way to specify a condition handler for a particular image. The use of dynamic handlers is also the most efficient way in terms of declaration. You should use vectored handlers for special purposes, such as writing debuggers.
  The VAX MACRO programmer can use the following single-move address instruction to place the address of the condition handler in the longword pointed to by the current frame pointer (FP):

  MOVAB HANDLER,(FP)

  
  You can associate a condition handler for the currently executing routine by specifying an address pointing to the handler, either in the routine's stack frame on VAX systems or in one of the exception vectors. (The MACRO-32 compiler for OpenVMS Alpha systems generates the appropriate Alpha code from this VAX instruction to establish a dynamic condition handler.)
  On VAX systems, the high-level language programmer can call the common run-time library routine LIB$ESTABLISH (see the OpenVMS RTL Library (LIB$) Manual), using the name of the handler as an argument. LIB$ESTABLISH returns as a function value either the address of the former handler established for the routine or 0 if no handler existed.
  On VAX systems, the new condition handler remains in effect for your routine until you call LIB$REVERT or control returns to the caller of the caller of LIB$ESTABLISH. Once this happens, you must call LIB$ESTABLISH again if the same (or a new) condition handler is to be associated with the caller of LIB$ESTABLISH.
  On VAX systems, some languages provide access to condition handling as part of the language. You can use the ON ERROR GOTO statement in BASIC and the ON statement in PL/I to define condition handlers. If you are using a language that does provide access to condition handling, use its language mechanism rather than LIB$ESTABLISH. Each procedure can declare a condition handler.
  When the routine signals an exception, the OpenVMS Condition Handling facility calls the condition handler associated with the routine. See Section 9.8 for more information about exception vectors. Figure 9-5 shows a sample stack scan for a condition handler.
  The following Compaq Fortran program segment establishes the condition handler ERRLOG. Because the condition handler is used as an actual argument, it must be declared in an EXTERNAL statement.

  INTEGER*4 OLD_HANDLER EXTERNAL ERRLOG . . . OLD_HANDLER = LIB$ESTABLISH (ERRLOG)

  
  LIB$ESTABLISH returns the address of the previous handler as its function value. If only part of a program unit requires a special condition handler, you can reestablish the original handler by invoking LIB$ESTABLISH and specifying the saved handler address as follows:

  CALL LIB$ESTABLISH (OLD_HANDLER)

  
  The run-time library provides several condition handlers and routines that a condition handler can call. These routines take care of several common exception conditions. Section 9.14 describes these routines.
  On Alpha systems, LIB$ESTABLISH and LIB$REVERT are not supported, though a high-level language may support them for compatibility. (Table 9-4 lists other run-time library routines supported and not supported on Alpha systems.)

• On VAX systems, remove an established condition-handler routine
  On VAX systems using LIB$REVERT, you can remove a condition handler from a routine's stack frame by setting the frame's handler address to 0. If your high-level language provides condition-handling statements, you should use them rather than LIB$REVERT.
• On VAX systems, enable or disable the detection of arithmetic hardware exceptions
  On VAX systems, using run-time library routines, you can enable or disable the signaling of floating point underflow, integer overflow, and decimal overflow, which are detected by the VAX hardware.
• Signal a condition
  When the hardware detects an exception, such as an integer overflow, a signal is raised at that instruction. A routine may also raise a signal by calling LIB$SIGNAL or LIB$STOP. Signals raised by LIB$SIGNAL allow the condition handler either to terminate or to resume the normal flow of the routine. Signals raised by LIB$STOP require termination of the operation that raises the condition. The condition handler will not be allowed to continue from the point of call to LIB$STOP.
• Display an informational message
  The system establishes default condition handlers before it calls the main program. Because these default condition handlers provide access to the system's standard error messages, the standard method for displaying a message is by signaling the severity of the condition: informational, warning, or error. See Section 9.5 for the definition of the severity field of a condition vector. The system default condition handlers resume execution of the instruction after displaying the messages associated with the signal. If the condition value indicates a severe condition, then the image exits after the message is displayed.
• Display a stack traceback on errors
  The default operations of the LINK and RUN commands provide a system-supplied handler (the traceback handler) to print a symbolic stack traceback. The traceback shows the state of the routine stack at the point where the condition occurred. The traceback information is displayed along with the messages associated with the signaled condition.
• Compile customer-defined messages
  The Message utility allows you to define your own exception conditions and the associated messages. Message source files contain the condition values and their associated messages. See Section 9.11.3 for a complete description of how to define your own messages.
• Unwind the stack
  A condition handler can cause a signal to be dismissed and the stack to be unwound to the establisher or caller of the establisher of the condition handler when it returns control to the OpenVMS Condition Handling facility (CHF). During the unwinding operation, the CHF scans the stack. If a condition handler is associated with a frame, the system calls that handler before removing the frame. Calling the condition handlers during the unwind allows a routine to perform cleanup operations specific to a particular application, such as recovering from noncontinuable errors or deallocating resources that were allocated by the routine (such as virtual memory, event flags, and so forth). See Section 9.12.3 for a description of the SYS$UNWIND system service.
• Log error messages to a file
  The Put Message (SYS$PUTMSG) system service permits any user-written handler to include a message in a listing file. Such message logging can be separate from the default messages the user receives. See Section 9.11 for a detailed description of the SYS$PUTMSG system service.

Exceptions can be generated by any of the following:

• Hardware
• Software
• System service failures

Hardware-generated exceptions always result in conditions that require special action if program execution is to continue.

Software-generated exceptions may result in error or warning conditions. These conditions and their message descriptions are documented in the online Help Message utility and in the OpenVMS system messages documentation. To access online message descriptions, use the HELP/MESSAGE command.

More information on using the Help Message utility is available in OpenVMS System Messages: Companion Guide for Help Message Users. That document describes only those messages that occur when the system is not fully operational and you cannot access Help Message.

Some examples of exception conditions are as follows:

• Arithmetic exception condition in a user-written program detected and signaled by hardware (for example, floating-point overflow)
• Error in a user argument to a run-time library routine detected by software and signaled by calling LIB$STOP (for example, a negative square root)
• Error in a run-time library language-support routine, such as an I/O error or an error in a data-type conversion
• RMS success condition stating that the record is already locked
• RMS success condition stating that the created file superseded an existing version

There are two standard methods for a Compaq- or user-written routine to indicate that an exception condition has occurred:

• Return a completion code to the calling program using the function value mechanism
  Most general-purpose run-time library routines indicate exception conditions by returning a condition value in R0. The calling program then tests bit 0 of R0 for success or failure. This method allows better programming structure, because the flow of control can be changed explicitly after the return from each call. If the actual function value returned is greater than 32 bits, then use both R0 and R1.
  On Alpha systems, if the actual function returned is a floating-point value, the floating-point value is returned in F0, or F0 and F1.
• Signal the exception condition
  A condition can be signaled by calling the RTL routine LIB$SIGNAL or LIB$STOP. Any condition handlers that were enabled are then called by the CHF. See Figure 9-5 for the order in which CHF invokes condition handlers.
  Exception conditions raised by hardware or software are signaled to the routine identically.
  For more details, see Section 9.8 and Section 9.8.1.

Table 9-1 summarizes common conditions caused by exceptions. The condition names are listed in the first column. The second column explains each condition more fully by giving information about the type, meaning, and arguments relating to the condition. The condition type is either trap or fault. For more information about traps and faults, refer to the VAX Architecture Reference Manual and Alpha Architecture Reference Manual. The meaning of the exception condition is a short description of each condition. The arguments for the condition handler are listed where applicable; they give specific information about the condition.

Table 9-1 Summary of Exception Conditions

Condition Name	Explanation
SS$_ACCVIO	Type:	Fault.
	Description	Acess Violation.
	Arguments:	Reason for access violation. This is a mask with the following format: Bit <0> = type of access violation 0 = page table entry protection code did not permit intended access 1 = P0LR, P1LR, or SLR length violation 1 Bit <1> = page table entry reference 0 = specified virtual address not accessible 1 = associated page table entry not accessible Bit <2> = intended access 0 = read 1 = modify Bit <16> = indicates fault on the pre-fetch of the instruction 2 0 = successful execution 1 = fault on fetch Bit <17> =indicates whether instruction is marked as no execute 2 0 = not market 1 = indicates instruction is marked as a fault on execute in its page table entry Virtual address to which access was attempted or, on some processors, virtual address within the page to which access was attempted.
SS$_ARTRES 2	Type: Description: Arguments:	Trap. Reserved arithmetic trap. None.
SS$_ASTFLT	Type:	Trap.
	Description:	Stack invalid during attempt to deliver an AST.
	Arguments:	Stack pointer value when fault occurred. AST parameter of failed AST. Program counter (PC) at AST delivery interrupt. Processor status longword (PSL) for VAX or processor status (PS) for Alpha at AST delivery interrupt. 3 For PS, it is the low-order 32 bits. Program counter (PC) to which AST would have been delivered. 3 Processor status longword (PSL) for VAX or processor status (PS) for Alpha to which AST would have been delivered. 3 For PS, it is the low-order 32 bits.
SS$_BREAK	Type: Description: Arguments:	Fault. Breakpoint instruction encountered. None.
SS$_CMODSUPR	Type: Description: Arguments:	Trap. Change mode to supervisor instruction encountered. 4 Change mode code. The possible values are --32,768 through 32,767.
SS$_CMODUSER	Type: Description: Arguments:	Trap. Change mode to user instruction encountered. 4 Change mode code. The possible values are --32,768 through 32,767.
SS$_COMPAT 1	Type:	Fault.
	Description:	Compatibility-mode exception. This exception condition can occur only when executing in compatibility mode. 5
	Arguments:	Type of compatibility exception. The possible values are as follows: 0 = Reserved instruction execution 1 = BPT instruction executed 2 = IOT instruction executed 3 = EMT instruction executed 4 = TRAP instruction executed 5 = Illegal instruction executed 6 = Odd address fault 7 = TBIT trap.
SS$_DECOVF 1 2	Type: Description: Arguments:	Trap. Decimal overflow. None.
SS$_FLTDIV 1 2	Type: Description: Arguments:	Trap. Floating/decimal divide-by-zero. None.
SS$_FLTDIV_F 1	Type: Description: Arguments:	Fault. Floating divide-by-zero. None.
SS$_FLTOVF 1 2	Type: Description: Arguments:	Trap. Floating-point overflow. None.
SS$_FLTOVF_F 1	Type: Description: Arguments:	Fault. Floating-point overflow fault. None.
SS$_FLTUND 1 2	Type: Description: Arguments:	Trap. Floating-point underflow. None.
SS$_FLTUND_F 1	Type: Description: Arguments:	Fault. Floating-point underflow fault. None.
SS$_INTDIV 1 2	Type: Description: Arguments:	Trap. Integer divide-by-zero. None.
SS$_INTOVF 1 2	Type: Description: Arguments:	Trap. Integer overflow. None.
SS$_OPCCUS 1	Type: Description: Arguments:	Fault. Opcode reserved for customer fault. None.
SS$_OPCDEC	Type: Description: Arguments:	Fault. Opcode reserved for Compaq fault. None.
SS$_PAGRDERR	Type:	Fault.
	Description:	Read error occurred during an attempt to read a faulted page from disk.
	Arguments:	Translation not valid reason. This is a mask with the following format: Bit <0> = 0 Bit <1> = page table entry reference 0 = specified virtual address not valid 1 = associated page table entry not valid Bit <2> = intended access 0 = read 1 = modify Virtual address of referenced page.
SS$_RADRMOD 1	Type: Description: Arguments:	Fault. Attempt to use a reserved addressing mode. None.
SS$_ROPRAND	Type: Description: Arguments:	Fault. Attempt to use a reserved operand. None.
SS$_SSFAIL	Type: Description: Arguments:	Fault. System service failure (when system service failure exception mode is enabled). Status return from system service (R0). (The same value is in R0 of the mechanism array.)
SS$_SUBRNG 1 2	Type: Description: Arguments:	Trap. Subscript range trap. None.
SS$_TBIT 1	Type: Description: Arguments:	Fault. Trace bit is pending following an instruction. None.

	privacy and legal statement
5841PRO_026.HTML