|
||||||||||
|
|
|
|
|
|
|
|
|
|
|
|
||||||||||
|
 |
 |
HP OpenVMS systems documentation |
|
| Previous | Contents | Index |
The SS$_NOPRIV and SS$_EXQUOTA condition values returned by a number of system service procedures require special checking. Any system service that is listed as returning SS$_NOPRIV or SS$_EXQUOTA can instead return a more specific condition value that indicates the privilege or quota in question. Table 9-8 list the specific privilege errors, and Table 9-9 lists the quota errors.
| SS$_NOACNT | SS$_NOALLSPOOL | SS$_NOALTPRI |
| SS$_NOBUGCHK | SS$_NOBYPASS | SS$_NOCMEXEC |
| SS$_NOCMKRNL | SS$_NODETACH | SS$_NODIAGNOSE |
| SS$_NODOWNGRADE | SS$_NOEXQUOTA | SS$_NOGROUP |
| SS$_NOGRPNAM | SS$_NOGRPPRV | SS$_NOLOGIO |
| SS$_NOMOUNT | SS$_NONETMBX | SS$_NOOPER |
| SS$_NOPFNMAP | SS$_NOPHYIO | SS$_NOPRMCEB |
| SS$_NOPRMGBL | SS$_NOPRMMBX | SS$_NOPSWAPM |
| SS$_NOREADALL | SS$_NOSECURITY | SS$_NOSETPRV |
| SS$_NOSHARE | SS$_NOSHMEM | SS$_NOSYSGBL |
| SS$_NOSYSLCK | SS$_NOSYSNAM | SS$_NOSYSPRV |
| SS$_NOTMPMBX | SS$_NOUPGRADE | SS$_NOVOLPRO |
| SS$_NOWORLD |
| SS$_EXASTLM | SS$_EXBIOLM | SS$_EXBYTLM |
| SS$_EXDIOLM | SS$_EXENQLM | SS$_EXFILLM |
| SS$_EXPGFLQUOTA | SS$_EXPRCLM | SS$_EXTQELM |
Because either a general or a specific value can be returned, your program must test for both. The following four symbols provide a starting and ending point with which you can compare the returned condition value:
The following HP Fortran example tests for a privilege error by comparing STATUS (the returned condition value) with the specific condition value SS$_NOPRIV and the range provided by SS$_NOPRIVSTRT and SS$_NOPRIVEND. You would test for SS$_NOEXQUOTA in a similar fashion.
. . . ! Declare status and status values INTEGER STATUS INCLUDE '($SSDEF)' . . . IF (.NOT. STATUS) THEN IF ((STATUS .EQ. SS$_NOPRIV) .OR. 2 ((STATUS .GE. SS$_NOPRIVSTRT) .AND. 2 (STATUS .LE. SS$_NOPRIVEND))) THEN . . . ELSE CALL LIB$SIGNAL (%VAL(STATUS)) END IF END IF |
To modify a condition value, copy a series of bits from one longword to another longword. For example, the following statement copies the first three bits (bits <2:0>) of STS$K_INFO to the first three bits of the signaled condition code, which is in the second element of the signal array named SIGARGS. As shown in Table 9-7, STS$K_INFO contains the symbolic severity code for an informational message.
! Declare STS$K_ symbols INCLUDE '($STSDEF)' . . . ! Change the severity of the condition code ! in SIGARGS(2) to informational CALL MVBITS (STS$K_INFO, 2 0, 2 3, 2 SIGARGS(2), 2 0) |
Once you modify the condition value, you can resignal the condition value and either let the default condition handler display the associated message or use the SYS$PUTMSG system service to display the message. If your condition handler displays the message, do not resignal the condition value, or the default condition handler will display the message a second time.
In the following example, the condition handler verifies that the signaled condition value is LIB$_NOSUCHSYM. If it is, the handler changes its severity from error to informational and then resignals the modified condition value. As a result of the handler's actions, the program displays an informational message indicating that the specified symbol does not exist, and then continues executing.
INTEGER FUNCTION SYMBOL (SIGARGS, 2 MECHARGS) ! Changes LIB$_NOSUCHSYM to an informational message ! Declare dummy arguments INTEGER*4 SIGARGS(*), 2 MECHARGS(*) ! Declare index variable for LIB$MATCH_COND INTEGER INDEX ! Declare condition codes INCLUDE '($LIBDEF)' INCLUDE '($STSDEF)' INCLUDE '($SSDEF)' ! Declare library procedures INTEGER LIB$MATCH_COND INDEX = LIB$MATCH_COND (SIGARGS(2), 2 LIB$NO_SUCHSYM) ! If the signaled condition code is LIB$NO_SUCHSYM, ! change its severity to informational. IF (INDEX .GT. 0) 2 CALL MVBITS (STS$K_INFO, 2 0, 2 3, 2 SIGARGS(2), 2 0) SYMBOL = SS$_RESIGNAL END |
When an exception occurs, control is passed to the operating system's exception-dispatching routine. The exception dispatcher searches for a condition-handling routine invoking the first handler it finds and passes the information to the handler about the condition code and the state of the program when the condition code was signaled. If the handler resignals, the operating system searches for another handler; otherwise, the search for a condition handler ends.
The operating system searches for condition handlers in the following sequence:
The search is terminated when the dispatcher finds a condition handler. If the dispatcher cannot find a user-specified condition handler, it calls the condition handler whose address is stored in the last-chance exception vector. If the image was activated by the command language interpreter, the last-chance vector points to the catchall condition handler. The catchall handler issues a message and either continues program execution or causes the image to exit, depending on whether the condition was a warning or an error condition, respectively.
You can call the catchall handler in two ways:
Figure 9-4 illustrates the exception dispatcher's search of the call stack for a condition handler.
Figure 9-4 Searching the Stack for a Condition Handler
In cases where the default condition handling is insufficient, you can establish your own handler by one of the mechanisms described in Section 9.2.1. Typically, you need condition handlers only if your program must perform one of the following operations:
On VAX systems, the argument list passed to the condition handler is constructed on the stack and consists of the addresses of two argument arrays, signal and mechanism, as illustrated in Section 9.8.2 and Section 9.8.3.
On Alpha and I64 systems, the arrays are set up on the stack, but any argument is passed in registers.
On VAX systems, you can use the $CHFDEF macro instruction to define the symbolic names to refer to the arguments listed in Table 9-10.
| Symbolic Name | Related Argument |
|---|---|
| CHF$L_SIGARGLST | Address of signal array |
| CHF$L_MCHARGLST | Address of mechanism array |
| CHF$L_SIG_ARGS | Number of signal arguments |
| CHF$L_SIG_NAME | Condition name |
| CHF$L_SIG_ARG1 | First signal-specific argument |
| CHF$L_MCH_ARGS | Number of mechanism arguments |
| CHF$L_MCH_FRAME | Establisher frame address |
| CHF$L_MCH_DEPTH | Frame depth of establisher |
| CHF$L_MCH_SAVR0 | Saved register R0 |
| CHF$L_MCH_SAVR1 | Saved register R1 |
On Alpha and I64 systems, you can use the $CHFDEF2 macro instruction to define the symbolic names to refer to the arguments listed in Table 9-11.
| Symbolic Name | Related Argument |
|---|---|
| CHF$L_SIGARGLST | Address of signal array |
| CHF$L_MCHARGLST | Address of mechanism array |
| CHF$IS_SIG_ARGS | Number of signal arguments |
| CHF$IS_SIG_NAME | Condition name |
| CHF$IS_SIG_ARG1 | First signal-specific argument |
| CHF$IS_MCH_ARGS | Number of mechanism arguments |
| CHF$IS_MCH_FLAGS | Flag bits <63:0> for related argument mechanism information |
| CHF$PH_MCH_FRAME | Establisher frame address |
| CHF$IS_MCH_DEPTH | Frame depth of establisher |
| CHF$PH_MCH_DADDR | Address of the handler data quadword if the exception handler data field is present |
| CHF$PH_MCH_ESF_ADDR | Address of the exception stack frame |
| CHF$PH_MCH_SIG_ADDR | Address of the signal array |
| CHF$IH_MCH_SAVR nn | A copy of the saved integer registers at the time of the exception |
| CHF$FH_MCH_SAVF nn | A copy of the saved floating-point registers at the time of the exception |
Signaling can be initiated when hardware or software detects an exception condition. In either case, the exception condition is said to be signaled by the routine in which it occurred. If hardware detects the error, it passes control to a condition dispatcher. If software detects the error, it calls one of the run-time library signal-generating routines: LIB$SIGNAL or LIB$STOP. The RTL signal-generating routines pass control to the same condition dispatcher. When LIB$STOP is called, the severity code is forced to severe, and control cannot return to the routine that signaled the condition. See Section 9.12.1 for a description of how a signal can be dismissed and how normal execution from the point of the exception condition can be continued.
When a routine signals, it passes to the OpenVMS Condition Handling facility (CHF) the condition value associated with the exception condition, as well as optional arguments that can be passed to a condition handler. The CHF uses these arguments to build two data structures on the stack:
These two vectors become the arguments that the CHF passes to condition handlers.
These argument vectors are described in detail in Section 9.8.2 and Section 9.8.3.
After the signal and mechanism argument vectors are set up, the CHF searches for enabled condition handlers. A condition handler is a separate routine that has been associated with a routine in order to take a specific action when an exception condition occurs. The CHF searches for condition handlers to handle the exception condition, beginning with the primary exception vector of the access mode in which the exception condition occurred. If this vector contains the address of a handler, that handler is called. If the address is 0 or if the handler resignals, then the CHF repeats the process with the secondary exception vector. Enabling vectored handlers is discussed in detail in the HP OpenVMS Calling Standard. Because the exception vectors are allocated in static storage, they are not generally used by modular routines.
If neither the primary nor secondary vectored handlers handle the exception condition by continuing program execution, then the CHF looks for stack frame condition handlers. It looks for the address of a condition handler in the first longword of the routine stack frame on VAX systems, in the procedure descriptor (in which the handler valid bit is set) for the routine stack frame on Alpha systems where the exception condition occurred, or in the unwind data on I64. At this point, several actions are possible, depending on the results of this search:
The OpenVMS Condition Handling facility searches for and calls condition handlers from each frame on the stack until the frame pointer is zero (indicating the end of the call sequence). At that point, the CHF calls the vectored catchall handler, which displays an error message and causes the program to exit. Note that, normally, the frame containing the stack catchall handler is at the end of the calling sequence or at the bottom of the stack. Section 9.9 explains the possible actions of default and user condition handlers in more detail.
Figure 9-5 illustrates a stack scan for condition handlers in which the main program calls procedure A, which then calls procedure B. A stack scan is initiated either when a hardware exception condition occurs or when a call is made to LIB$SIGNAL or LIB$STOP.
Figure 9-5 Sample Stack Scan for Condition Handlers
When software detects an exception condition, the software normally calls one of the run-time library signal-generating routines, LIB$SIGNAL or LIB$STOP, to initiate the signaling mechanism. This call indicates to the calling program that the exception condition has occurred. Your program can also call one of these routines explicitly to indicate an exception condition.
You can signal a condition code by invoking the run-time library procedure LIB$SIGNAL and passing the condition code as the first argument. (The HP OpenVMS RTL Library (LIB$) Manual contains the complete specifications for LIB$SIGNAL.) The following statement signals the condition code contained in the variable STATUS:
|
CALL LIB$SIGNAL (%VAL(STATUS)) |
When an error occurs in a subprogram, the subprogram can signal the appropriate condition code rather than return the condition code to the invoking program unit. In addition, some statements also signal condition codes; for example, an assignment statement that attempts to divide by zero signals the condition code SS$_INTDIV.
When your program wants to issue a message and allow execution to continue after handling the condition, it calls the standard routine, LIB$SIGNAL. The calling sequence for LIB$SIGNAL is the following:
LIB$SIGNAL condition-value [,condition-argument...]
[,condition-value-n [,condition-argument-n...]...]
|
Only the condition-value argument must be specified; other arguments are optional. A description of the arguments is as follows:
condition-value
OpenVMS 32-bit condition value. The condition-value argument is an unsigned longword that contains this condition value. Section 9.5 explains the format of a condition value.
OpenVMS usage: cond_value type: longword (unsigned) access: read only mechanism: by value condition-argument
As many arguments as are required to process the exception specified by condition-value. These arguments are also used as FAO (formatted ASCII output) arguments to format a message.
OpenVMS usage: varying_arg type: unspecified access: read only mechanism: by value condition-value-n
OpenVMS 32-bit condition value. The optional condition-value-n argument is an unsigned longword that contains this condition value. The calling routine can specify additional conditions to be processed by specifying condition-value-2 through condition-value-n, with each condition value followed by any arguments required to process the condition specified. However, the total number of arguments in the call to LIB$SIGNAL must not exceed 253.
OpenVMS usage: cond_value type: longword (unsigned) access: read only mechanism: by value condition-argument-n
As many arguments as required to create the message reporting the exception specified by condition-value-n.
OpenVMS usage: varying_arg type: unspecified access: read only mechanism: by value
When your program wants to issue a message and stop execution unconditionally, it calls LIB$STOP. The calling sequence for LIB$STOP is as follows:
|
LIB$STOP condition-value [,number-of-arguments] [,FAO-argument....] |
Only the condition-value argument must be specified; other arguments are optional. The condition-value argument is an OpenVMS 32-bit condition value. The condition-value argument is an unsigned longword that contains this condition value.
The number-of-arguments argument, if specified, contains the number of FAO arguments that are associated with condition-value. The optional number-of-arguments argument is a signed longword integer that contains this number. If omitted or specified as zero, no FAO arguments follow.
The FAO-argument argument is an optional FAO (formatted ASCII output) argument that is associated with the specified condition value.
The condition-value argument indicates the condition that is being signaled. However, LIB$STOP always sets the severity of condition-value to SEVERE before proceeding with the stack-scanning operation.
The FAO arguments describe the details of the exception condition. These are the same arguments that are passed to the OpenVMS Condition Handling facility as part of the signal argument vector. The system default condition handlers pass them to SYS$PUTMSG, which uses them to issue a system message.
Unlike most routines, LIB$SIGNAL and LIB$STOP preserve R0 and R1 as well as the other registers. Therefore, a call to LIB$SIGNAL allows the debugger to display the entire state of the process at the time of the exception condition. This is useful for debugging checks and gathering statistics.
The behavior of LIB$SIGNAL is the same as that of the exception dispatcher that performs the stack scan after hardware detects an exception condition. That is, the system scans the stack in the same way, and the same arguments are passed to each condition handler. This allows a user to write a single condition handler to detect both hardware and software conditions.
For more information about the RTL routines LIB$SIGNAL and LIB$STOP, see the HP OpenVMS RTL Library (LIB$) Manual.
| Previous | Next | Contents | Index |