HP OpenVMS Programming Concepts Manual, Volume II Order Number: AA–PV67H–TK January 2005 This manual is Volume II of two volumes. It describes the features that the HP OpenVMS operating system provides to programmers. Revision/Update Information: This manual supersedes the HP OpenVMS Programming Concepts Manual, Version 7.3-1. Software Version: OpenVMS I64 Version 8.2 OpenVMS Alpha Version 8.2 Hewlett Packard Company Palo Alto, California © 2005 Hewlett-Packard Development Company, L.P. Confidential computer software. Valid license from HP 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. The information contained herein is subject to change without notice. The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein. Microsoft, Windows, and Windows NT are U.S. registered trademarks of Microsoft Corporation. UNIX is a registered trademark of The Open Group. X/Open is a registered trademark, and the X device is a trademark of X/Open Company Ltd. in the UK and other countries. Intel and Itanium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries. Printed in the U.S. ZK6641 The HP OpenVMS documentation set is available on CD-ROM. This document was prepared using DECdocument, Version 3.3-1b. Contents Preface ............................................................ xxi Part I OpenVMS Programming Interfaces: Calling a System Routine 17 Call Format to OpenVMS Routines 17.1 Overview . ................................................ 17–1 17.2 Format Heading ............................................. 17–2 17.2.1 Procedure Call Format ..................................... 17–3 17.2.2 JSB Call Format (VAX only) ................................ 17–4 17.3 Returns Heading ............................................ 17–4 17.3.1 Condition Values Returned in a Register ....................... 17–4 17.3.2 Other Returned Values .................................... 17–5 17.3.3 Condition Values Signaled . ................................ 17–6 17.4 Arguments Heading . ........................................ 17–6 17.4.1 OpenVMS Usage Entry .................................... 17–6 17.4.2 Type Entry .............................................. 17–7 17.4.3 Access Entry ............................................ 17–9 17.4.4 Mechanism Entry . ........................................ 17–10 17.4.5 Explanatory Text . ........................................ 17–10 17.5 Condition Values Returned Heading ............................. 17–11 17.5.1 Condition Values Returned . ................................ 17–12 17.5.2 Condition Values Returned in an I/O Status Block ............... 17–12 17.5.3 Condition Values Returned in a Mailbox ....................... 17–13 17.5.4 Condition Values Signaled . ................................ 17–13 18 Basic Calling Standard Conventions 18.1 Hardware Registers . ........................................ 18–1 18.1.1 Register Usage for OpenVMS VAX ............................ 18–1 18.1.2 Register Usage for OpenVMS Alpha . ....................... 18–2 18.1.2.1 Integer Registers ...................................... 18–2 18.1.2.2 Floating-Point Registers . ................................ 18–3 18.1.3 Register Usage for OpenVMS I64 ............................ 18–3 18.1.3.1 Partitioning . ........................................ 18–4 18.1.3.2 I64 General Register Usage .............................. 18–4 18.1.3.3 I64 Floating-Point Register Usage . ....................... 18–7 18.1.3.4 I64 Predicate Register Usage ............................. 18–7 18.1.3.5 I64 Branch Register Usage .............................. 18–8 18.2 Stack Usage for Procedures .................................... 18–8 18.2.1 Stack Procedure Usage for VAX .............................. 18–8 18.2.1.1 Calling Sequence ...................................... 18–10 18.2.1.2 Call Frames on Return . ................................ 18–10 iii 18.2.2 Stack Procedure Usage for Alpha . ............................ 18–10 18.2.2.1 Fixed-Size Stack Frame ................................. 18–10 18.2.2.2 Variable-Size Stack Frame . ............................ 18–11 18.2.3 Stack Procedure Usage for I64 . ............................ 18–13 18.2.3.1 Procedure Types . .................................... 18–14 18.2.3.2 Memory Stack ........................................ 18–15 18.2.3.3 Procedure Frames . .................................... 18–15 18.2.3.4 Register Stack ........................................ 18–17 18.2.3.4.1 Input and Local Registers ............................ 18–17 18.2.3.4.2 Output Registers ................................... 18–18 18.2.3.4.3 Rotating Registers .................................. 18–18 18.2.3.4.4 Frame Markers .................................... 18–19 18.2.3.4.5 Backing Store for Register Stack ....................... 18–19 18.3 Procedure Representation . .................................... 18–20 18.4 Argument List . ............................................ 18–20 18.5 Argument Passing Mechanisms ................................. 18–24 18.5.1 Passing Arguments by Value ................................ 18–27 18.5.2 Passing Arguments by Reference . ............................ 18–27 18.5.3 Passing Arguments by Descriptor ............................ 18–29 18.5.4 Parameter Passing Mechanisms for I64 ........................ 18–31 18.5.4.1 Allocation of Parameter Slots . ............................ 18–31 18.5.5 Normal Register Parameters ................................ 18–32 18.5.6 Argument Information (AI) Register .......................... 18–34 18.5.7 Memory Stack Parameters .................................. 18–36 18.5.8 Variable Argument Lists ................................... 18–36 18.5.9 Pointers to Formal Parameters . ............................ 18–36 18.5.9.1 Languages Other than C ................................ 18–37 18.5.10 Rounding Floating-Point Values . ............................ 18–37 18.6 Passing Scalars as Arguments .................................. 18–37 18.7 Passing Arrays as Arguments .................................. 18–37 18.8 Passing Strings as Arguments .................................. 18–37 18.9 Combinations of Descriptor Class and Data Type ................... 18–38 18.10 Function Value Return ........................................ 18–41 18.11 Condition Value Return . .................................... 18–42 18.12 Macro-32 Register Usage and Mapping for I64 . ................... 18–43 18.12.1 I64 Register Usage Compared with Alpha and VAX . ........... 18–43 18.12.1.1 I64 Register Mapping in MACRO Compiler .................. 18–44 18.12.1.2 Use of MACRO Linkage Directives to Preserve Registers ....... 18–46 18.12.2 High-Level Language Compiler Register Mapping ................ 18–47 19 Calling Run-Time Library Routines 19.1 Overview .................................................. 19–1 19.2 Call Instructions ............................................ 19–3 19.2.1 Facility Prefix and Routine Name ............................ 19–3 19.2.2 The RTL Call Entry . .................................... 19–4 19.2.2.1 JSB Call Entries (VAX Only) . ............................ 19–6 19.2.3 Returns from an RTL Routine . ............................ 19–6 19.2.3.1 Facility Return Status and Condition Value Symbols .......... 19–6 19.3 Calling a Library Procedure in VAX MACRO (VAX Only) . ........... 19–7 19.3.1 VAX MACRO Calling Sequence . ............................ 19–7 19.3.2 VAX MACRO CALLS Instruction Example . ................... 19–8 19.3.3 VAX MACRO CALLG Instruction Example . ................... 19–9 19.3.4 VAX MACRO JSB Entry Points . ............................ 19–9 iv 19.3.5 Return Status . ........................................ 19–10 19.3.6 Function Return Values in VAX MACRO (VAX and Alpha) . ....... 19–11 19.4 Calling a Library Routine in BLISS .............................. 19–12 19.4.1 BLISS Calling Sequence . ................................ 19–12 19.4.2 Accessing a Return Status in BLISS . ....................... 19–13 19.4.3 Calling JSB Entry Points from BLISS . ....................... 19–13 20 Calling System Services 20.1 Overview . ................................................ 20–1 20.2 Preserving System Integrity . ................................ 20–2 20.2.1 User Privileges . ........................................ 20–2 20.2.2 Resource Quotas . ........................................ 20–2 20.2.3 Access Modes ............................................ 20–2 20.3 System Service Call Entry ..................................... 20–3 20.4 System Service Completion .................................... 20–5 20.4.1 Asynchronous and Synchronous System Services . ............... 20–5 20.4.2 System Service Resource Wait Mode . ....................... 20–6 20.4.3 Condition Values Returned from System Services . ............... 20–7 20.4.4 Testing the Condition Value . ................................ 20–8 20.4.4.1 Testing the Condition Value With $VMS_STATUS_SUCCESS Macro ............................................... 20–8 20.4.5 Special Condition Values