HP OpenVMS Systems Documentation

OpenVMS Calling Standard

Order Number: AA--QSBBD--TE

April 2001

This standard defines the requirements, mechanisms, and conventions used in the OpenVMS interface that supports procedure-to-procedure calls for Alpha and VAX environments. The standard defines the run-time data structures, constants, algorithms, conventions, methods, and functional interfaces that enable a 32-bit or 64-bit native user-mode procedure to operate correctly in a multilanguage and multithreaded environment on Alpha and VAX processors.

Revision/Update Information: This manual supersedes the OpenVMS Calling Standard for OpenVMS Alpha Version 7.1 and OpenVMS VAX Version 7.1.

Software Version: OpenVMS Alpha Version 7.3 OpenVMS VAX Version 7.3

Compaq Computer Corporation Houston, Texas

Compaq, VAX, VMS, and the Compaq logo Registered in U.S. Patent and Trademark Office.

OpenVMS is a trademark of Compaq Information Technologies Group, L.P. in the United States and other countries.

All other product names mentioned herein may be trademarks of their respective companies.

Confidential computer software. Valid license from Compaq required for possession, use, or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license.

Compaq shall not be liable for technical or editorial errors or omissions contained herein. The information in this document is provided "as is" without warranty of any kind and is subject to change without notice. The warranties for Compaq products are set forth in the express limited warranty statements accompanying such products. Nothing herein should be construed as constituting an additional warranty.

ZK5973

The Compaq OpenVMS documentation set is available on CD-ROM.

Contents

Index

Preface

The OpenVMS Calling Standard defines the requirements, mechanisms, and conventions used in the OpenVMS interface that supports procedure-to-procedure calls for both Alpha and VAX environments. The standard defines the run-time data structures, constants, algorithms, conventions, methods, and functional interfaces that enable a native user-mode procedure to operate correctly in a multilanguage environment on Alpha and VAX systems. Properties of the run-time environment that must apply at various points during program execution are also defined.

The 32-bit user mode of the OpenVMS Alpha standard provides a high degree of compatibility with current programs written for the OpenVMS VAX environment.

The 64-bit user mode of the OpenVMS Alpha standard is a compatible superset of the OpenVMS Alpha 32-bit environment.

The interfaces, methods, and conventions specified in this manual are primarily intended for use by implementers of compilers, debuggers, and other run-time tools, run-time libraries, and base operating systems. These specifications may or may not be appropriate for use by higher level system software and applications.

This standard is under engineering change order (ECO) control. This manual includes all ECOs through ECO #48. ECOs are approved by Compaq's Calling Standard committee.

Intended Audience

This manual primarily defines requirements for compiler and debugger writers, but the information can apply to procedure calling for all programmers in various levels of programming.

Document Structure

This manual contains six chapters. Some chapters are restricted to either an Alpha or a VAX environment.

Chapter 1 provides an overview of the standard, defines goals, and defines terms used in the text.

Chapter 2 describes the primary conventions in calling a procedure in an OpenVMS VAX environment. It defines the VAX register usage and argument-passing list as well as vector and scalar processor synchronization.

Chapter 3 describes the fundamental concepts and conventions in calling a procedure in an OpenVMS Alpha environment. The chapter identifies the Alpha register usage and addressing, and focuses on aspects of the calling standard that pertain to procedure-to-procedure flow of control.

Chapter 4 defines the argument-passing data types used in calling a procedure for both OpenVMS Alpha and OpenVMS VAX environments.

Chapter 5 defines the argument descriptors used in calling a procedure for both OpenVMS Alpha and OpenVMS VAX environments.

Chapter 6 describes the OpenVMS condition- and exception-handling requirements for both OpenVMS Alpha and OpenVMS VAX environments.

Reader's Comments

Compaq welcomes your comments on this manual. Please send comments to either of the following addresses:

Internet	openvmsdoc@compaq.com
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.compaq.com

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

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 points in examples indicate 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 points indicate 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 choices in parentheses if you specify more than one.
[ ]	In command format descriptions, brackets indicate optional choices. You can choose one or more items or no items. Do not type the brackets on the command line. However, you must include the brackets in the syntax for OpenVMS directory specifications and for a substring specification in an assignment statement.
{ }	In command format descriptions, braces indicate required choices; you must choose at least one of the items listed. Do not type the braces on the command line.
bold text	This typeface 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
Introduction

This standard defines properties such as the run-time data structures, constants, algorithms, conventions, methods, and functional interfaces that enable a native user-mode procedure to operate correctly in a multilanguage and multithreaded environment on OpenVMS Alpha and OpenVMS VAX systems. These properties include the contents of key registers, format and contents of certain data structures, and actions that procedures must perform under certain circumstances.

This standard also defines properties of the run-time environment that must apply at various points during program execution. These properties vary in scope and applicability. Some properties apply at all points throughout the execution of standard-conforming user-mode code and must, therefore, be held constant at all times. Examples of such properties include those defined for the stack pointer and various properties of the call-chain navigation mechanism. Other properties apply only at certain points, such as call conventions that apply only at the point of transfer of control to another procedure.

Furthermore, some properties are optional depending on circumstances. For example, compilers are not obligated to follow the argument list conventions when a procedure and all of its callers are in the same module, have been analyzed by an interprocedural analyzer, or have private interfaces (such as language-support routines).

Note

In many cases, significant performance gains can be realized by selective use of nonstandard calls when the safety of such calls is known. Compiler or tools writers are encouraged to make full use of such optimizations.

The OpenVMS Alpha portion of this calling standard is intended to provide a calling standard that contains a high degree of compatibility with the OpenVMS VAX environment. Conventions that differ are, for the most part, those that are dictated by differences between the Alpha and VAX hardware architectures.

The procedure call mechanism depends on agreement between the calling and called procedures to interpret the argument list. The argument list does not fully describe itself. This standard requires language extensions to permit a calling program to generate some of the argument-passing mechanisms expected by called procedures.

This standard specifies the following attributes of the interfaces between modules:

Calling sequence---instructions at the call site, entry point, and returns
Argument list---structure of the list describing the arguments to the called procedure
Function value return---form and conventions for the return of the function value as a value or as a condition value to indicate success or failure
Register usage---which registers are preserved and who is responsible for preserving them
Stack usage---rules governing the use of the stack
Argument data types---data types of arguments that can be passed
Argument descriptor formats---how descriptors are passed for the more complex arguments
Condition handling---how exception conditions are signaled and how they are handled in a modular fashion
Stack unwinding---how the current thread of execution is aborted efficiently

1.1 Applicability

This standard defines the rules and conventions that govern the native user-mode run-time environment on Alpha and VAX processors. It is applicable to all products of Compaq Computer Corporation that execute in native user mode.

Uses of this standard include:

All externally callable interfaces in Compaq supported, standard system software
All intermodule calls to major software components
All external procedure calls generated by OpenVMS language processors without interprocedural analysis or permanent private conventions (such as those used for language-support run-time library [RTL] routines)

1.2 Architectural Level

This standard defines an implementation-level run-time software architecture for OpenVMS operating systems.

The interfaces, methods, and conventions specified in this document are primarily intended for use by implementers of compilers, debuggers, and other run-time tools, run-time libraries, and base operating systems. These specifications may or may not be appropriate for use by higher-level system software and applications.

Compilers and run-time libraries may provide additional support of these capabilities via interfaces that are more suited for compiler and application use. This specification neither prohibits nor requires such additional interfaces.

1.3 Goals

Generally, this calling standard promotes the highest degree of performance, portability, efficiency, and consistency in the interface between called procedures of a common OpenVMS environment. Specifically, the calling standard:

Applies to all intermodule callable interfaces in the native software system. Specifically, the standard considers the requirements of important compiled languages including Ada, BASIC, Bliss, C, C++, COBOL, FORTRAN, Pascal, LISP, PL/I, and calls to the operating system and library procedures. The needs of other languages that the OpenVMS operating system may support in the future must be met by the standard or by compatible revisions to it.
Excludes capabilities for lower-level components (such as assembler routines) that cannot be invoked from the high-level languages.
Allows the calling program and called procedure to be written in different languages. The standard reduces the need for using language extensions in mixed-language programs.
Contributes to the writing of error-free, modular, and maintainable software, and promotes effective sharing and reuse of software modules.
Provides the programmer with control over fixing, reporting, and flow of control when various types of exception conditions occur.
Provides subsystem and application writers with the ability to override system messages toward a more suitable application-oriented interface.
Adds no space or time overhead to procedure calls and returns that do not establish exception handlers, and minimizes time overhead for establishing handlers at the cost of increased time overhead when exceptions occur.

The OpenVMS Alpha portion of this standard:

Supports a 32-bit user-mode environment that provides a high degree of compatibility with the OpenVMS VAX environment.
Supports a 64-bit user-mode environment that is a compatible superset of the OpenVMS Alpha 32-bit environment.
Simplifies coexistence with VAX procedures that execute under the translated image environment.
Simplifies the compilation of VAX assembler source to native Alpha object code.
Supports a multilanguage, multithreaded execution environment, including efficient, effective support for the implementation of the multithread architecture (Compaq POSIX Threads Library¹).
Provides an efficient mechanism for calling lightweight procedures that do not need or cannot expend the overhead of setting up a stack call frame.
Provides for the use of a common calling sequence to invoke lightweight procedures that maintain only a register call frame and heavyweight procedures that maintain a stack call frame. This calling sequence allows a compiler to determine whether to use a stack frame based on the complexity of the procedure being compiled. A recompilation of a called routine that causes a change in stack frame usage does not require a recompilation of its callers.
Provides condition handling, traceback, and debugging for lightweight procedures that do not have a stack frame.
Makes efficient use of the Alpha architecture, including effectively using a larger number of registers than is contained in a conventional VAX processor.
Minimizes the cost of procedure calls.

The OpenVMS procedure calling mechanisms of this standard do not provide:

Checking of argument data types, data structures, and parameter access. The VAX and Alpha protection and memory management systems do not depend on correct interactions between user-level calling and called procedures. Such extended checking might be desirable in some circumstances, but system integrity does not depend on it.
Information for an interpretive OpenVMS Debugger. The definition of the debugger includes a debug symbol table (DST) that contains the required descriptive information.