Document revision date: 19 July 1999
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

OpenVMS Programming Interfaces: Calling a System Routine


Previous Contents Index

1.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 1.4.3 and 1.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 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 or Alpha registers, the registers cannot be used to convey completion status information. All routines that return actual data in VAX or Alpha 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 status.

1.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.

Digital's system routines never signal condition values indicating success. Only error condition values are signaled.

1.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.

1.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 1.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 B-1 for a list of the possible OpenVMS usage entries and their definitions. Refer to the appropriate language implementation table in Appendix B 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 programs.

1.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 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) partly on the stack. The argument information (AI) register contains the argument count that specifies the number of 64-bit argument items.

When arguments are passed by descriptors, these standard data types are defined with symbolic codes. Table 1-3 lists the standard data types for VAX and Alpha systems that can appear for the type entry in an argument description, along with their symbolic code (DTYPE) used in argument descriptors.

For a detailed description of each of the following symbolic codes, see the OpenVMS Calling Standard.

Table 1-3 Standard Data Types and Their Descriptor Field Symbols
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 DSC$K_DTYPE_BPV
Byte (unsigned) DSC$K_DTYPE_BU
COBOL intermediate temporary DSC$K_DTYPE_CIT
D_floating DSC$K_DTYPE_D
D_floating complex DSC$K_DTYPE_DC
Descriptor DSC$K_DTYPE_DSC
F_floating DSC$K_DTYPE_F
F_floating complex DSC$K_DTYPE_FC
G_floating DSC$K_DTYPE_G
G_floating complex DSC$K_DTYPE_GC
+H_floating DSC$K_DTYPE_H
+H_floating complex DSC$K_DTYPE_HC
++S_floating (32-bit IEEE) DSC$K_DTYPE_FS
++T_floating (64-bit IEEE) DSC$K_DTYPE_FT
++X_floating (128-bit IEEE) DSC$K_DTYPE_FX
++S_floating complex DSC$K_DTYPE_FSC
++T_floating complex DSC$K_DTYPE_FTC
++X_floating complex DSC$K_DTYPE_FXC
Longword integer (signed) DSC$K_DTYPE_L
Longword (unsigned) DSC$K_DTYPE_LU
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
Octaword (unsigned) DSC$K_DTYPE_OU
Packed decimal string DSC$K_DTYPE_P
Quadword integer (signed) DSC$K_DTYPE_Q
Quadword (unsigned) DSC$K_DTYPE_QU
Character string DSC$K_DTYPE_T
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
Word (unsigned) DSC$K_DTYPE_WU
Unspecified DSC$K_DTYPE_Z
+Procedure entry mask DSC$K_DTYPE_ZEM
+Sequence of instruction DSC$K_DTYPE_ZI


+VAX specific.
++Alpha specific.

1.4.3 Access Entry

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 OpenVMS Calling Standard.

1.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:

Table 1-4 Descriptor Classes of Passing Mechanisms
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

1.4.5 Explanatory Text

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:

  1. A sentence or a sentence fragment that describes (1) the nature of the data specified by the argument, and (2) the way in which the routine uses this data. For example, if an argument were supplying a number, which the routine converts to another data type, the argument description would contain the following sentence fragment:

    Integer to be converted to an F_floating point number
  2. A sentence that expresses the relationship between the argument and the data that it specifies. This relationship is the passing mechanism used to pass the data and, for a given argument, is expressed in one of the following ways:
    1. If the passing mechanism is by value, the sentence should read as follows:

      The attrib argument is a longword that contains (or is) the bit mask specifying the attributes.
    2. If the passing mechanism is by reference, the sentence should read as follows:

      The objtyp argument is the address of a longword containing a value indicating whether the object is a file or a device.
    3. If the passing mechanism is by descriptor, the sentence should read as follows:

      The devnam argument is the address of a string descriptor of a logical name denoting a device name.
  3. Additional explanatory paragraphs that appear for each argument, as needed. For example, some arguments specify complex data consisting of many discrete fields, each of which has a particular purpose and use. In such cases, additional paragraphs provide detailed descriptions of each such field, symbolic names for the fields, if any, and guidance on their use.

1.5 Condition Values Returned Heading

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

The 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:

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.

1.5.1 Condition Values Returned

The possible condition values that the called routine can return in general register R0 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.

1.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 B-1 or Section 2.11 for the field detail of the condition value structure.


Previous Next Contents Index

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
5843PRO_001.HTML