OpenVMS Programming Interfaces: Calling a System Routine

Document revision date: 19 July 1999

Order Number: AA--PV68C--TK

January 1999

This manual describes the OpenVMS programming interface and defines the standard conventions to call an OpenVMS system routine from a user procedure. The Alpha and VAX data type implementations for various high-level languages are also presented in this manual.

Revision/Update Information: This manual supersedes the OpenVMS Programming Interfaces: Calling a System Routine, OpenVMS AXP Version 1.5 and OpenVMS VAX Version 6.0.

Software Version: OpenVMS Alpha Version 7.1 OpenVMS VAX Version 7.1

The content of this document has not changed since OpenVMS Version 7.1

Compaq Computer Corporation Houston, Texas

Reprinted January 1999

Compaq Computer Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description.

Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Compaq or an authorized sublicensor.

Compaq conducts its business in a manner that conserves the environment and protects the safety and health of its employees, customers, and the community.

The following are trademarks of Compaq Computer Corporation: Alpha, Compaq, DECdirect, DECwindows, DIGITAL, OpenVMS, VAX, VAX DOCUMENT, VAXcluster, VMS, and the Compaq logo.

The following are third-party trademarks:

All other trademarks and registered trademarks are the property of their respective holders.

ZK5843

The OpenVMS documentation set is available on CD-ROM.

This document was prepared using VAX DOCUMENT, Version V3.2n.

Contents Index

Preface

The OpenVMS Programming Interfaces: Calling a System Routine manual describes how application programs call routines supplied by the following system facilities:

OpenVMS Run-Time Library
OpenVMS system services
Utility routines
OpenVMS Record Management Services

These facilities provide OpenVMS routines to programs written in high-level languages and assembly language (VAX MACRO and MACRO-64 for OpenVMS Alpha). This manual also defines the OpenVMS usage data types and how OpenVMS usage data may be defined in the various high-level languages.

As of Version 7.0, the OpenVMS Alpha operating system provides support for 64-bit virtual addressing, which makes the 64-bit virtual address space defined by the Alpha architecture available to the OpenVMS Alpha operating system and to application programs. The 64-bit addressing features allow processes to map and access data beyond the limits of 32-bit virtual addresses. Both process-private and system virtual address space now extend beyond 2 GB.

OpenVMS Alpha system services and many tools and languages supported by OpenVMS Alpha (including the Debugger, run-time library routines, and DEC C) support 64-bit virtual addressing. For more information about using these features in application programs, refer to the OpenVMS Alpha Guide to 64-Bit Addressing and VLM Features.

Intended Audience

This manual is intended for system and application programmers who use OpenVMS system routines and system services.

Document Structure

This manual contains four chapters and and two appendixes.

Chapter 1 discusses the way OpenVMS system routines are described in OpenVMS programming documentation and introduces the conventions used to code a procedure call to an OpenVMS system routine.

Chapter 2 summarizes the concepts and conventions of the OpenVMS Calling Standard that are relevant to most routine calls.

Chapter 3 describes how to call a routine of the OpenVMS Run-Time Library.

Chapter 4 describes how to call an OpenVMS system service.

Chapter 5 describes the libraries that contain C header files for routines and data structures supplied by the OpenVMS Alpha operating system.

Appendix A describes the generic macro format used by VAX MACRO programs to invoke and pass arguments to OpenVMS system services.

Appendix B describes the OpenVMS usage data types and how you can define the data types in various OpenVMS high-level languages.

Reader's Comments

Compaq welcomes your comments on this manual.

Print or edit the online form SYS$HELP:OPENVMSDOC_COMMENTS.TXT and send us your comments by:

Internet openvmsdoc@zko.mts.dec.com

Fax 603 884-0120, Attention: OSSG Documentation, ZKO3-4/U08

Mail Compaq Computer Corporation
OSSG Documentation Group, ZKO3-4/U08
110 Spit Brook Rd.
Nashua, NH 03062-2698

How To Order Additional Documentation

Use the following World Wide Web address to order additional documentation:

http://www.openvms.digital.com:81/

If you need help deciding which documentation best meets your needs, call 800-344-4825.

Conventions

The following conventions are used in this manual:

Ctrl/ x A sequence such as Ctrl/ x indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button.

PF1 x A sequence such as PF1 x indicates that you must first press and release the key labeled PF1 and then press and release another key or a pointing device button.

[Return] In examples, a key name enclosed in a box indicates that you press a key on the keyboard. (In text, a key name is not enclosed in a box.)
In the HTML version of this document, this convention appears as brackets, rather than a box.

... A horizontal ellipsis in examples indicates one of the following possibilities:

Additional optional arguments in a statement have been omitted.
The preceding item or items can be repeated one or more times.
Additional parameters, values, or other information can be entered.

.
.
. A vertical ellipsis indicates the omission of items from a code example or command format; the items are omitted because they are not important to the topic being discussed.

( ) In command format descriptions, parentheses indicate that you must enclose the options in parentheses if you choose more than one.

[ ] In command format descriptions, brackets indicate optional elements. You can choose one, none, or all of the options. (Brackets are not optional, however, in the syntax of a directory name in an OpenVMS file specification or in the syntax of a substring specification in an assignment statement.)

[|] In command format descriptions, vertical bars separating items inside brackets indicate that you choose one, none, or more than one of the options.

{ } In command format descriptions, braces indicate required elements; you must choose one of the options listed.

bold text This text style represents the introduction of a new term or the name of an argument, an attribute, or a reason.

italic text Italic text indicates important information, complete titles of manuals, or variables. Variables include information that varies in system output (Internal error number), in command lines (/PRODUCER= name), and in command parameters in text (where dd represents the predefined code for the device type).

UPPERCASE TEXT Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.

Monospace text Monospace type indicates code examples and interactive screen displays.
In the C programming language, monospace type in text identifies the following elements: keywords, the names of independently compiled external functions and files, syntax summaries, and references to variables or identifiers introduced in an example.

- A hyphen at the end of a command format description, command line, or code line indicates that the command or statement continues on the following line.

numbers All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated.

Chapter 1
Call Format to OpenVMS Routines

This chapter describes the format used to document system routine calls and explains where to find and how to interpret information about routine calls. Subsequent chapters provide more specific information about calling run-time library (RTL) routines and system services.

Note

The documentation format described in this chapter is generic; portions of it are used or not used, as appropriate, in the following OpenVMS manuals that document system routines:

OpenVMS System Services Reference Manual: A--GETMSG
OpenVMS System Services Reference Manual: GETQUI--Z
OpenVMS Run-Time Library manuals
OpenVMS Utility Routines Manual
OpenVMS Record Management Services Reference Manual

1.1 Overview

This chapter provides additional explanations for the following documentation categories for routines:

Format
Returns
Arguments
Condition values returned

However, some main categories in the routine format contain information requiring no explanation beyond that given in Table 1-1.

Table 1-1 Main Headings in the Documentation Format for System Routines
Main Heading Description

Routine Name Always present. The routine entry point name appears at the top of the first page. It is usually followed by the English text name of the routine.

Routine Overview Always present. Appears directly below the routine name and briefly explains what the routine does.

Format Always present. Follows the routine overview and gives the routine entry point name and the routine argument list.

Returns Always present. Follows the routine format and explains what information is returned by the routine.

Arguments Always present. Follows the Returns heading and gives detailed information about each argument. If a routine takes no arguments, the word None appears.

Description Optional. Follows the Arguments heading and contains information about specific actions taken by the routine: interaction between routine arguments, if any; operation of the routine within the context of OpenVMS; user privileges needed to call the routine, if any; system resources used by the routine; and user quotas that might affect the operation of the routine.
Note that any restrictions on the use of the routine are always discussed first in the Description section. For example, any required user privileges or necessary system resources are explained first.
For some simple routines, a Description section is not necessary because the routine overview provides the needed information.

Condition Values
Returned Always present. Follows the Description section and lists the condition values (typically status or completion codes) that are returned by the routine.

Example Optional. Follows the Condition Values Returned heading and contains one or more programming examples that illustrate how to use the routine, followed by an explanation.
All examples under this heading are complete. They have been tested and should run when compiled (or assembled) and linked. Throughout the manuals that document system routines, examples are provided in as many different programming languages as possible.

**Table 1-1 Main Headings in the Documentation Format for System Routines**
Main Heading	Description
Routine Name	Always present. The routine entry point name appears at the top of the first page. It is usually followed by the English text name of the routine.
Routine Overview	Always present. Appears directly below the routine name and briefly explains what the routine does.
Format	Always present. Follows the routine overview and gives the routine entry point name and the routine argument list.
Returns	Always present. Follows the routine format and explains what information is returned by the routine.
Arguments	Always present. Follows the Returns heading and gives detailed information about each argument. If a routine takes no arguments, the word None appears.
Description	Optional. Follows the Arguments heading and contains information about specific actions taken by the routine: interaction between routine arguments, if any; operation of the routine within the context of OpenVMS; user privileges needed to call the routine, if any; system resources used by the routine; and user quotas that might affect the operation of the routine. Note that any restrictions on the use of the routine are always discussed first in the Description section. For example, any required user privileges or necessary system resources are explained first. For some simple routines, a Description section is not necessary because the routine overview provides the needed information.
Condition Values Returned	Always present. Follows the Description section and lists the condition values (typically status or completion codes) that are returned by the routine.
Example	Optional. Follows the Condition Values Returned heading and contains one or more programming examples that illustrate how to use the routine, followed by an explanation. All examples under this heading are complete. They have been tested and should run when compiled (or assembled) and linked. Throughout the manuals that document system routines, examples are provided in as many different programming languages as possible.

1.2 Format Heading

The following three types of information can be present in the format heading:

Procedure call format
Explanatory text
Jump to Subroutine (JSB) format (VAX only)

On VAX processors, all system routines have a procedure call format, but few system routines have JSB formats. If a routine has a JSB format, the format always appears after the routine's procedure call format.

1.2.1 Procedure Call Format

Procedure call formats can appear in many forms. The following four formats illustrate the meaning of syntactical elements, such as brackets and commas. General rules of syntax governing how to use procedure call formats are shown in Table 1-2.

Table 1-2 General Rules of Syntax for Procedure Call Formats
Element Syntax Rule

Entry point names Entry point names are always shown in uppercase characters.

Argument names Argument names are always shown in lowercase characters.

Spaces One or more spaces are used between the entry point name and the first argument, and between each argument.

Braces ({}) Braces surround two or more arguments. You must choose one of the arguments.

Brackets ([]) Brackets surround optional arguments. Note that commas can also be optional (see the comma element). Note that programming language syntax for optional arguments differs between languages. Refer to your language user's guide for more information.

Commas (,) Between arguments, the comma always follows the space. If the argument is optional, the comma might appear either inside or outside the brackets, depending on the position of the argument in the list and on whether surrounding arguments are optional or required.

Null arguments A null argument is a placeholding argument. It is used for one of the following reasons: (1) to hold a place in the argument list for an argument that has not yet been implemented by Digital Equipment Corporation but might be in the future; or (2) to mark the position of an argument that was used in earlier versions of the routine but is not used in the latest version (upward compatibility is thereby ensured because arguments that follow the null argument in the argument list keep their original positions). A null argument is always given the name nullarg.
In the argument list constructed when a procedure is called, both null arguments and omitted optional arguments are represented by argument list entries containing the value 0. The programming language syntax required to produce argument list entries containing 0 differs from language to language. See your language user's guide for language-specific syntax.

**Table 1-2 General Rules of Syntax for Procedure Call Formats**
Element	Syntax Rule
Entry point names	Entry point names are always shown in uppercase characters.
Argument names	Argument names are always shown in lowercase characters.
Spaces	One or more spaces are used between the entry point name and the first argument, and between each argument.
Braces ({})	Braces surround two or more arguments. You must choose one of the arguments.
Brackets ([])	Brackets surround optional arguments. Note that commas can also be optional (see the comma element). Note that programming language syntax for optional arguments differs between languages. Refer to your language user's guide for more information.
Commas (,)	Between arguments, the comma always follows the space. If the argument is optional, the comma might appear either inside or outside the brackets, depending on the position of the argument in the list and on whether surrounding arguments are optional or required.
Null arguments	A null argument is a placeholding argument. It is used for one of the following reasons: (1) to hold a place in the argument list for an argument that has not yet been implemented by Digital Equipment Corporation but might be in the future; or (2) to mark the position of an argument that was used in earlier versions of the routine but is not used in the latest version (upward compatibility is thereby ensured because arguments that follow the null argument in the argument list keep their original positions). A null argument is always given the name nullarg. In the argument list constructed when a procedure is called, both null arguments and omitted optional arguments are represented by argument list entries containing the value 0. The programming language syntax required to produce argument list entries containing 0 differs from language to language. See your language user's guide for language-specific syntax.

Format 1

This format illustrates the standard representation of optional arguments and best describes the use of commas as delimiters. Arguments enclosed within square brackets are optional. In most languages, if an optional argument other than a trailing optional argument is omitted, you must include a comma as a delimiter for the omitted argument.

ROUTINE_NAME arg1[, [arg2][, arg3]]

Typically, OpenVMS RMS system routines use this format when a maximum of three arguments appear in the argument list.

Format 2

When the argument list contains three or more optional arguments, the syntax does not provide enough information. If you omit the optional arguments arg3 and arg4 and specify the trailing argument arg5, you must use commas to delimit the positions of the omitted arguments.

ROUTINE_NAME arg1, [arg2], nullarg, [arg3], [arg4], arg5

Typically, system services, utility routines, and run-time library routines contain call formats with more than three arguments.

Format 3

In the following call format, the trailing four arguments are optional as a group; that is, you specify either arg2, arg3, arg4, and arg5, or none of them. Therefore, if you do not specify the optional arguments, you need not use commas to delimit unoccupied positions.

However, if you specify a required argument or a separate optional argument after arg5, you must use commas when arg2, arg3, arg4, and arg5 are omitted.

ROUTINE_NAME arg1[, arg2, arg3, arg4, arg5]

Format 4

In the following example, you can specify arg2 and omit arg3. However, whenever you specify arg3, you must specify arg2.

ROUTINE_NAME arg1[, arg2[, arg3]]

1.2.2 JSB Call Format (VAX only)

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

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.

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

1.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 Alpha 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 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, 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, the mechanism heading is by value. (If the called routine had written the address of the condition value into R0, 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.

Contents

Index

privacy and legal statement

5843PRO.HTML

Internet	openvmsdoc@zko.mts.dec.com
Fax	603 884-0120, Attention: OSSG Documentation, ZKO3-4/U08
Mail	Compaq Computer Corporation OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698

Ctrl/ x	A sequence such as Ctrl/ x indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button.
PF1 x	A sequence such as PF1 x indicates that you must first press and release the key labeled PF1 and then press and release another key or a pointing device button.
`[Return]`	In examples, a key name enclosed in a box indicates that you press a key on the keyboard. (In text, a key name is not enclosed in a box.) In the HTML version of this document, this convention appears as brackets, rather than a box.
...	A horizontal ellipsis in examples indicates one of the following possibilities: Additional optional arguments in a statement have been omitted. The preceding item or items can be repeated one or more times. Additional parameters, values, or other information can be entered.
. . .	A vertical ellipsis indicates the omission of items from a code example or command format; the items are omitted because they are not important to the topic being discussed.
( )	In command format descriptions, parentheses indicate that you must enclose the options in parentheses if you choose more than one.
[ ]	In command format descriptions, brackets indicate optional elements. You can choose one, none, or all of the options. (Brackets are not optional, however, in the syntax of a directory name in an OpenVMS file specification or in the syntax of a substring specification in an assignment statement.)
[\|]	In command format descriptions, vertical bars separating items inside brackets indicate that you choose one, none, or more than one of the options.
{ }	In command format descriptions, braces indicate required elements; you must choose one of the options listed.
bold text	This text style represents the introduction of a new term or the name of an argument, an attribute, or a reason.
italic text	Italic text indicates important information, complete titles of manuals, or variables. Variables include information that varies in system output (Internal error number), in command lines (/PRODUCER= name), and in command parameters in text (where dd represents the predefined code for the device type).
UPPERCASE TEXT	Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.
Monospace text	Monospace type indicates code examples and interactive screen displays. In the C programming language, monospace type in text identifies the following elements: keywords, the names of independently compiled external functions and files, syntax summaries, and references to variables or identifiers introduced in an example.
-	A hyphen at the end of a command format description, command line, or code line indicates that the command or statement continues on the following line.
numbers	All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated.