HP OpenVMS Systems Documentation

HP OpenVMS Programming Concepts Manual

A condition value is a longword that has the following uses on the OpenVMS VAX, OpenVMS Alpha, and OpenVMS I64 systems:

• Indicates the success or failure of a called procedure
• Describes an exception condition when an exception is signaled
• Identifies system messages
• Reports program success or failure to the command level

The HP OpenVMS Calling Standard explains in detail the uses for the condition value and depicts its format and contents.

The Condition Values Returned heading describes the condition values that are returned by the routine when it completes execution without generating an exception condition. These condition values describe the completion status of the operation.

If a called routine generates an exception condition during execution, the exception condition is signaled; the exception condition is then handled by a condition handler (either user supplied or system supplied). Depending on the nature of the exception condition and on the condition handler, the called routine either continues normal execution or terminates abnormally.

If a called routine executes without generating an exception condition, the called routine returns a condition value in one or two of the following ways:

• Condition Values Returned
• Condition Values Returned in an I/O Status Block
• Condition Values Returned in a Mailbox
• Condition Values Signaled

The method used to return the condition value is indicated under the Condition Values Returned heading in the documentation of each routine. These methods are discussed individually in the following subsections.

Under these headings, a two-column list shows the symbolic code for each condition value the routine can return and an accompanying description. The description explains whether the condition value indicates success or failure and, if failure, what user action might have caused the failure and what to do to correct it. Condition values that indicate success are listed first.

Symbolic codes for condition values are defined by the system. Though the condition value consists of several fields, each of which can be interpreted individually for specific information, the entire condition value itself can be interpreted as an integer, and this integer has an equivalent symbolic code.

The three sections that follow discuss the ways in which the called routine returns condition values.

17.5.1 Condition Values Returned

The possible condition values that the called routine can return in general register R0 (R8, R9 for I64) are listed under the Condition Values Returned heading in the documentation. Most routines return a condition value in this way.

In the documentation of system services that complete asynchronously, both the Condition Values Returned and Condition Values Returned in the I/O Status Block headings are used. Under the Condition Values Returned heading, the condition values returned by the asynchronous service refer to the success or failure of the system service request---that is, to the status associated with the correctness of the syntax of the call, in contrast to the final status associated with the completion of the service operation. For asynchronous system services, condition values describing the success or failure of the actual service operation---that is, the final completion status---are listed under the Condition Values Returned in the I/O Status Block heading.

17.5.2 Condition Values Returned in an I/O Status Block

The possible condition values that the called routine can return in an I/O status block are listed under the Condition Values Returned in the I/O Status Block heading.

The routines that return condition values in the I/O status block are the system services that are completed asynchronously. Each of these asynchronous system services returns to the caller as soon as the service call is queued. This allows the continued use of the calling program during the execution of the service operations. System services that are completed asynchronously all have arguments that specify an I/O status block. When the system service operation is completed, a condition value specifying the completion status of the operation is written in the first word of this I/O status block.

Representing a condition value in a word-length field is possible for system services because the high-order segment of all system service condition values is 0. See cond_value in Table E-1 or Section 18.11 for the field detail of the condition value structure.

17.5.3 Condition Values Returned in a Mailbox

The possible condition values that the called routine can return in a mailbox are listed under the Condition Values Returned in a Mailbox heading.

Routines such as SYS$SNDOPR that return condition values in a mailbox send information to another process to perform a task. The receiving process performs the action and returns the status of the task to the mailbox of the sending process.

17.5.4 Condition Values Signaled

The possible condition values that the called routine can signal (instead of returning them in R0 (R8, R9 for I64) are listed under the Condition Values Signaled heading.

Routines that signal condition values as a way of indicating the completion status do so because these routines are returning actual data as the value of the routine.

As mentioned, the signaling of condition values occurs whenever a routine generates an exception condition, regardless of how the routine returns its completion status under normal circumstances.

The HP OpenVMS Calling Standard defines the concepts and conventions used by common languages to invoke routines and pass data between them. This chapter briefly describes the following calling standard conventions:

• Register usage
• Stack usage
• Argument list
• Argument passing
• Returns

Section 18.12.1 briefly compares OpenVMS I64 register usage to that on OpenVMS Alpha and OpenVMS VAX.

Refer to the HP OpenVMS Calling Standard for more detail on calling conventions and for standards defining argument data types, descriptor formats, and procedures for condition handling and stack unwinding.

18.1 Hardware Registers

Registers in the hardware provide the necessary temporary storage for computation within OpenVMS software procedures. The number of registers available and their usage vary between the OpenVMS Alpha, OpenVMS VAX, and OpenVMS I64 systems.

18.1.1 Register Usage for OpenVMS VAX

The calling standard defines several VAX registers and their use, as listed in Table 18-1.

By definition, any called routine can use registers R2 through R11 for computation and the AP register as a temporary register.

18.1.2 Register Usage for OpenVMS Alpha

On Alpha systems, there are two groups of 64-bit wide, general-purpose Alpha hardware registers:

• Integer
• Floating point

The first 32 general-purpose registers support integer processing; the second 32 support floating-point operations.

18.1.2.1 Integer Registers

The calling standard defines the Alpha general-purpose integer registers and their use, as listed in Table 18-2.

18.1.2.2 Floating-Point Registers

The Intel® Itanium® architecture defines 128 general purpose registers, 128 floating­point registers, 64 predicate registers, 8 branch registers, and up to 128 application registers. The large number of architectural registers enable multiple computations to be performed without having to frequently spill and fill intermediate data to memory.

The instruction pointer is a 64­bit register that points to the currently executing instruction bundle.

This section describes the register conventions for OpenVMS I64.

OpenVMS I64 uses the following register types:

• General
• Floating-point
• Predicate
• Branch
• Application

Registers are partitioned into the following classes that define the way a register can be used within a procedure:

• Scratch registers -- may be modified by a procedure call; the caller must save these registers before a call if needed (caller save).
• Preserved registers -- must not be modified by a procedure call; the callee must save and restore these registers if used (callee save). A procedure using one of the preserved general registers must save and restore the caller's original contents, including the NaT bits associated with the registers, without generating a NaT consumption fault.
  One way to preserve a register is not to use it at all.
• Automatic registers -- saved and restored automatically by the hardware call/return mechanism.
• Constant or Read-only registers -- contain a fixed value that cannot be changed by the program.
• Special registers -- used in the calling standard call/return mechanism.
• Global registers -- shared across a set of cooperating routines as global static storage that happens to be allocated in a register. (Details regarding the dynamic lifetime of such storage are not addressed here.)

OpenVMS I64 further defines the way that static registers can be used between routines:

• Special registers -- used in the calling standard call/return mechanism. (These are the same as the set of special registers in the preceding list of registers used within a procedure.)
• Input registers -- may be used to pass information into a procedure (in addition to the normal stacked input registers).
• Output registers -- may be used to pass information back from a called procedure to its caller (in addition to the normal return value registers).
• Volatile registers -- may not be used to pass information between procedures, either as input or output.

There are 128, 64­bit general-purpose registers (R0­R127) that are used to hold values for integer and multimedia computations. Each of the 128 registers has one additional NaT (Not a Thing) bit that is used to indicate whether the value stored in the register is valid. Execution of I64 speculative instructions can result in a register's NaT bit being set. Register R0 is read only and contains a value of zero (0). Attempting to write to R0 will cause a fault.

This standard defines the usage of the OpenVMS general registers as listed in Table 18-4.

18.1.3.3 I64 Floating-Point Register Usage

This standard defines the usage of the OpenVMS floating-point registers as listed in Table 18-5.