HP OpenVMS Systems Documentation
HP OpenVMS Calling Standard
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.
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:
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.|
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.
|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|
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.
|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:
|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:
The OpenVMS Condition Handling Facility (CHF) provides functions to perform the following operations: