[OpenVMS documentation]
[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
Updated: 11 December 1998

OpenVMS Calling Standard


Previous Contents Index

6.1.1 Interpretation of Severity Codes

A standard procedure must consider all possible severity codes (0--4) of a condition value. Table 6-3 lists the interpretation of severity codes 0 through 4.

Table 6-3 Interpretation of Severity Codes
Severity Code Meaning
0 Indicates a warning. This code is used whenever a procedure produces output, but the output produced might not be what the user expected (for example, a compiler modification of a source program).
1 Indicates that the procedure generating the condition value completed successfully, as expected.
2 Indicates that an error has occurred but the procedure did produce output. Execution can continue, but the results produced by the component generating the condition value are not all correct.
3 Indicates that the procedure generating the condition value completed successfully but has some parenthetical information to be included in a message if the condition is signaled.
4 Indicates that a severe error occurred and the component generating the condition value was unable to produce output.

When designing a procedure, you should base the choice of severity code for its condition values on the following default interpretations:

The following table summarizes the action default decisions of the severity conditions:
Severity Routine Signal Default at
Program Exit
Success Normal Continue Continue
Information Normal Continue Continue
Warning Failure Continue Continue
Error Failure Continue Stop job
Severe error Failure Exit Stop job

The default for signaled messages is to output a message with the SYS$OUTPUT system service. In addition, for severities other than success (STS$K_SUCCESS), a copy of the message is made on SYS$ERROR. At program exit, success and information completion values do not generate messages; however, warning, error, and severe error condition values do generate messages to SYS$OUTPUT and SYS$ERROR unless bit <28> (STS$V_INHIB_MSG) is set.

Unless there is a good basis for another choice, a procedure should use success or severe error as its severity code for each condition value.

6.1.2 Use of Condition Values

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, 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 Digital.

6.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 6.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 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.

6.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 6.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:

6.4 Operations Involving Condition Handlers

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

6.4.1 Establishing a Condition Handler

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 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 a 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. You establish a handler by including the procedure value of the handler procedure in that field. (See Sections 3.4.1 and 3.4.4.)

In addition, the OpenVMS operating system on VAX and Alpha 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.

6.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 systems, there is no means to revert to a caller's handler (unless a language provides emulation of dynamically specified handlers).

6.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 6.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.

6.4.4 Signaling a Condition Using GENTRAP (Alpha Only)

On Alpha systems, a GENTRAP PALcode instruction provides an efficient means for software to raise hardwarelike exceptions. This mechanism is used in low levels of the operating system or in the bootstrap sequence when only a limited execution environment is available. In a constrained environment, GENTRAP can be handled directly using the SCB vector by which the trap is reported. In a more complete environment, the GENTRAP parameter is transformed into a corresponding exception code and reported as a normal hardware exception. Because of this, low-level software can use this mechanism to report exceptions that are independent of the execution environment. Compiled code can also use the GENTRAP instruction to raise common generic exceptions more simply than by executing a complete LIB$SIGNAL procedure call.

The PALcode operation is defined as follows:

     GENTRAP ( expt_code ) 

The expt_code argument defines the code for the exception to be raised.

If the expt_code value is one of the small negative values shown in Table 6-4, then that value is mapped to a corresponding OpenVMS exception code as shown. If the value is negative but not one of the values shown in Table 6-4, then SS$_GENTRAP is raised with the unmapped value included in the exception record 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 using GENTRAP. For more information on GENTRAP, see the Alpha Architecture Reference Manual.

Table 6-4 Exception Codes and Symbols for the Alpha GENTRAP Argument
Exception Code Symbol Meaning
--1 SS$_INTOVF Integer overflow
--2 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 SS$_DECOVF Decimal overflow
--9 SS$_DECDIV Decimal divide by zero
--10 SS$_DECINV Decimal invalid operand
--11 SS$_ROPRAND Reserved operand
--12 SS$_ASSERTERR Assertion error
--13 SS$_NULPTRERR Null pointer error
--14 SS$_STKOVF Stack overflow
--15 SS$_STRLENERR String length error
--16 SS$_SUBSTRERR Substring error
--17 SS$_RANGEERR Range error
--18 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

6.4.5 Condition Handler Search

The signal procedure examines the two exception vectors first, then examines a system-defined maximum number of previous stack frames, and, if necessary, examines the last-chance exception vector. The current and previous stack frames are found by using the frame pointer and chaining back through the stack frames using the saved context in each frame. The exception vectors have three address locations per access mode.

As part of image startup, the system declares a default last-chance handler. This handler is used as a last resort when the normal handlers are not performing correctly. The debugger can replace the default system last-chance handler with its own.

On Alpha systems, note that the default catchall handler in user mode can be a list of handlers and is not in conflict with this standard.

On both VAX and Alpha systems, in some frame before the call to the main program, the system establishes a default catchall condition handler that issues system messages. In a subsequent frame before the call to the main program, the system usually establishes a traceback handler. These system-supplied condition handlers use the condition-value argument to get the message and then use the remainder of the argument list to format and output the message through the SYS$PUTMSG system service.

If the severity field of the condition-value argument (bits <2:0>) does not indicate a severe error (that is, a value of 4), these default condition handlers return with SS$_CONTINUE. If the severity is a severe error, these default handlers exit the program image with the condition value as the final image status.

The stack search ends when the old frame address is 0 or is not accessible, or when a system-defined maximum number of frames have been examined. If a condition handler is not found, or if all handlers return with a SS$_RESIGNAL or SS$_RESIGNAL64, then the vectored last-chance handler is called.

If a handler returns SS$_CONTINUE or SS$_CONTINUE64, and LIB$STOP was not called, control returns to the signaler. Otherwise, LIB$STOP issues a message indicating that an attempt was made to continue from a noncontinuable exception and exits with the condition value as the final image status.

Figure 6-2 lists all combinations of interaction between condition handler actions, default condition handlers, types of signals, and calls to signal or stop. In this figure, "Cannot Continue" indicates an error that results in the following message:


IMPROPERLY HANDLED CONDITION, ATTEMPT TO CONTINUE FROM STOP. 

Figure 6-2 Interaction Between Handlers and Default Handlers



Previous Next Contents Index

[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
[OpenVMS documentation]

Copyright © Compaq Computer Corporation 1998. All rights reserved.

Legal
5973PRO_013.HTML