[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

Content starts here

HP OpenVMS Calling Standard


Previous Contents Index

7.14.1 Facility-Specific Descriptor Class Codes

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.


Chapter 8
OpenVMS Conditions

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


Table 8-1 Contents of the Condition Value
Symbol Description
Severity Indicates success or failure. The severity code bit <0> is set for success (logical true) and is clear for failure (logical false); bits <1> and <2> distinguish degrees of success or failure. Bits <2:0>, when taken as an unsigned integer, are interpreted as shown in the following table:
Symbol Value Description
STS$K_WARNING 0 Warning
STS$K_SUCCESS 1 Success
STS$K_ERROR 2 Error
STS$K_INFO 3 Information
STS$K_SEVERE 4 Severe error
  5 Reserved to Hewlett-Packard
  6 Reserved to Hewlett-Packard
  7 Reserved to Hewlett-Packard

Section 8.1.1 more fully describes severity codes.

Condition identification Identifies the condition uniquely on a systemwide basis.
Message number Describes the status, which can be a hardware exception that occurred or a software-defined value. Message numbers with bit <15> set are specific to a single facility. Message numbers with bit <15> clear are systemwide status codes.
Facility number Identifies the software component generating the condition value. Bit <27> is set for customer facilities and is clear for Hewlett-Packard facilities.
Control Controls the printing of the message associated with the condition value. Bit <28> inhibits the message associated with the condition value from being printed by the SYS$EXIT system service. This bit is set by the system default handler after it has output an error message using the SYS$PUTMSG system service. It should also be set in the condition value returned by a procedure as a function value, if the procedure has also signaled the condition (so the condition has been printed or suppressed). Bits <31:29> must be 0; they are reserved to Hewlett-Packard for future use.

Table 8-2 lists the possible software symbols that are defined for the various fields of the condition-value longword.

Table 8-2 Value Symbols for the Condition Value Longword
Symbol Value Meaning Field
STS$V_COND_ID 3 Position of 27:3 Condition identification
STS$S_COND_ID 25 Size of 27:3 Condition identification
STS$M_COND_ID Mask Mask for 27:3 Condition identification
STS$V_INHIB_MSG 1@28 Position for 28 Inhibit message on image exit
STS$S_INHIB_MSG 1 Size for 28 Inhibit message on image exit
STS$M_INHIB_MSG Mask Mask for 28 Inhibit message on image exit
STS$V_FAC_NO 16 Position of 27:16 Facility number
STS$S_FAC_NO 12 Size of 27:16 Facility number
STS$M_FAC_NO Mask Mask for 27:16 Facility number
STS$V_CUST_DEF 27 Position for 27 Customer facility
STS$S_CUST_DEF 1 Size for 27 Customer facility
STS$M_CUST_DEF 1@27 Mask for 27 Customer facility
STS$V_MSG_NO 3 Position of 15:3 Message number
STS$S_MSG_NO 13 Size of 15:3 Message number
STS$M_MSG_NO Mask Mask for 15:3 Message number
STS$V_FAC_SP 15 Position of 15 Facility-specific
STS$S_FAC_SP 1 Size for 15 Facility-specific
STS$M_FAC_SP 1@15 Mask for 15 Facility-specific
STS$V_CODE 3 Position of 14:3 Message code
STS$S_CODE 12 Size of 14:3 Message code
STS$M_CODE Mask Mask for 14:3 Message code
STS$V_SEVERITY 0 Position of 2:0 Severity
STS$S_SEVERITY 3 Size of 2:0 Severity
STS$M_SEVERITY 7 Mask for 2:0 Severity
STS$V_SUCCESS 0 Position of 0 Success
STS$S_SUCCESS 1 Size of 0 Success
STS$M_SUCCESS 1 Mask for 0 Success

8.1.1 Interpretation of Severity Codes

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.

Table 8-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 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:

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.

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.

8.4 Operations Involving Condition Handlers

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.


Previous Next Contents Index