Openvms Programming Concepts Manual, Vol. 2
Total Page:16
File Type:pdf, Size:1020Kb
OpenVMS Programming Concepts Manual, Volume II Order Number: AA–PV67E–TK April 2001 This manual is volume two of two volumes. It describes the features that the OpenVMS operating system provides to programmers. Revision/Update Information: This manual supersedes the OpenVMS Programming Concepts Manual, Version 7.2. Software Version: OpenVMS Alpha Version 7.3 OpenVMS VAX Version 7.3 Compaq Computer Corporation Houston, Texas © 2001 Compaq Computer Corporation Compaq, AlphaServer, VAX, VMS, and the Compaq logo Registered in U.S. Patent and Trademark Office. Alpha, OpenVMS, PATHWORKS, DECnet, and DEC are trademarks of Compaq Information Technologies Group, L.P. in the United States and other countries. UNIX and X/Open are trademarks of The Open Group 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. Printed in the U.S.A. ZK6641 The Compaq OpenVMS documentation set is available on CD–ROM. Contents Preface ............................................................ xvii 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–8 17.4.4 Mechanism Entry . ........................................ 17–9 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–12 17.5.4 Condition Values Signaled . ................................ 17–12 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.2 Stack Usage for Procedures .................................... 18–3 18.2.1 Stack Procedure Usage for VAX .............................. 18–3 18.2.1.1 Calling Sequence ...................................... 18–5 18.2.1.2 Call Frames on Return . ................................ 18–5 18.2.2 Stack Procedure Usage for Alpha ............................. 18–5 18.2.2.1 Fixed-Size Stack Frame . ................................ 18–5 18.2.2.2 Variable-Size Stack Frame ............................... 18–6 18.3 Procedure Representation ..................................... 18–8 18.4 Argument List .............................................. 18–9 18.5 Argument Passing Mechanisms . ................................ 18–11 18.5.1 Passing Arguments by Value ................................ 18–13 iii 18.5.2 Passing Arguments by Reference . ............................ 18–14 18.5.3 Passing Arguments by Descriptor ............................ 18–16 18.6 Passing Scalars as Arguments .................................. 18–18 18.7 Passing Arrays as Arguments .................................. 18–18 18.8 Passing Strings as Arguments .................................. 18–18 18.9 Combinations of Descriptor Class and Data Type ................... 18–19 18.10 Return of the Function Value ................................... 18–22 18.11 Return of the Condition Value .................................. 18–22 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–8 19.3.4 VAX MACRO JSB Entry Points . ............................ 19–9 19.3.5 Return Status ........................................... 19–10 19.3.6 Function Return Values in VAX MACRO ....................... 19–11 19.4 Calling a Library Routine in BLISS . ............................ 19–11 19.4.1 BLISS Calling Sequence ................................... 19–12 19.4.2 Accessing a Return Status in BLISS .......................... 19–12 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.5 Special Condition Values Using Symbolic Codes ................. 20–8 20.4.6 Testing the Return Condition Value for Assembly Languages ....... 20–9 20.4.7 System Messages Generated by Condition Values ................ 20–10 20.5 Program Examples with System Service Calls . ................... 20–11 iv 21 STARLET Structures and Definitions for C Programmers 21.1 SYS$STARLET_C.TLB Equivalency to STARLETSD.TLB ............. 21–1 21.2 NEW STARLET Definitions for C ............................... 21–2 Part II I/O, System and Programming Routines 22 Run-Time Library Input/Output Operations 22.1 Choosing I/O Techniques ...................................... 22–1 22.2 Using SYS$INPUT and SYS$OUTPUT ........................... 22–3 22.2.1 Default Input and Output Devices............................ 22–3 22.2.2 Reading and Writing to Alternate Devices and External Files ....... 22–4 22.3 Working with Simple User I/O . ................................ 22–4 22.3.1 Default Devices for Simple I/O ............................... 22–4 22.3.2 Getting a Line of Input .................................... 22–4 22.3.3 Getting Several Lines of Input ............................... 22–5 22.3.4 Writing Simple Output ..................................... 22–6 22.4 Working with Complex User I/O ................................ 22–7 22.4.1 Compaq DECwindows Motif . ................................ 22–7 22.4.1.1 DECwindows Server Height or Width Exceeding 32767 (VAX Only) ............................................... 22–8 22.4.1.2 SET DISPLAY Used to Create WSA Pseudo Workstation Devices .............................................. 22–8 22.4.2 SMG$ Run-Time Routines . ................................ 22–9 22.4.3 Pasteboards ............................................. 22–10 22.4.3.1 Erasing a Pasteboard . ................................ 22–11 22.4.3.2 Deleting a Pasteboard . ................................ 22–11 22.4.3.3 Setting Screen Dimensions and Background Color ............ 22–11 22.4.4 Virtual Displays . ........................................ 22–12 22.4.4.1 Creating a Virtual Display ............................... 22–12 22.4.4.2 Pasting Virtual Displays ................................ 22–13 22.4.4.3 Rearranging Virtual Displays ............................ 22–15 22.4.4.4 Removing Virtual Displays ..............................