HP OpenVMS systems documentation

OpenVMS software components return condition values when they complete execution. When a severity code in the range of 0 through 4 is generated, the status code describes the nature of the problem. This value can be tested to change the flow of control of a procedure, can be used to generate a message, or both.

User procedures can also generate condition values to be examined by other procedures and by the command interpreter. User-generated condition values should have bits <27> and <15> set so they do not conflict with values generated by Hewlett-Packard.

8.2 Condition Handlers

To handle hardware- or software-detected exceptions, the OpenVMS Condition Handling Facility (CHF) allows you to specify a condition handler procedure to be called when an exception condition occurs.

An active procedure can establish a condition handler to be associated with it. When an event occurs that is to be treated using the Condition Handling Facility, the procedure detecting the event signals the event by calling the facility and passing a condition value that describes the condition. This condition value has the format and interpretation described in Section 8.1. All hardware exceptions are signaled.

When a condition is signaled, the Condition Handling Facility looks for a condition handler associated with the current procedure's stack frame. If a handler is found, it is entered. If a handler is not associated with the current procedure, the immediately preceding stack frame is examined. Again, if a handler is found, it is entered. If a handler is not found, the search of previous stack frames continues until the default condition handler established by the system is reached or until the stack runs out.

The default condition handler prints messages, indicated by the signal argument list, by calling the put message (SYS$PUTMSG) system service, followed by an optional symbolic stack traceback. Success conditions with STS$K_SUCCESS result in messages to SYS$OUTPUT only. All other conditions, including informational messages (STS$K_INFO), produce messages on SYS$OUTPUT and SYS$ERROR.

For example, if a procedure needs to keep track of the occurrence of the floating-point underflow exception, it can establish a condition handler to examine the condition value passed when the handler is invoked. Then, when the floating-point underflow exception occurs, the condition handler is entered and logs the condition. The handler returns to the instruction immediately following the instruction that was executing when the condition was reported by the hardware. On a VAX or Intel Itanium processor, this instruction is the one immediately following the instruction that caused the underflow; on an Alpha processor, this instruction might occur later.

If floating-point operations occur in many procedures of a program, the condition handler can be associated with the program's main procedure. When the condition is signaled, successive stack frames are searched until the stack frame for the main procedure is found, at which time the handler is entered. If a user program has not associated a condition handler with any of the procedures that are active at the time of the signal, successive stack frames are searched until the frame for the system program invoking the user program is reached. A default condition handler that prints an error message is then entered.

8.3 Condition Handler Options

Each procedure activation potentially has a single condition handler associated with it. This condition handler is entered whenever any condition is signaled within that procedure. (It can also be entered as a result of signals within active procedures called by the procedure.) Each signal includes a condition value (see Section 8.1) that describes the condition that caused the signal. When the condition handler is entered, examine the condition value to determine the cause of the signal. After the handler either processes the condition or ignores it, it can take one of the following actions:

• Return to the instruction immediately following the signal. Note that such a return is not always possible.
• Resignal the same or a modified condition value. A new search for a condition handler begins with the immediately preceding stack frame.
• Signal a different condition.
• Unwind the stack.
• On OpenVMS Alpha or I64, perform a nonlocal GOTO operation (see Section 8.4) that transfers control from one procedure invocation and continues execution in a prior one.

The OpenVMS Condition Handling Facility (CHF) provides functions to perform the following operations:

• Establish a condition handler.
  A condition handler is associated with a procedure in various ways, depending on the language in which the procedure is written. Some languages provide specific syntax for defining a handler and its possible actions; others allow dynamic specification of a routine to act as a handler.
• On VAX systems, revert to the caller's handling.
  If a condition handler has been established on a VAX system, you can remove it.
• Enable or disable certain arithmetic exceptions.
  The software can enable or disable the following hardware exceptions: floating-point underflow, integer overflow, and decimal overflow. No signal occurs when the exception is disabled.
  On VAX systems, exceptions are enabled or disabled dynamically at every procedure entry or by directly manipulating the processor status longword.
  On Alpha or Itanium systems, exceptions are enabled or disabled statically during compilation; this is reflected in the code that is compiled.
• Signal a condition.
  Signaling a condition initiates the search for an established condition handler.
• Unwind the stack.
  Upon exiting from a condition handler, it is possible to remove one or more frames that occur before the signal from the stack. During the unwinding operation, the stack is scanned; if a condition handler is associated with a frame, the handler is entered before the frame is removed. Unwinding the stack allows a procedure to perform application-specific cleanup operations before exiting.
• On Alpha or I64 systems, perform a nonlocal GOTO unwind.
  A GOTO unwind operation is a transfer of control that leaves one procedure invocation and continues execution in a prior (currently active) procedure. This unified GOTO operation gives unterminated procedure invocations the opportunity to clean up in an orderly way.

On VAX systems, the association of a handler with a procedure invocation is dynamic and can be changed or reverted to the caller's handler during execution, but this is not supported for languages that implicitly provide their own handlers.

Each procedure activation can have an associated condition handler, using the first longword in its stack frame. Initially, the first longword (longword 0) contains the value 0, indicating no handler. You establish a handler by moving the address of the handler's procedure entry point mask to the establisher's stack frame.

On VAX systems, the following code establishes a condition handler:

MOVAB handler_entry_point,0(FP)

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

Each procedure, other than an Alpha null frame procedure, can have a condition handler potentially associated with it, which is identified by the HANDLER_VALID, STACK_HANDLER, or REG_HANDLER fields of the associated procedure descriptor on an Alpha system, or the handler field in the associated unwind information block on an I64 system. You establish a handler by including the procedure value of the handler procedure in that field. (See Sections 3.4.1, 3.4.4, and A.4.1.)

In addition, the OpenVMS operating system on all processors provides three statically allocated exception vectors for each access mode of a process. These vectors are available to declare condition handlers that take precedence over any handlers declared at the procedure level. For example, the vectors are used to allow a debugger to monitor all exceptions and for the system to establish a last-chance handler. Because these handlers do not obey the procedure nesting rules, do not use them with modular code. Instead, use frame-based handlers.

8.4.2 Reverting to the Caller's Handling

On VAX systems, reverting to the caller's handling deletes the condition handler associated with the current procedure activation. You do this by clearing the handler address in the stack frame.

On VAX systems, the code to revert to the caller's handling is as follows:

CLRL 0(FP)

On Alpha and I64 systems, there is no means to revert to a caller's handler (unless a language provides emulation of dynamically specified handlers).

8.4.3 Signaling a Condition

The signal operation is the method for indicating the occurrence of an exception condition. To initiate a signal and allow execution to continue after handling the condition, a program calls the LIB$SIGNAL procedure. To initiate a signal but not allow execution to continue at the point of initiation, a program calls the LIB$STOP procedure. The format of the LIB$SIGNAL and LIB$STOP calls are defined as follows:

LIB$SIGNAL(condition-value, argn...)

LIB$STOP(condition-value, argn...)

Argument	OpenVMS Usage	Type	Access	Mechanism
condition-value	condition	longword	read	by value
argn	integer	quadword	read	by value

Arguments:

	condition-value An OpenVMS condition value.
	argn Zero or more integer arguments that become the additional arguments of a signal argument vector (see Section 8.5.1.1)

Function Value Returned:

None.

In both cases, the condition-value argument indicates the condition that is signaled. However, LIB$STOP sets the severity of the condition-value argument to be a severe error. The remaining arguments describe the details of the exception. These are the same arguments used to issue a system message.

Unlike most calls, LIB$SIGNAL and LIB$STOP preserve all registers. Therefore, a debugger can insert a call to LIB$SIGNAL to display the entire state of the process at the time of the exception. Use of LIB$ routines also allows signals to be coded in an assembler language without changing the register usage. This feature of preserving all registers is useful for debugging checks and for gathering statistics. Hardware and system service exceptions behave like calls to LIB$SIGNAL.

8.4.4 Signaling a Condition Using GENTRAP (Alpha and I64 Systems Only)

Alpha and I64 systems each have a special instruction that provides an efficient means to raise a hardware-like exception. These are intended for use especially in low levels of the operating system or in the bootpath sequence when only a limited execution environment is available. Compiled code can also use these instructions to raise common generic exceptions more simply and compactly than by executing a complete LIB$SIGNAL procedure call.

In each case, the special instruction takes an exception code (excp_code) parameter that is passed in a general register; that parameter specifies the particular exception to be raised.

On Alpha systems, the GENTRAP PALcall instruction is used. The excp_code parameter is passed in R16. Interpretation of that parameter is described below.

On I64 systems, the BREAK instruction with an immediate operand of 100001 (hex) is used to implement a GENTRAP operation. The excp_code parameter is passed in R17. Interpretation of that parameter is described below.

If the excp_code value is one of the small integers shown in the first column of Table 8-4, than that value is mapped to a corresponding OpenVMS condition code as shown in the third (Symbol) column of the Table. If the value is negative but not one of the values shown in Table 8-4, then SS$_GENTRAP is raised with the unmapped value included in the signal vector as the first and only qualifier value. Otherwise, a positive value is used directly to raise an exception using that value as the condition value. Note that there is no means to associate any parameters with an exception raised by GENTRAP.

For more information on the Alpha GENTRAP PALcall, see the Alpha Architecture Reference Manual. For more information on the BREAK instruction on the Intel Itanium processors, see the Intel IA-64 Architecture Software Developer's Manual. For more information on Itanium Conventions Defined Codes see Section 8.4.5.

Table 8-4 Exception Codes and Symbols for the GENTRAP Parameter

OpenVMS GENTRAP excp_code Parameter	Intel Itanium Conventions Defined Codes (High Bits 000)	Symbol	Meaning
Alpha and I64 Systems
--1	2	SS$_INTOVF	Integer overflow
--2	1	SS$_INTDIV	Integer divide by zero
--3		SS$_FLTOVF	Floating overflow
--4		SS$_FLTDIV	Floating divide by zero
--5		SS$_FLTUND	Floating underflow
--6		SS$_FLTINV	Floating invalid operand
--7		SS$_FLTINE	Floating inexact result
--8	6	SS$_DECOVF	Decimal overflow
--9	7	SS$_DECDIV	Decimal divide by zero
--10	8, 9, 10	SS$_DECINV	Decimal invalid operand
--11	0	SS$_ROPRAND	Reserved operand
--12		SS$_ASSERTERR	Assertion error
--13	4	SS$_NULPTRERR	Null pointer error
--14	11	SS$_STKOVF	Stack overflow
--15		SS$_STRLENERR	String length error
--16		SS$_SUBSTRERR	Substring error
--17		SS$_RANGEERR	Range error
--18	3	SS$_SUBRNG	Subscript range error
--19		SS$_SUBRNG1	Subscript 1 range error
--20		SS$_SUBRNG2	Subscript 2 range error
--21		SS$_SUBRNG3	Subscript 3 range error
--22		SS$_SUBRNG4	Subscript 4 range error
--23		SS$_SUBRNG5	Subscript 5 range error
--24		SS$_SUBRNG6	Subscript 6 range error
--25		SS$_SUBRNG7	Subscript 7 range error
I64 Systems Only
--26		SS$_CALLUNDEFSYM	Call using undefined function symbol
--27		SS$_ARGTYP1	Argument 1 type error
--28		SS$_ARGTYP2	Argument 2 type error
--29		SS$_ARGTYP3	Argument 3 type error
--30		SS$_ARGTYP4	Argument 4 type error
--31		SS$_ARGTYP5	Argument 5 type error
--32		SS$_ARGTYP6	Argument 6 type error
--33		SS$_ARGTYP7	Argument 7 type error
--34		SS$_ARGTYP8	Argument 8 type error
	5	SS$_UNALIGNED	Unaligned parameter

8.4.5 Signaling a Condition Using BREAK (I64 Only)

In accordance with the Itanium software conventions, OpenVMS I64 partitions the 21-bit immediate operand values that can occur in a BREAK instruction into the following groups:

• Immediate operands whose three highest-order bits are 000, which is the range 000000 through 03FFFF (hex). These values are reserved for architected software interrupt codes. The defined software interrupt codes are listed in the second column of Table 8-4. Immediate operands in this range, but not listed in the table, are reserved for future use.
  A code shown in the second column of Table 8-4 is mapped to a corresponding OpenVMS condition code as shown in the third (Symbol) column, which is then raised. (This handling is similar to the handling of a negative excp_code parameter for GENTRAP as described in Section 8.4.4.)
• Immediate operands whose three highest-order bits are 001, which is the range 040000 (hex) through 07FFFF (hex).
  Operands in this range are reserved for use by applications. If one of these occurs, then SS$_BREAK_APPL is raised with the operand value included as the first (and only) additional argument in the signal argument vector (see Section 8.5.1.1).
• Immediate operands whose two highest-order bits are 01, which is the range 080000 (hex) through 0FFFFF (hex).
  Operands in this range are reserved for use by debuggers. OpenVMS debugger software uses only immediate operands in the range 080000 (hex) through 0BFFFF (hex). Other debugger software is encouraged, but not required, to use immediate operands in the range 0C0000 (hex) through 0FFFFF (hex).
• Immediate operands whose highest-order bit is 1, which is the range 100000 (hex) through 1FFFFF (hex).
  Operands in this range are reserved for use within OpenVMS. The value 100001, however, is used to implement an Alpha-compatible GENTRAP operation as described in Section 8.4.4.
  For more information on the Itanium software conventions, see the Itanium® Software Conventions and Runtime Architecture Guide.