HP OpenVMS systems
The JSB call format indicates that the named routine is called using the VAX JSB instruction. The routine returns using Return from Subroutine (RSB). You can use the JSB call format with only the VAX MACRO and VAX BLISS languages.
Explanatory text might follow the procedure call format or the JSB call
format, or both. This text is present only when needed to clarify the
format. For example, in the call format, you indicate that arguments
are optional by enclosing them in brackets (). However, brackets
alone cannot convey all the important information that might apply to
optional arguments. For example, in some routines that have many
optional arguments, if you select one optional argument, you must also
select another optional argument. In such cases, text following the
format clarifies this.
17.3 Returns Heading
The Returns heading contains a description of any information returned
by the routine to the caller. A routine can return information to the
caller in various ways. The following subsections discuss each
possibility and then describe how this returned information is
17.3.1 Condition Values Returned in a Register
Most routines return a condition value in register R0. This condition value contains various kinds of information, the most important for the caller (in bits <3:0>) being the completion status of the operation. You test the condition value to determine whether the routine completed successfully. On OpenVMS I64, the calling standard specifies that return status is returned in R8. As an aid to portable code, the MACRO complier automatically maps R0 to R8. See the HP OpenVMS MACRO Compiler Porting and User's Guide for additional information.
On Alpha and I64 processors, a 32-bit condition value is represented in the Alpha register sign-extended to 64 bits.
If you program in high-level languages for OpenVMS environments, the fact that status information is returned by means of a condition value and that it is returned in a hardware register is of little importance because you receive this status information in the return (or status) variable. The run-time environment established for the high-level language program allows the status information in R0 (R8, R9 for I64) to be moved automatically to the user's return variable.
Nevertheless, for routines that return a condition value, the Returns heading in the documentation contains the following information:
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
The OpenVMS usage entry specifies the OpenVMS data type of the information returned. Because a condition value in any OpenVMS operating system environment is returned in a specific condition value structure, the OpenVMS usage entry is cond_value.
The type entry specifies the standard data type of the information returned. Because the condition value structure is 32 bits, the type heading is longword (unsigned).
The access entry specifies the way in which the called routine accesses the object. Because the called routine is returning the condition value, the routine writes the value into R0 (R8, R9 for I64), so the access heading is write only.
The mechanism heading specifies the passing mechanism used by the called routine in returning the condition value. Because the called routine is writing the condition value directly into R0 (R8, R9 for I64), the mechanism heading is by value. (If the called routine had written the address of the condition value into R0 (R8, R9 for I64), the passing mechanism would have been by reference.)
Note that if a routine returns a condition value, another main heading
in the documentation format (Condition Values Returned) describes the
possible condition values that the routine can return.
17.3.2 Other Returned Values
If a routine returns actual data, the Returns heading in the documentation of that routine contains the following information (for example, from a math routine):
OpenVMS usage: floating_point type: G_floating access: write only mechanism: by value
In this mathematics routine notation, the OpenVMS data type is floating_point and the standard data type is G_floating point. The meaning of the contents of the access and mechanism headings is discussed in Sections 17.4.3 and 17.4.4.
The registers used to return values vary with the type of the result and the specific hardware environment. For more information, see the HP OpenVMS Calling Standard.
In addition, under the Returns heading, some text can be provided after the information about the type, access, and mechanism. This text explains other relevant information about what the routine is returning.
For example, because the routine is returning actual data in the VAX,
Alpha, or I64 registers, the registers cannot be used to convey
completion status information. All routines that return actual data in
VAX, Alpha, or I64 registers must signal the condition
value, which contains the completion status. Thus, the text under the
Returns heading points out that the routine signals its completion
17.3.3 Condition Values Signaled
Although most routines return condition values, some routines choose to signal their condition values using the OpenVMS signaling mechanism. Routines can signal their completion status whether or not they are returning actual data in the hardware registers, but all routines that return actual data in the hardware registers must signal their completion status if they are to return this status information at all.
If a routine signals its completion status, text under the Returns heading explains this, and the Condition Values Signaled heading in the documentation format describes the possible condition values that the routine can signal.
HP's system routines never signal condition values indicating success.
Only error condition values are signaled.
17.4 Arguments Heading
Detailed information about each argument is listed in the call format under the Arguments heading. Arguments are described in the order in which they appear in the call format. If the routine has no arguments, the word None appears.
The following format is used to describe each argument:
argument-name OpenVMS usage: OpenVMS data type type: argument data type access: argument access mechanism: argument passing mechanism
A paragraph of structured text describing the arguments follows the
argument format along with additional information, if needed.
17.4.1 OpenVMS Usage Entry
The purpose of the OpenVMS usage entry is to facilitate the coding of source-language data type declarations in application programs. Ordinarily, the standard data type, discussed in Section 17.4.2, is sufficient to describe the type of data passed by an argument. However, within the OpenVMS operating system environment, many system routines contain arguments whose conceptual nature or complexity requires additional explanation. For instance, when an argument passes the name of an event flag, the type entry longword (unsigned) alone does not indicate the nature of the value. In this instance, an accompanying OpenVMS usage entry, denoting the OpenVMS data type ef_number, further explains the actual usage.
See Table E-1 for a list of the possible OpenVMS usage entries and their definitions. Refer to the appropriate language implementation table in Appendix E to determine the correct syntax of the type declaration in the language you are using.
Note that the OpenVMS usage entry is not a traditional data type (such
as the standard data types of byte, word, longword, and so on). It is
significant only within the context of the OpenVMS operating system and
is intended solely to expedite data declarations within application
17.4.2 Type Entry
In actuality, an argument does not have a data type; rather, the data specified by an argument has a data type. The argument is merely the vehicle for passing data to the called routine. Nevertheless, the phrase argument data type is used to describe the standard data type of the data specified by the argument.
Procedure calls result in the construction of an argument list. (This process is described in the HP OpenVMS Calling Standard.) An argument list is a sequence of entries together with a count of the number of entries.
On VAX systems, an argument list is represented as a vector of longwords, where the first longword contains the count and each remaining longword contains one argument.
On Alpha systems, an argument list is represented as quadword entities that comprise an argument item sequence, partly in hardware registers and (when there are more than six arguments for Alpha) partly on the stack. The argument information (AI) register contains the argument count that specifies the number of 64-bit argument items.
For I64 systems, parameters are passed in a combination of general registers, floating-point registers, and memory, as described in Chapter 18, and as illustrated in Figure 18-9. The parameter list is formed by placing each individual parameter into fixed-size elements of the parameter list, referred to as parameter slots. Each parameter slot is 64 bits wide; parameters larger than 64 bits are placed in as many consecutive parameter slots as are needed to contain the entire parameter. The rules for allocation and alignment of parameter slots are described in Section 184.108.40.206. The contents of the first eight parameter slots are always passed in registers, while the remaining parameters are always passed on the memory stack, beginning at the caller's stack pointer plus 16 bytes.
When arguments are passed by descriptors, these standard data types are defined with symbolic codes. Table 17-3 lists the standard data types for VAX, Alpha, and I64 systems that can appear for the type entry in an argument description, along with their symbolic code (DTYPE) used in argument descriptors.
|Data Type||Symbolic Code|
|Absolute date and time||DSC$K_DTYPE_ADT|
|Byte integer (signed)||DSC$K_DTYPE_B|
|Bound label value||DSC$K_DTYPE_BLV|
|Bound procedure value 1||DSC$K_DTYPE_BPV|
|COBOL intermediate temporary||DSC$K_DTYPE_CIT|
|H_floating complex 1||DSC$K_DTYPE_HC|
|S_floating (32-bit IEEE) 2||DSC$K_DTYPE_FS|
|T_floating (64-bit IEEE) 2||DSC$K_DTYPE_FT|
|X_floating (128-bit IEEE) 2||DSC$K_DTYPE_FX|
|S_floating complex 2||DSC$K_DTYPE_FSC|
|T_floating complex 2||DSC$K_DTYPE_FTC|
|X_floating complex 2||DSC$K_DTYPE_FXC|
|Longword integer (signed)||DSC$K_DTYPE_L|
|Numeric string, left separate sign||DSC$K_DTYPE_NL|
|Numeric string, left overpunched sign||DSC$K_DTYPE_NLO|
|Numeric string, right separate sign||DSC$K_DTYPE_NR|
|Numeric string, right overpunched sign||DSC$K_DTYPE_NRO|
|Numeric string, unsigned||DSC$K_DTYPE_NU|
|Numeric string, zoned sign||DSC$K_DTYPE_NZ|
|Octaword integer (signed)||DSC$K_DTYPE_O|
|Packed decimal string||DSC$K_DTYPE_P|
|Quadword integer (signed)||DSC$K_DTYPE_Q|
|Aligned bit string||DSC$K_DTYPE_V|
|Varying character string||DSC$K_DTYPE_VT|
|Unaligned bit string||DSC$K_DTYPE_VU|
|Word integer (signed)||DSC$K_DTYPE_W|
|Procedure entry mask 1||DSC$K_DTYPE_ZEM|
|Sequence of instruction 1||DSC$K_DTYPE_ZI|
The access entry describes the way in which the called routine accesses the data specified by the argument, or access method. The following methods of access are most common:
Following is a complete list of access methods that can appear under the access entry in an argument description:
For more information, see the HP OpenVMS Calling Standard.
17.4.4 Mechanism Entry
The way in which an argument specifies the actual data to be used by the called routine is defined in terms of the argument passing mechanism. There are three basic passing mechanism types:
|Passing Mechanism||Descriptor Symbolic Code|
|By descriptor, fixed-length (scalar)||DSC$K_CLASS_S|
|By descriptor, dynamic string||DSC$K_CLASS_D|
|By descriptor, array||DSC$K_CLASS_A|
|By descriptor, procedure||DSC$K_CLASS_P|
|By descriptor, decimal string||DSC$K_CLASS_SD|
|By descriptor, noncontiguous array||DSC$K_CLASS_NCA|
|By descriptor, varying string||DSC$K_CLASS_VS|
|By descriptor, varying string array||DSC$K_CLASS_VSA|
|By descriptor, unaligned bit string||DSC$K_CLASS_UBS|
|By descriptor, unaligned bit array||DSC$K_CLASS_UBA|
|By descriptor, string with bounds||DSC$K_CLASS_SB|
|By descriptor, unaligned bit string with bounds||DSC$K_CLASS_UBSB|
For each argument, one or more paragraphs of explanatory text follow the OpenVMS usage, type, access, and mechanism entries. The first paragraph is highly structured and always contains information in the following sequence: