HP OpenVMS Systems Documentation

HP OpenVMS Calling Standard

Descriptor class codes 160 through 191 are reserved for Hewlett-Packard for facility-specific purposes. These codes must not be passed between facilities, because different facilities might use the same code for different purposes. These codes can be used by compiler-generated code to pass parameters to the language-specific, run-time support procedures associated with that language or to the OpenVMS Debugger.

An OpenVMS condition is a hardware-generated synchronous exception or a software event that is to be processed in a manner similar to a hardware exception.

Floating-point overflow exception, memory access violation exception, and reserved operation exception are examples of hardware-generated conditions. An output conversion error, an end of file, and the filling of an output buffer are examples of software events that might be treated as conditions.

Depending on the condition and on the program, you can exercise any of four types of action when a condition occurs:

• Ignore the condition.
  For example, if an underflow occurs in a floating-point operation, continuing from the point of the exception with a zero result might be sufficient.
• Take some special action and continue from the point at which the condition occurred.
  For example, if the end of a buffer is reached while a series of data items are being written, the special action is to start a new buffer.
• End the operation and branch from the sequential flow of control.
  For example, if the end of an input file is reached, the branch exits from a loop that is processing the input data.
• Treat the condition as an unrecoverable error.
  For example, when the floating divide-by-zero exception condition occurs, the program exits after writing (optionally) an appropriate error message.

When an unusual event or error occurs in a called procedure, the procedure can return a condition value to the caller indicating what has happened (see Section 8.1). The caller tests the condition value and takes the appropriate action.

When an exception is generated by the hardware, a branch out of the program's flow of control occurs automatically. In this case, and for certain software-generated events, it is more convenient to handle the condition as soon as it is detected rather than to program explicit tests.

8.1 Condition Values

Condition values are used in the OpenVMS operating system to provide the following functions:

• Indicate the success or failure of a called procedure as a function value.
• Describe an exception condition when an exception is signaled.
• Identify system messages.
• Report program success or failure to the command language level.

A condition value is a longword that includes fields to describe the software component that generates the value, the reason the value was generated, and severity status of the condition value. Figure 8-1 shows the format of a condition value. Table 8-1 describes the fields of a condition value.

Figure 8-1 Format of a Condition Value

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

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

• The calling program typically performs a low-bit test, so it treats warnings, errors, and severe errors as failures, and treats success and information as successes.
• If the condition value is signaled (see Section 8.4.3), the default handler treats severe errors as reason to terminate and treats all the others as the basis for continuation.
• When the program image exits, the command interpreter by default treats errors and severe errors as the basis for stopping the job, and treats warnings, information, and successes as the basis for continuation.

The following table summarizes the action default decisions of the severity conditions:

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.

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