HP OpenVMS ProgrammingConceptsManual,Volume IOrder Number: AARNSHDTE

January 2005

This manual is Volume I of two volumes. It describes the features thatthe HP OpenVMS operating system provides to programmers in theareas of process and synchronization; interrupts and condition handling;and addressing and memory management.

Revision/Update Information: This manual supersedes the HPOpenVMS Programming ConceptsManual, Version 7.3-1.

Software Version: OpenVMS I64 Version 8.2OpenVMS Alpha Version 8.2

Hewlett Packard CompanyPalo Alto, California

Copyright 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 SoftwareDocumentation, and Technical Data for Commercial Items are licensed to the U.S. Governmentunder vendors standard commercial license.

The information contained herein is subject to change without notice. The only warranties for HPproducts and services are set forth in the express warranty statements accompanying such productsand services. Nothing herein should be construed as constituting an additional warranty. HP shallnot be liable for technical or editorial errors or omissions contained herein.

Intel and Itanium are trademarks or registered trademarks of Intel Corporation or its subsidiariesin the United States and other countries.

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 theUK and other countries.

Printed in the US

ZK6640

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

This document was prepared using DECdocument, Version 3.3-1b.

Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix

1 Overview of Manuals and Introduction to Development on OpenVMSSystems

1.1 Overview of the Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111.2 Overview of the OpenVMS Operating System . . . . . . . . . . . . . . . . . . . . . . 121.3 Components of the OpenVMS Operating System . . . . . . . . . . . . . . . . . . . . 131.3.1 OpenVMS Systems on Multiple Platforms . . . . . . . . . . . . . . . . . . . . . . 141.3.1.1 System Compatibility and Program Portability Across

Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141.3.2 OpenVMS Computing Environments . . . . . . . . . . . . . . . . . . . . . . . . . . 141.3.2.1 Open System Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141.3.2.2 Application Portability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151.3.2.2.1 Other Application Portability Features . . . . . . . . . . . . . . . . . . 151.3.3 Distributed Computing Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . 151.3.3.1 Client/Server Style of Computing . . . . . . . . . . . . . . . . . . . . . . . . . . 151.3.3.2 OpenVMS Client/Server Capabilities . . . . . . . . . . . . . . . . . . . . . . . 161.4 The OpenVMS Programming Environment . . . . . . . . . . . . . . . . . . . . . . . . 161.4.1 Programming to Standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181.4.1.1 Common Environment for Writing Code . . . . . . . . . . . . . . . . . . . . 181.4.1.2 Common Language Environment . . . . . . . . . . . . . . . . . . . . . . . . . . 181.5 OpenVMS Programming Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181.5.1 Creating Program Source Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191.5.2 Creating Object Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1101.5.3 Creating Runnable Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1111.5.4 Testing and Debugging Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1111.5.4.1 Special Modes of Operation for Debugging . . . . . . . . . . . . . . . . . . . 1131.5.5 Using Other Program Development Utilities . . . . . . . . . . . . . . . . . . . . 1131.5.6 Managing Software Development Tasks . . . . . . . . . . . . . . . . . . . . . . . . 1141.6 Using Callable System Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1141.6.1 Using the POSIX Threads Library Routines . . . . . . . . . . . . . . . . . . . . 1141.6.2 Using OpenVMS Run-Time Library Routines . . . . . . . . . . . . . . . . . . . 1151.6.3 Using OpenVMS System Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1161.6.4 Using OpenVMS Utility Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1171.7 Programming User Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1181.8 Optional HP Software Development Tools . . . . . . . . . . . . . . . . . . . . . . . . . 1191.9 Managing Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1191.9.1 RMS Files and Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1191.9.2 RMS Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

iii

Part I Process and Synchronization

2 Process Creation2.1 Process Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212.2 Execution Context of a Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.3 Modes of Execution of a Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.4 Creating a Subprocess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232.4.1 Naming a Spawned Subprocess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232.4.2 Using LIB$SPAWN to Create a Spawned Subprocess . . . . . . . . . . . . . 242.4.3 Using the C system( ) Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272.4.4 Using SYS$CREPRC to Create a Subprocess . . . . . . . . . . . . . . . . . . . 272.4.4.1 Disk and Directory Defaults for Created Processes . . . . . . . . . . . . 2132.5 Creating a Detached Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2132.6 Process Quota Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2142.7 Debugging a Subprocess or a Detached Process . . . . . . . . . . . . . . . . . . . . . 2152.8 Kernel Threads and the Kernel Threads Process Structure (Alpha and I64

Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2172.8.1 Definition and Advantages of Kernel Threads . . . . . . . . . . . . . . . . . . . 2182.8.2 Kernel Threads Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2182.8.2.1 Multiple Execution Contexts Within a Process . . . . . . . . . . . . . . . . 2182.8.2.2 Efficient Use of the OpenVMS and POSIX Threads Library

Schedulers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2192.8.2.3 Terminating a POSIX Threads Image . . . . . . . . . . . . . . . . . . . . . . 2192.8.3 Kernel Threads Model and Design Features . . . . . . . . . . . . . . . . . . . . 2202.8.3.1 Kernel Threads Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2202.8.3.2 Kernel Threads Design Features . . . . . . . . . . . . . . . . . . . . . . . . . . 2202.8.3.2.1 Process Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2202.8.3.2.2 Access to Inner Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2202.8.3.2.3 Scheduling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2212.8.3.2.4 ASTs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2212.8.3.2.5 Event Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2212.8.3.2.6 Process Control Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2212.8.4 Kernel Threads Process Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2212.8.4.1 Process Control Block (PCB) and Process Header (PHD) . . . . . . . . 2212.8.4.1.1 Effect of a Multithreaded Process on the PCB and PHD . . . . . 2222.8.4.2 Kernel Thread Block (KTB) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2222.8.4.3 Floating-Point Registers and Execution Data Blocks (FREDs) . . . . 2232.8.4.4 Kernel Threads Region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2232.8.4.5 Per-Kernel Thread Stacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2232.8.4.6 Per-Kernel-Thread Data Cells . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2242.8.4.7 Summary of Process Data Structures . . . . . . . . . . . . . . . . . . . . . . 2242.8.4.8 Kernel Thread Priorities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2242.9 THREADCP Command Not Supported on OpenVMS I64 . . . . . . . . . . . . . 2252.10 KPS Services (Alpha and I64 only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225

3 Process Communication3.1 Communication Within a Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313.1.1 Using Local Event Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323.1.2 Using Logical Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323.1.2.1 Creating and Accessing Logical Names . . . . . . . . . . . . . . . . . . . . . 32

iv

3.1.3 Using Command Language Interpreter Symbols . . . . . . . . . . . . . . . . . 353.1.3.1 Local and Global Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353.1.3.2 Creating and Using Global Symbols . . . . . . . . . . . . . . . . . . . . . . . . 353.1.4 Using the Common Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363.1.4.1 Creating the Process Common Area . . . . . . . . . . . . . . . . . . . . . . . . 363.1.4.2 Common I/O Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363.1.4.3 Modifying or Deleting Data in the Common Block . . . . . . . . . . . . . 363.1.4.4 Specifying Other Types of Data . . . . . . . . . . . . . . . . . . . . . . . . . . . 363.2 Communication Between Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373.2.1 Using Logical Name Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383.2.2 Mailboxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393.2.2.1 Creating a Mailbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393.2.2.2 Creating Temporary and Permanent Mailboxes . . . . . . . . . . . . . . . 393.2.2.3 Assigning an I/O Channel Along with a Mailbox . . . . . . . . . . . . . . 3103.2.2.4 Reading and Writing Data to a Mailbox . . . . . . . . . . . . . . . . . . . . . 3113.2.2.5 Using Synchronous Mailbox I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . 3123.2.2.6 Using Immediate Mailbox I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3143.2.2.7 Using Asynchronous Mailbox I/O . . . . . . . . . . . . . . . . . . . . . . . . . . 3183.3 Intracluster Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3213.3.1 Programming with Intracluster Communications . . . . . . . . . . . . . . . . 3223.3.1.1 ICC Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3223.3.1.2 Design Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3233.3.1.2.1 Naming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3233.3.1.2.2 Message Ordering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3233.3.1.2.3 Flow Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3233.3.1.2.4 Transfer Sizes and Receiving Data . . . . . . . . . . . . . . . . . . . . . . 3233.3.1.2.5 Transfer Sizes and Transceive . . . . . . . . . . . . . . . . . . . . . . . . . 3243.3.1.2.6 Disconnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3243.3.1.2.7 Error Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3253.3.1.3 General Programming Considerations . . . . . . . . . . . . . . . . . . . . . . 3253.3.1.4 Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3253.3.1.4.1 Connection Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3263.3.1.4.2 Disconnection Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3263.3.1.5 Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327

4 Process Control4.1 Using Process Control for Programming Tasks . . . . . . . . . . . . . . . . . . . . . 414.1.1 Determining Privileges for Process Creation and Control . . . . . . . . . . 434.1.2 Determining Process Identification . . . . . . . . . . . . . . . . . . . . . . . . . . . 434.1.3 Qualifying Process Naming Within Groups . . . . . . . . . . . . . . . . . . . . . 454.2 Obtaining Process Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454.2.1 Using the PID to Obtain Information . . . . . . . . . . . . . . . . . . . . . . . . . 464.2.2 Using the Process Name to Obtain Information . . . . . . . . . . . . . . . . . . 464.2.3 Using SYS$GETJPI and LIB$GETJPI . . . . . . . . . . . . . . . . . . . . . . . . . 494.2.3.1 Requesting Information About a Single Process . . . . . . . . . . . . . . . 494.2.3.2 Requesting Information About All Processes on the Local

System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4124.2.4 Using SYS$GETJPI with SYS$PROCESS_SCAN . . . . . . . . . . . . . . . . 4144.2.4.1 Using SYS$PROCESS_SCAN Item List and Item-Specific

Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4164.2.4.2 Requesting Information About Processes That Match One

Criterion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417

v

4.2.4.3 Requesting Information About Processes That Match MultipleValues for One Criterion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420

4.2.4.4 Requesting Information About Processes That Match MultipleCriteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421

4.2.5 Specifying a Node as Selection Criterion . . . . . . . . . . . . . . . . . . . . . . . 4214.2.5.1 Checking All Nodes on the Cluster for Processes . . . . . . . . . . . . . . 4224.2.5.2 Checking Specific Nodes on the Cluster for Processes . . . . . . . . . . 4224.2.5.3 Conducting Multiple Simultaneous Searches with

SYS$PROCESS_SCAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4234.2.6 Programming with SYS$GETJPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4244.2.6.1 Using Item Lists Correctly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4244.2.6.2 Improving Performance by Using Buffered $GETJPI

Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4244.2.6.3 Fulfilling Remote SYS$GETJPI Quota Requirements . . . . . . . . . . 4254.2.6.4 Using the SYS$GETJPI Control Flags . . . . . . . . . . . . . . . . . . . . . . 4264.2.7 Using SYS$GETLKI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4304.2.8 Setting Process Privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4314.3 Changing Process and Kernel Threads Scheduling . . . . . . . . . . . . . . . . . . 4324.4 Using Affinity and Capabilities in CPU Scheduling (Alpha and I64

Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4324.4.1 Defining Affinity and Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4334.4.1.1 Using Affinity and Capabilities with Caution . . . . . . . . . . . . . . . . 4334.4.2 Types of Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4334.4.3 Looking at User Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4344.4.4 Using the Capabilities System Services . . . . . . . . . . . . . . . . . . . . . . . . 4344.4.5 Types of Affinity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4354.4.5.1 Implicit Affinity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4354.4.5.2 Explicit Affinity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4364.5 Using the Class Scheduler in CPU Scheduling . . . . . . . . . . . . . . . . . . . . . 4364.5.1 Specifications for the Class_Schedule Command . . . . . . . . . . . . . . . . . 4374.5.1.1 The Add Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4374.5.1.2 The Delete Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4384.5.1.3 The Modify Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4384.5.1.4 The Show Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4394.5.1.5 The Suspend Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4394.5.1.6 The Resume Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4394.5.2 The Class Scheduler Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4404.5.2.1 The Class Scheduler Database and Process Creation . . . . . . . . . . . 4404.5.3 Determining If a Process Is Class Scheduled . . . . . . . . . . . . . . . . . . . . 4404.5.4 The SYS$SCHED System Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4414.6 Changing Process Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4414.7 Accessing Another Processs Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4424.7.1 Reading and Writing in the Address Space of Another Process (Alpha

and I64 Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4424.7.1.1 EXE$READ_PROCESS and EXE$WRITE_PROCESS . . . . . . . . . . 442

EXE$READ_PROCESS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443EXE$WRITE_PROCESS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446

4.7.2 Writing an Executive Image (Alpha and I64 Only) . . . . . . . . . . . . . . . 4494.7.2.1 INITIALIZATION_ROUTINE Macro (Alpha and I64 Only) . . . . . . 451

INITIALIZATION_ROUTINE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4514.7.2.2 Linking an Executive Image (Alpha or I64 Only) . . . . . . . . . . . . . . 4524.7.2.3 Loading an Executive Image (Alpha or I64 Only) . . . . . . . . . . . . . 4524.7.2.4 LDR$LOAD_IMAGE (Alpha or I64 Only) . . . . . . . . . . . . . . . . . . . 453

LDR$LOAD_IMAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453

vi

4.7.2.5 LDR$UNLOAD_IMAGE (Alpha or I64 Only) . . . . . . . . . . . . . . . . . 457LDR$UNLOAD_IMAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457

4.8 Synchronizing Programs by Specifying a Time for Program Execution . . . 4594.8.1 Obtaining the System Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4594.8.1.1 Executing a Program at a Specified Time . . . . . . . . . . . . . . . . . . . 4604.8.1.2 Executing a Program at Timed Intervals . . . . . . . . . . . . . . . . . . . . 4614.8.2 Placing Entries in the System Timer Queue . . . . . . . . . . . . . . . . . . . . 4624.9 Controlling Kernel Threads and Process Execution . . . . . . . . . . . . . . . . . . 4634.9.1 Process Hibernation and Suspension . . . . . . . . . . . . . . . . . . . . . . . . . . 4634.9.1.1 Using Process Hibernation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4654.9.1.2 Using Alternative Methods of Hibernation . . . . . . . . . . . . . . . . . . . 4664.9.1.3 Using SYS$SUSPND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4674.9.2 Passing Control to Another Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4674.9.2.1 Invoking a Command Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4674.9.2.2 Invoking a Noncommand Image . . . . . . . . . . . . . . . . . . . . . . . . . . . 4684.9.3 Performing Image Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4684.9.3.1 Performing Image Rundown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4694.9.3.2 Initiating Rundown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4694.9.3.3 Performing Cleanup and Rundown Operations . . . . . . . . . . . . . . . 4704.9.3.4 Initiating Image Rundown for Another Process . . . . . . . . . . . . . . . 4704.9.4 Deleting a Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4714.9.4.1 Deleting a Process By Using System Services . . . . . . . . . . . . . . . . 4744.9.4.2 $DELPRC System Service Can Invoke Exit Handlers (Alpha and

I64 only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4744.9.4.3 Terminating Mailboxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476

5 Symmetric Multiprocessing (SMP) Systems5.1 Introduction to Symmetric Multiprocessing . . . . . . . . . . . . . . . . . . . . . . . . 515.2 CPU Characteristics of an SMP System . . . . . . . . . . . . . . . . . . . . . . . . . . . 515.2.1 Booting an SMP System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 515.2.2 Interrupt Requests on SMP System . . . . . . . . . . . . . . . . . . . . . . . . . . . 525.3 Symmetric Multiprocessing Goals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

6 Synchronizing Data Access and Program Operations6.1 Overview of Synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 616.1.1 Threads of Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 626.1.2 Atomicity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636.2 Memory Read and Memory Write Operations for VAX and Alpha . . . . . . . 636.2.1 Accessing Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636.2.2 Ordering of Read and Write Operations . . . . . . . . . . . . . . . . . . . . . . . . 656.2.3 Memory Reads and Memory Writes . . . . . . . . . . . . . . . . . . . . . . . . . . . 656.3 Memory Read and Memory Write Operations for I64 Systems . . . . . . . . . . 656.3.1 Atomic Semaphore Instructions on I64 . . . . . . . . . . . . . . . . . . . . . . . . 656.3.2 Accessing Memory on I64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666.3.3 Ordering of Read and Write Operations for I64 Systems . . . . . . . . . . . 666.4 Memory Read-Modify-Write Operations for VAX and Alpha . . . . . . . . . . . . 666.4.1 Uniprocessor Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666.4.2 Multiprocessor Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676.5 Memory Read-Modify-Write Operations for I64 Systems . . . . . . . . . . . . . . 686.5.1 Preserving Atomicity with MACRO-32 . . . . . . . . . . . . . . . . . . . . . . . . . 686.6 Synchronization Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 696.6.1 Interrupt Priority Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 610

vii

6.6.2 LDx_L and STx_C Instructions (Alpha Only) . . . . . . . . . . . . . . . . . . . . 6106.6.3 Interlocking Memory References (Alpha Only) . . . . . . . . . . . . . . . . . . . 6116.6.3.1 Required Code Checks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6126.6.3.2 Using the Code Analysis Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6126.6.3.3 Characteristics of Noncompliant Code . . . . . . . . . . . . . . . . . . . . . . 6136.6.3.4 Coding Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6146.6.3.5 Compiler Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6156.6.3.6 Interlocked Memory Sequence Checking for the MACRO32

Compiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6166.6.3.7 Recompiling Code with ALONONPAGED_INLINE or

LAL_REMOVE_FIRST Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . 6176.6.4 Interlocked Instructions (VAX Only) . . . . . . . . . . . . . . . . . . . . . . . . . . 6176.6.5 Memory Barriers (Alpha Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6186.6.6 Memory Fences (I64 Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6196.6.7 PALcode Routines (Alpha Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6196.6.8 I64 Emulation of PALcode Built-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . 6196.7 Software-Level Synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6196.7.1 Synchronization Within a Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6206.7.2 Synchronization in Inner Mode (Alpha and I64 Only) . . . . . . . . . . . . . 6206.7.3 Synchronization Using Process Priority . . . . . . . . . . . . . . . . . . . . . . . . 6216.7.4 Synchronizing Multiprocess Applications . . . . . . . . . . . . . . . . . . . . . . . 6216.7.5 Synchronization Using Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6226.7.6 Writable Global Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6226.8 Using Event Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6236.8.1 General Guidelines for Using Event Flags . . . . . . . . . . . . . . . . . . . . . . 6236.8.2 Introducing Local and Common Event Flag Numbers and Event Flag

Clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6246.8.3 Using Event Flag Zero (0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6266.8.4 Using EFN$C_ENF Local Event Flag . . . . . . . . . . . . . . . . . . . . . . . . . 6266.8.5 Using Local Event Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6266.8.5.1 Example of Event Flag Services . . . . . . . . . . . . . . . . . . . . . . . . . . . 6276.8.6 Using Common Event Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6286.8.6.1 Using the name Argument with SYS$ASCEFC . . . . . . . . . . . . . . 6296.8.6.2 Temporary Common Event Flag Clusters . . . . . . . . . . . . . . . . . . . 6306.8.6.3 Permanent Common Event Flag Clusters . . . . . . . . . . . . . . . . . . . 6306.8.7 Wait Form Services and SYS$SYNCH . . . . . . . . . . . . . . . . . . . . . . . . . 6326.8.8 Event Flag Waits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6326.8.9 Setting and Clearing Event Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6346.8.10 Example of Using a Common Event Flag Cluster . . . . . . . . . . . . . . . . 6346.8.11 Example of Using Event Flag Routines and Services . . . . . . . . . . . . . . 6366.9 Synchronizing System Services Operations . . . . . . . . . . . . . . . . . . . . . . . . 638

7 Synchronizing Access to Resources7.1 Synchronizing Operations with the Lock Manager . . . . . . . . . . . . . . . . . . . 717.2 Concepts of Resources and Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 727.2.1 Resource Granularity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 737.2.2 Resource Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 747.2.3 Resource Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 747.2.4 Choosing a Lock Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 757.2.5 Levels of Locking and Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . 757.2.6 Lock Management Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 767.2.7 Concepts of Lock Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 777.2.8 Deadlock Detection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

viii

7.2.9 Lock Quotas and Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 787.2.9.1 Enqueue Limit Quota (ENQLM) . . . . . . . . . . . . . . . . . . . . . . . . . . 797.2.9.2 Subresources and Sublocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797.2.9.3 Resource Hash Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797.2.9.4 LOCKIDTBL System Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . 797.3 Queuing Lock Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797.3.1 Example of Requesting a Null Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . 7107.4 Advanced Locking Techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7117.4.1 Synchronizing Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7117.4.2 Notification of Synchronous Completion . . . . . . . . . . . . . . . . . . . . . . . . 7127.4.3 Expediting Lock Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7127.4.4 Lock Status Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7127.4.5 Blocking ASTs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7137.4.6 Lock Conversions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7137.4.7 Forced Queuing of Conversions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7147.4.8 Parent Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7157.4.9 Lock Value Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7167.4.10 Interoperation with 16-Byte and 64-Byte Value Blocks . . . . . . . . . . . . 7177.5 Dequeuing Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7187.6 Local Buffer Caching with the Lock Management Services . . . . . . . . . . . 7207.6.1 Using the Lock Value Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7207.6.2 Using Blocking ASTs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7207.6.2.1 Deferring Buffer Writes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7207.6.2.2 Buffer Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7217.6.3 Choosing a Buffer-Caching Technique . . . . . . . . . . . . . . . . . . . . . . . . . 7217.7 Example of Using Lock Management Services . . . . . . . . . . . . . . . . . . . . . 722

Part II Interrupts and Condition Handling

8 Using Asynchronous System Traps8.1 Overview of AST Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 818.2 Declaring and Queuing ASTs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 828.2.1 Reentrant Code and ASTs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 838.2.1.1 The Call Frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 838.2.2 Shared Data Access with Readers and Writers . . . . . . . . . . . . . . . . . . 838.2.3 Shared Data Access and AST Synchronization . . . . . . . . . . . . . . . . . . 848.2.4 User ASTs and Asynchronous Completions . . . . . . . . . . . . . . . . . . . . . 858.3 Common Mistakes in Asynchronous Programming . . . . . . . . . . . . . . . . . . 858.4 Using System Services for AST Event and Time Delivery . . . . . . . . . . . . . 858.5 Access Modes for AST Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 878.6 Calling an AST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 878.7 Delivering ASTs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 888.7.1 The AST Service Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 898.7.2 Conditions Affecting AST Delivery . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8108.7.3 Kernel Threads AST Delivery (Alpha and I64Only) . . . . . . . . . . . . . . . 8118.7.3.1 Outer Mode (User and Supervisor) Nonserial Delivery of ASTs . . . 8128.7.3.2 Inner Mode (Executive and Kernel) AST Delivery . . . . . . . . . . . . . 8138.8 ASTs and Process Wait States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8138.8.1 Event Flag Waits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8138.8.2 Hibernation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8138.8.3 Resource Waits and Page Faults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8148.9 Examples of Using AST Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 814

ix

9 Condition-Handling Routines and Services9.1 Overview of Run-Time Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 919.2 Overview of the OpenVMS Condition Handling Facility . . . . . . . . . . . . . . 929.2.1 Condition-Handling Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 929.2.2 Functions of the Condition Handling Facility . . . . . . . . . . . . . . . . . . . 949.3 Exception Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 979.3.1 Conditions Caused by Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 989.3.2 Exception Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9149.3.3 Arithmetic Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9169.3.4 Unaligned Access Traps (Alpha and I64 Only) . . . . . . . . . . . . . . . . . . . 9189.4 How Run-Time Library Routines Handle Exceptions . . . . . . . . . . . . . . . . 9189.4.1 Exception Conditions Signaled from Mathematics Routines (VAX

Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9199.4.1.1 Integer Overflow and Floating-Point Overflow . . . . . . . . . . . . . . . . 9199.4.1.2 Floating-Point Underflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9199.4.2 System-Defined Arithmetic Condition Handlers . . . . . . . . . . . . . . . . . 9199.5 Condition Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9219.5.1 Return Status Convention . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9249.5.1.1 Testing Returned Condition Values . . . . . . . . . . . . . . . . . . . . . . . . 9249.5.1.2 Using the $VMS_STATUS_SUCCESS Macro . . . . . . . . . . . . . . . . . 9249.5.1.3 Testing SS$_NOPRIV and SS$_EXQUOTA Condition Values . . . . 9259.5.2 Modifying Condition Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9269.6 Exception Dispatcher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9279.7 Argument List Passed to a Condition Handler . . . . . . . . . . . . . . . . . . . . . 9309.8 Signaling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9319.8.1 Generating Signals with LIB$SIGNAL and LIB$STOP . . . . . . . . . . . . 9339.8.2 Signal Argument Vector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9369.8.3 VAX Mechanism Argument Vector (VAX Only) . . . . . . . . . . . . . . . . . . . 9389.8.4 Alpha Mechanism Argument Vector (Alpha Only) . . . . . . . . . . . . . . . . 9409.8.5 I64 Mechanism Vector Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9429.8.6 Multiple Active Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9469.9 Types of Condition Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9489.9.1 Default Condition Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9499.9.2 Interaction Between Default and User-Supplied Handlers . . . . . . . . . 9519.10 Types of Actions Performed by Condition Handlers . . . . . . . . . . . . . . . . . 9529.10.1 Unwinding the Call Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9539.10.2 GOTO Unwind Operations (Alpha and I64 Only) . . . . . . . . . . . . . . . . . 9569.11 Displaying Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9569.11.1 Chaining Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9609.11.2 Logging Error Messages to a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9629.11.2.1 Creating a Running Log of Messages Using SYS$PUTMSG . . . . . 9639.11.2.2 Suppressing the Display of Messages in the Running Log . . . . . . . 9639.11.3 Using the Message Utility to Signal and Display User-Defined

Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9649.11.3.1 Creating the Message Source File . . . . . . . . . . . . . . . . . . . . . . . . . 9659.11.3.1.1 Specifying the Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9659.11.3.1.2 Specifying the Severity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9669.11.3.1.3 Specifying Condition Names and Messages . . . . . . . . . . . . . . . 9669.11.3.1.4 Specifying Variables in the Message Text . . . . . . . . . . . . . . . . . 9679.11.3.1.5 Compiling and Linking the Messages . . . . . . . . . . . . . . . . . . . 9679.11.3.1.6 Linking the Message Object Module . . . . . . . . . . . . . . . . . . . . 9679.11.3.1.7 Accessing the Message Object Module from Multiple Programs

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9679.11.3.1.8 Modifying a Message Source Module . . . . . . . . . . . . . . . . . . . . 968

x

9.11.3.1.9 Accessing Modified Messages Without Relinking . . . . . . . . . . . 9689.11.4 Signaling User-Defined Values and Messages with Global and Local

Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9689.11.4.1 Signaling with Global Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . 9689.11.4.2 Signaling with Local Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9689.11.4.3 Specifying FAO Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9699.12 Writing a Condition Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9709.12.1 Continuing Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9719.12.2 Resignaling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9719.12.3 Unwinding the Call Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9729.12.4 Example of Writing a Condition Handler . . . . . . . . . . . . . . . . . . . . . . . 9729.12.4.1 Signal Array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9729.12.4.2 Mechanism Array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9729.12.4.3 Comparing the Signaled Condition with an Expected Condition

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9729.12.4.4 Exiting from the Condition Handler . . . . . . . . . . . . . . . . . . . . . . . . 9739.12.4.5 Returning Control to the Program . . . . . . . . . . . . . . . . . . . . . . . . . 9749.12.5 Example of Condition-Handling Routines . . . . . . . . . . . . . . . . . . . . . . 9769.13 Debugging a Condition Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9779.14 Run-Time Library Condition-Handling Routines . . . . . . . . . . . . . . . . . . . . 9779.14.1 RTL Jacket Handlers (Alpha and I64 Only) . . . . . . . . . . . . . . . . . . . . . 9789.14.2 Converting a Floating-Point Fault to a Floating-Point Trap (VAX

Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9789.14.3 Changing a Signal to a Return Status . . . . . . . . . . . . . . . . . . . . . . . . 9789.14.4 Changing a Signal to a Stop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9809.14.5 Matching Condition Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9809.14.6 Correcting a Reserved Operand Condition (VAX Only) . . . . . . . . . . . . 9809.14.7 Decoding the Instruction That Generated a Fault (VAX Only) . . . . . . 9819.15 Exit Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9819.15.1 Establishing an Exit Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9829.15.2 Writing an Exit Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9849.15.3 Debugging an Exit Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9859.15.4 Example of Exit Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 985

Part III Addressing and Memory Management

10 Overview of Alpha and I64 Virtual Address Space10.1 Using 64-Bit Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10110.2 Traditional OpenVMS 32-Bit Virtual Address Space Layout . . . . . . . . . . . 10210.3 OpenVMS Alpha and OpenVMS I64 64-Bit Virtual Address Space

Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10310.3.1 Process-Private Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10410.3.2 System Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10510.3.3 Page Table Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10510.3.4 Virtual Address Space Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10610.4 Virtual Regions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10610.4.1 Regions Within P0 Space and P1 Space . . . . . . . . . . . . . . . . . . . . . . . . 10810.4.2 64-Bit Program Region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10810.4.3 User-Defined Virtual Regions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

xi

11 Support for 64-Bit Addressing (Alpha and I64 Only)11.1 System Services Support for 64-Bit Addressing . . . . . . . . . . . . . . . . . . . . . 11111.1.1 System Services Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11111.1.2 Comparison of 32-Bit and 64-Bit Descriptors . . . . . . . . . . . . . . . . . . . . 11211.1.3 Comparison of 32-Bit and 64-Bit Item Lists . . . . . . . . . . . . . . . . . . . . . 11411.1.3.1 32-Bit Item Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11511.1.3.2 64-Bit Item Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11611.1.4 System Services That Support 64-Bit Addresses . . . . . . . . . . . . . . . . . 11811.1.5 Sign-Extension Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111211.1.6 Language Support for 64-Bit System Services . . . . . . . . . . . . . . . . . . . 111211.2 RMS Interface Features for 64-Bit Addressing . . . . . . . . . . . . . . . . . . . . . 111211.2.1 RAB64 Data Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111311.2.2 Using the 64-Bit RAB Extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111411.2.3 Macros to Support User RAB Structure . . . . . . . . . . . . . . . . . . . . . . . . 111511.3 File System Support for 64-Bit Addressing . . . . . . . . . . . . . . . . . . . . . . . . 111611.4 OpenVMS Alpha and OpenVMS I64 64-Bit API Guidelines . . . . . . . . . . . . 111611.4.1 Quadword/Longword Argument Pointer Guidelines . . . . . . . . . . . . . . . 111611.4.2 OpenVMS Alpha, OpenVMS VAX, and OpenVMS I64 Guidelines . . . . 112311.4.3 Promoting an API from a 32-Bit API to a 64-Bit API . . . . . . . . . . . . . 112311.4.4 Example of a 32-Bit Routine and a 64-Bit Routine . . . . . . . . . . . . . . . 112411.5 OpenVMS Alpha and OpenVMS I64 Tools and Utilities That Support

64-Bit Addressing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112511.5.1 OpenVMS Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112511.5.2 OpenVMS Alpha System-Code Debugger . . . . . . . . . . . . . . . . . . . . . . . 112611.5.3 Delta/XDelta . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112611.5.4 LIB$ and CVT$ Facilities of the OpenVMS Run-Time Library . . . . . . 112611.5.5 Watchpoint Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112611.5.6 SDA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112711.6 Language and Pointer Support for 64-Bit Addressing . . . . . . . . . . . . . . . . 112711.7 HP C RTL Support for 64-Bit Addressing . . . . . . . . . . . . . . . . . . . . . . . . . 1128

12 Memory Management Services and Routines on OpenVMS Alphaand OpenVMS I6412.1 Virtual Page Sizes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12112.2 Levels of Memory Allocation Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12212.3 Using System Services for Memory Allocation . . . . . . . . . . . . . . . . . . . . . . 12412.3.1 Increasing and Decreasing Virtual Address Space with 64-Bit System

Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12412.3.2 Increasing and Decreasing Virtual Address Space with 32-bit System

Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12512.3.3 Input Address Arrays and Return Address Arrays for the 64-Bit

System Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12712.3.4 Input Address Arrays and Return Address Arrays for the 32-Bit

System Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12812.3.5 Allocating Memory in Existing Virtual Address Space on Alpha and

I64 Systems Using the 32-Bit System Service . . . . . . . . . . . . . . . . . . . 12912.3.6 Page Ownership and Protection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1210

xii

12.3.7 Working Set Paging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121112.3.7.1 SYS$ADJWSL System Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121112.3.7.2 SYS$PURGWS System Service . . . . . . . . . . . . . . . . . . . . . . . . . . . 121112.3.7.3 SYS$LKWSET and SYS$LKWSET_64 System Services . . . . . . . . 121212.3.7.4 Specifying a Range of Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . 121212.3.7.5 Specifying a Range of Addresses In OpenVMS Version 8.1 . . . . . . 121212.3.7.6 Specifying a Range of Addresses In OpenVMS Versions Prior to

V8.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121312.3.7.7 Specifying the Access Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121312.3.8 Process Swapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121312.3.9 Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121412.3.9.1 Creating Sections with 64-Bit System Services . . . . . . . . . . . . . . . 121512.3.9.2 PFN-Mapped Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121512.3.9.3 Creating Sections with 32-Bit System Services . . . . . . . . . . . . . . . 121612.3.9.3.1 Opening the Disk File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121612.3.9.3.2 Defining the Section Extents . . . . . . . . . . . . . . . . . . . . . . . . . . 121712.3.9.3.3 Defining the Section Characteristics . . . . . . . . . . . . . . . . . . . . 121712.3.9.3.4 Defining Global Section Characteristics . . . . . . . . . . . . . . . . . 121812.3.9.3.5 Global Section Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121812.3.9.4 Mapping Sections with 32-Bit System Services . . . . . . . . . . . . . . . 121912.3.9.5 Mapping Global Sections with 32-Bit Services . . . . . . . . . . . . . . . . 122212.3.9.6 Global Page-File Sections with 32-Bit System Services . . . . . . . . . 122312.3.9.7 Mapping into a Defined Address Range With 32-Bit System

Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122312.3.9.8 Mapping from an Offset into a Section File With 32-Bit System

Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122312.3.9.9 Section Paging Resulting from SYS$CRMPSC . . . . . . . . . . . . . . . . 122412.3.9.10 Reading and Writing Data Sections . . . . . . . . . . . . . . . . . . . . . . . 122612.3.9.11 Releasing and Deleting Sections . . . . . . . . . . . . . . . . . . . . . . . . . . 122712.3.9.12 Writing Back Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122712.3.9.13 Memory-Resident Global Sections . . . . . . . . . . . . . . . . . . . . . . . . . 122812.3.9.14 Image Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122812.3.9.15 Page Frame Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122812.3.9.16 Partial Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122912.3.10 Example of Using 32-Bit Memory Management System Services . . . . 123012.4 Large Page-File Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1234

13 Memory Management Services and Routines on OpenVMS VAX13.1 Virtual Page Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13113.2 Virtual Address Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13113.3 Extended Addressing Enhancements on Selected VAX Systems . . . . . . . . . 13313.3.1 Page Table Entry for Extended Addresses on VAX Systems . . . . . . . . 13513.4 Levels of Memory Allocation Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13513.5 Using System Services for Memory Allocation . . . . . . . . . . . . . . . . . . . . . . 13713.5.1 Increasing and Decreasing Virtual Address Space . . . . . . . . . . . . . . . . 13813.5.2 Input Address Arrays and Return Address Arrays . . . . . . . . . . . . . . . 13913.5.3 Page Ownership and Protection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131013.5.4 Working Set Paging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131113.5.5 Process Swapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1312

xiii

13.5.6 Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131313.5.6.1 Creating Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131413.5.6.2 Opening the Disk File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131413.5.6.3 Defining the Section Extents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131513.5.6.4 Defining the Section Characteristics . . . . . . . . . . . . . . . . . . . . . . . 131513.5.6.5 Defining Global Section Characteristics . . . . . . . . . . . . . . . . . . . . . 131613.5.6.6 Global Section Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131713.5.6.7 Mapping Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131813.5.6.8 Mapping Global Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131913.5.6.9 Global Page-File Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132013.5.6.10 Section Paging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132013.5.6.11 Reading and Writing Data Sections . . . . . . . . . . . . . . . . . . . . . . . . 132213.5.6.12 Releasing and Deleting Sections . . . . . . . . . . . . . . . . . . . . . . . . . . 132313.5.6.13 Writing Back Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132313.5.6.14 Image Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132313.5.6.15 Page Frame Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132413.5.7 Example of Using Memory Management System Services . . . . . . . . . . 1325

14 Using Run-Time Routines for Memory Allocation14.1 Allocating and Freeing Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14114.2 Interactions with Other Run-Time Library Routines . . . . . . . . . . . . . . . . . 14314.3 Interactions with System Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14414.4 Zones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14614.4.1 Zone Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14814.4.2 Default Zone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141214.4.3 Zone Identification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141214.4.4 Creating a Zone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141314.4.5 Deleting a Zone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141314.4.6 Resetting a Zone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141314.5 Allocating and Freeing Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141414.6 Allocation Algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141414.6.1 First Fit Algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141514.6.2 Quick Fit Algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141614.6.3 Frequent Sizes Algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141614.6.4 Fixed Size Algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141614.7 User-Defined Zones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141614.8 Debugging Programs That Use Virtual Memory Zones . . . . . . . . . . . . . . . 1419

15 Alignment on VAX, Alpha, and I64 Systems15.1 Alignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15115.1.1 Alignment and Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15215.1.1.1 Alignment on OpenVMS VAX (VAX Only) . . . . . . . . . . . . . . . . . . . 15315.1.1.2 Alignment on OpenVMS Alpha and I64 . . . . . . . . . . . . . . . . . . . . . 15315.2 Using Compilers for Alignment (Alpha and I64 Only) . . . . . . . . . . . . . . . . 15415.2.1 The HP C Compiler (Alpha and I64 Only) . . . . . . . . . . . . . . . . . . . . . . 15415.2.1.1 Compiler Example of Memory Structure of VAX C and HP C . . . . 15515.2.2 The BLISS Compiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15615.2.3 The HP Fortran Compiler (Alpha and I64 Only) . . . . . . . . . . . . . . . . . 15615.2.4 The MACRO-32 Compiler (Alpha and I64) . . . . . . . . . . . . . . . . . . . . . . 15715.2.4.1 Precedence of Alignment Controls . . . . . . . . . . . . . . . . . . . . . . . . . 15915.2.4.2 Recommendations for Aligning Data . . . . . . . . . . . . . . . . . . . . . . . 15915.2.5 The VAX Environment Software TranslatorVEST (Alpha Only) . . . . 159

xiv

15.3 Using Tools for Finding Unaligned Data . . . . . . . . . . . . . . . . . . . . . . . . . . 151015.3.1 The OpenVMS Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151015.3.2 The Performance and Coverage AnalyzerPCA . . . . . . . . . . . . . . . . . 151115.3.3 System Services (Alpha and I64 Only) . . . . . . . . . . . . . . . . . . . . . . . . . 151115.3.4 Alignment Fault Utility (Alpha and I64 Only) . . . . . . . . . . . . . . . . . . . 1512

16 Memory Management with VLM Features16.1 Overview of VLM Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16116.2 Memory-Resident Global Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16216.3 Fast I/O and Buffer Objects for Global Sections . . . . . . . . . . . . . . . . . . . . . 16416.3.1 Comparison of $QIO and Fast I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16416.3.2 Overview of Locking Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16416.3.3 Overview of Buffer Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16516.3.4 Creating and Using Buffer Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . 16616.4 Shared Page Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16616.4.1 Memory Requirements for Private Page Tables . . . . . . . . . . . . . . . . . . 16716.4.2 Shared Page Tables and Private Data . . . . . . . . . . . . . . . . . . . . . . . . . 16716.5 Expandable Global Page Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

Part IV Appendixes: Macros and Examples of 64-Bit Programming

A C Macros for 64-Bit AddressingDESCRIPTOR64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A1$is_desc64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A2$is_32bits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A2

B 64-Bit Example Program

C VLM Example Program

Index

Examples31 Performing an Iterative Calculation with a Spawned Subprocess . . . . 3332 Opening a Mailbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31233 Synchronous I/O Using a Mailbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31234 Immediate I/O Using a Mailbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31535 Asynchronous I/O Using a Mailbox . . . . . . . . . . . . . . . . . . . . . . . . . . . 31841 Obtaining Different Types of Process Information . . . . . . . . . . . . . . . . 4742 Using SYS$GETJPI to Obtain Calling Process Information . . . . . . . . . 4943 Obtaining the Process Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41144 Using SYS$GETJPI and the Process Name to Obtain Information

About a Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41245 Using SYS$GETJPI to Request Information About All Processes on

the Local System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41346 Using SYS$GETJPI and SYS$PROCESS_SCAN to Select Process

Information by User Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418

xv

47 Using SYS$GETJPI and SYS$PROCESS_SCAN with Multiple Valuesfor One Criterion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420

48 Selecting Processes That Match Multiple Criteria . . . . . . . . . . . . . . . . 42149 Searching the Cluster for Process Information . . . . . . . . . . . . . . . . . . . 422410 Searching for Process Information on Specific Nodes in the Cluster . . 423411 Using a SYS$GETJPI Buffer to Improve Performance . . . . . . . . . . . . . 425412 Using SYS$GETJPI Control Flags to Avoid Swapping a Process into

the Balance Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427413 Procedure for Obtaining Process Lock Information . . . . . . . . . . . . . . . 430414 Executing a Program Using Delta Time . . . . . . . . . . . . . . . . . . . . . . . . 460415 Executing a Program at Timed Intervals . . . . . . . . . . . . . . . . . . . . . . . 46271 Requesting a Null Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71181 Calling the SYS$SETIMR System Service . . . . . . . . . . . . . . . . . . . . . . 87141 Monitoring Heap Operations with a User-Defined Zone . . . . . . . . . . . . 1417151 OpenVMS Debugger Output from SET OUTPUT LOG Command . . . . 1510

Figures41 Image Exit and Process Deletion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47371 Model Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7372 Three Lock Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7773 Deadlock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7874 Lock Status Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71291 SS$_HPARITH Exception Signal Array . . . . . . . . . . . . . . . . . . . . . . . . 91792 SS$_ALIGN Exception Signal Array . . . . . . . . . . . . . . . . . . . . . . . . . . 91893 Format of a Condition Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92294 Searching the Stack for a Condition Handler . . . . . . . . . . . . . . . . . . . . 92995 Sample Stack Scan for Condition Handlers . . . . . . . . . . . . . . . . . . . . . 93396 Format of the Signal Argument Vector . . . . . . . . . . . . . . . . . . . . . . . . 93697 Signal Argument Vector for the Reserved Operand Error Conditions

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93898 Signal Argument Vector for RTL Mathematics Routine Errors . . . . . . 93899 Format of a VAX Mechanism Argument Vector . . . . . . . . . . . . . . . . . . 939910 Mechanism Array on Alpha Systems . . . . . . . . . . . . . . . . . . . . . . . . . . 941911 I64 Mechanism Vector Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 944912 Stack After Second Exception Condition Is Signaled . . . . . . . . . . . . . 947913 Interaction Between Handlers and Default Handlers . . . . . . . . . . . . . 951914 Unwinding the Call Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 955915 Formats of Message Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 959916 Using a Condition Handler to Log an Error Message . . . . . . . . . . . . . 963917 Structure of an Exit Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 982101 32-Bit Virtual Address Space Layout . . . . . . . . . . . . . . . . . . . . . . . . . . 102102 64-Bit Virtual Address Space Layout . . . . . . . . . . . . . . . . . . . . . . . . . . 104111 General Format of a 32-Bit Descriptor . . . . . . . . . . . . . . . . . . . . . . . . . 113112 General Format of a 64-Bit Descriptor . . . . . . . . . . . . . . . . . . . . . . . . . 113113 Item_list_2 Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115114 Item_list_3 Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

xvi

115 Item_list_64a Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116116 Item_list_64b Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117117 item_list_64a . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1119118 item_list_64b . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1119131 Virtual Address Overview on VAX Systems . . . . . . . . . . . . . . . . . . . . . 132132 Layout of VAX Process Virtual Address Space . . . . . . . . . . . . . . . . . . . 133133 Physical Address Space for VAX Systems with XPA . . . . . . . . . . . . . . . 134134 Virtual Address Space for VAX Systems with XVA . . . . . . . . . . . . . . . 135135 Hierarchy of VAX Memory Management Routines . . . . . . . . . . . . . . . . 137141 Memory Fragmentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143142 Boundary Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149151 Aligned and Unaligned Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152152 Alignment Using VAX C Compiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155153 Alignment Using HP C Compiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

Tables11 Manual Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1212 OpenVMS Programming Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1913 Compilers, Interpreters, and Assemblers . . . . . . . . . . . . . . . . . . . . . . . 11014 Other OpenVMS Program Development Utilities . . . . . . . . . . . . . . . . . 11315 Groups of OpenVMS Run-Time Library Routines . . . . . . . . . . . . . . . . 11516 Groups of OpenVMS System Services . . . . . . . . . . . . . . . . . . . . . . . . . 11617 OpenVMS Utility Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11721 Characteristics of Subprocesses and Detached Processes . . . . . . . . . . . 2122 Comparison of LIB$SPAWN, SYS$CREPRC, and C system( ) Call

Context Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2341 Routines and Commands for Controlling Processes and Kernel

Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4242 Process Identification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4543 SYS$GETJPI Kernel Threads Item Codes . . . . . . . . . . . . . . . . . . . . . . 41544 SYS$PROCESS_SCAN Kernel Threads Item Codes . . . . . . . . . . . . . . 41645 Item-Specific Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41646 Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43347 SYSMAN Command: Class_Schedule . . . . . . . . . . . . . . . . . . . . . . . . . 43748 Class Name Qualifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43849 Show Subcommand Qualifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439410 Time Manipulation System Services and Routines . . . . . . . . . . . . . . . 459411 Process Hibernation and Suspension . . . . . . . . . . . . . . . . . . . . . . . . . . 464412 System Services and Routines Used for Hibernation and

Suspension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464413 Contents of $DELPRC Flag Argument . . . . . . . . . . . . . . . . . . . . . . . . . 47561 OpenVMS Compilers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61562 Usage Styles of Event Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62363 Event Flag Routines and Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62464 Event Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62571 Lock Manager Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

xvii

72 Lock Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7573 Compatibility of Lock Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7674 Legal QUECVT Conversions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71575 Effect of Lock Conversion on Lock Value Block . . . . . . . . . . . . . . . . . . 71781 AST System Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8282 System Services That Use ASTs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8283 AST Arguments for VAX, Alpha, and I64 Systems . . . . . . . . . . . . . . . . 8991 Summary of Exception Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9992 I64-Specific Exception Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91393 Architecture-Specific Hardware Exceptions . . . . . . . . . . . . . . . . . . . . . 91594 Exception Summary Argument Fields . . . . . . . . . . . . . . . . . . . . . . . . . 91795 Run-Time Library Condition-Handling Support Routines . . . . . . . . . . 92196 Fields of a Condition Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92297 Severity of Error Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92398 Privilege Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92599 Quota Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 925910 $CHFDEF Symbolic Names and Arguments on VAX Systems . . . . . . . 930911 $CHFDEF2 Symbolic Names and Arguments on Alpha and I64

Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 931912 Fields in the Alpha Mechanism Array . . . . . . . . . . . . . . . . . . . . . . . . 942913 Contents of the I64 Argument Mechanism Array (MECH) . . . . . . . . . . 945111 Contents of the General Descriptor Format . . . . . . . . . . . . . . . . . . . . . 114112 64-Bit System Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118121 Sample Virtual Address Arrays for 64-Bit Services . . . . . . . . . . . . . . . 128122 Page and Byte Offset Within Pages on Alpha and I64 Systems . . . . . . 128123 Sample Virtual Address Arrays on Alpha and I64 Systems . . . . . . . . . 129131 Sample Virtual Address Arrays on VAX Systems . . . . . . . . . . . . . . . . . 1310132 Flag Bits to Set for Specific Section Characteristics on VAX

Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1316141 Overhead for Area Control Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1410142 Possible Values for the Block Size Attribute . . . . . . . . . . . . . . . . . . . . 1410143 Attribute Values for the Default Zone . . . . . . . . . . . . . . . . . . . . . . . . . 1412144 Allocation Algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1415151 Aligned Data Sizes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152161 Page Table Size Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

xviii

Preface

Intended AudienceThis manual is intended for system and application programmers. It presumesthat its readers have some familiarity with the HP OpenVMS programmingenvironment.

Document StructureThe printed copy of the HP OpenVMS Programming Concepts Manual is atwo-volume manual. The first volume contains four parts; the four parts are asfollows:

Process and Synchronization

Interrupts and Condition Handling

Addressing and Memory Management

Appendixes: Macros and Examples of 64-Bit Programming

Within the parts of Volume I, chapters provide information about theprogramming features of the OpenVMS operating system. A list of the chaptersand a summary of their content follows:

Chapter 1 describes the structure of the two-volume manual, and offers anintroduction to the OpenVMS operating system and to the tools that areavailable in the programming environment.

Chapter 2 defines the two types of processes, and describes what constitutesthe context of a process, and the modes of execution of a process. It alsodescribes kernel threads and the kernel threads process structure.

Chapter 3 describes communication within a process and between processes.

Chapter 4 describes how to use the creation and control of a process or kernelthread for programming tasks. It also describes how to gather informationabout a process or kernel thread and how to synchronize a program by usingtime.

Chapter 5 describes overview concepts of symmetric multiprocessing (SMP)systems.

Chapter 6 describes synchronization concepts and the differences betweensynchronization techniques on VAX systems, Alpha systems, and I64 systems.It presents methods of synchronization such as event flags, asynchronoussystem traps (ASTs), parallel processing RTLs, and process priorities, and theeffects of kernel threads upon synchronization. It also describes how to usesynchronous and asynchronous system services, and how to write applicationsin a multiprocessing environment.

xix

Chapter 7 describes the use of the lock manager system services tosynchronize access to shared resources. This chapter presents the concept ofresources and locks; it also describes the use of the SYS$ENQ and SYS$DEQsystem services to queue and dequeue locks.

Chapter 8 describes how to use asynchronous system traps (ASTs). Itdescribes access modes and service routines for ASTs and how ASTs aredeclared and delivered. It also describes the effects of kernel threads on ASTdelivery.

Chapter 9 describes the OpenVMS Condition Handling facility. It describesVAX system, Alpha system, and I64 system exceptions, arithmetic exceptions,and Alpha and I64 system unaligned access traps. It describes the conditionvalue field, exception dispatcher, signaling, and the argument list passed to acondition handler. Additionally, types of condition handlers and various typesof actions performed by them are presented. This chapter also describes howto write and debug a condition handler, and how to use an exit handler.

Chapter 10 describes the 32-bit and 64-bit use of virtual address space.

Chapter 11 describes all the services, routines, tools, and programs thatsupport 64-bit addressing.

Chapter 12 describes system services and RTLs of Alpha and I64 systemsto manage memory. It describes the page size and layout of virtual addressspace on Alpha and I64 systems. This chapter also describes how to addvirtual address space, adjust working sets, control process swapping, andcreate and manage sections on Alpha and I64 systems.

Chapter 13 describes the of system services and RTLs of VAX systems tomanage memory. It describes the page size and layout of virtual addressspace on VAX systems. This chapter also describes how to add virtual addressspace, adjust working sets, control process swapping, and create and managesections on VAX systems.

Chapter 14 describes how to use RTLs to allocate and free pages and blocks ofmemory, and how to use RTLs to create, manage, and debug virtual memoryzones.

Chapter 15 describes the importance and techniques of instruction and dataalignment.

Chapter 16 describes the VLM memory management features, such as thefollowing:

Memory-resident global sectionsFast I/O and buffer objects for global sectionsShared page tablesExpandable global page tableReserved memory registry

Appendix A describes the C language macros for manipulating 64-bitaddresses, for checking the sign extension of the low 32 bits of 64-bit values,and for checking descriptors for the 64-bit format.

Appendix B illustrates writing a program with a 64-bit region that wascreated and deleted by system services.

Appendix C demonstrates the memory management VLM features describedin Chapter 16.

xx

Related DocumentsFor a detailed description of each run-time library and system service routinementioned in this manual, see the OpenVMS Run-Time Library documentationand the HP OpenVMS System Services Reference Manual.

You can find additional information about calling OpenVMS system services andRun-Time Library routines in your language processor documentation. You mayalso find the following documents useful:

HP OpenVMS DCL Dictionary

OpenVMS Users Manual

Guide to OpenVMS File Applications

HP OpenVMS Guide to System Security

OpenVMS Record Management Services documentation

OpenVMS Utility Routines Manual

HP OpenVMS I/O Users Reference Manual

For additional information about HP OpenVMS products and services, visit thefollowing World Wide Web address:

http://www.hp.com/go/openvms

Readers CommentsHP welcomes your comments on this manual. Please send comments to either ofthe following addresses:

Internet openvmsdoc@hp.com

Postal Mail Hewlett-Packard CompanyOSSG Documentation Group, ZKO3-4/U08110 Spit Brook Rd.Nashua, NH 03062-2698

How to Order Additional DocumentationFor information about how to order additional documentation, visit the followingWorld Wide Web address:

http://www.hp.com/go/openvms/doc/order

ConventionsThe following conventions may be used in this manual:

Ctrl/x A sequence such as Ctrl/x indicates that you must hold downthe key labeled Ctrl while you press another key or a pointingdevice button.

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

xxi

Return In examples, a key name enclosed in a box indicates thatyou press a key on the keyboard. (In text, a key name is notenclosed in a box.)

In the HTML version of this document, this convention appearsas brackets, rather than a box.

. . . A horizontal ellipsis in examples indicates one of the followingpossibilities:

Additional optional arguments in a statement have beenomitted.

The preceding item or items can be repeated one or moretimes.

Additional parameters, values, or other information can beentered.

.

.

.

A vertical ellipsis indicates the omission of items from a codeexample or command format; the items are omitted becausethey are not important to the topic being discussed.

( ) In command format descriptions, parentheses indicate that youmust enclose choices in parentheses if you specify more thanone.

[ ] In command format descriptions, brackets indicate optionalchoices. 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 OpenVMSdirectory specifications and for a substring specification in anassignment statement.

| In command format descriptions, vertical bars separate choiceswithin brackets or braces. Within brackets, the choices areoptional; within braces, at least one choice is required. Do nottype the vertical bars on the command line.

{ } In command format descriptions, braces indicate requiredchoices; you must choose at least one of the items listed. Donot type the braces on the command line.

bold type Bold type represents the introduction of a new term. It alsorepresents the name of an argument, an attribute, or a reason.

italic type Italic type indicates important information, complete titlesof manuals, or variables. Variables include information thatvaries in system output (Internal error number), in commandlines (/PRODUCER=name), and in command parameters intext (where dd represents the predefined code for the devicetype).

Example This typeface indicates code examples, command examples, andinteractive screen displays. In text, this type also identifiesURLs, UNIX commands and pathnames, PC-based commandsand folders, and certain elements of the C programminglanguage.

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

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

numbers All numbers in text are assumed to be decimal unlessotherwise noted. Nondecimal radixesbinary, octal, orhexadecimalare explicitly indicated.

xxii

1Overview of Manuals and Introduction to

Development on OpenVMS Systems

This chapter describes the structure of this two-volume manual. This chapteralso provides an overview of the OpenVMS operating system, its components, andthe tools in programming software.

1.1 Overview of the ManualThis two-volume manual introduces the resources and features of the OpenVMSoperating system that are available to help you develop programs. Table 11describes the parts of each volume.

Overview of Manuals and Introduction to Development on OpenVMS Systems 11

Overview of Manuals and Introduction to Development on OpenVMS Systems1.1 Overview of the Manual

Table 11 Manual DescriptionVolume Part Description

Volume I

Part I Process and Synchronization. Describesthe creation, communication, and controlof processes. It also describes symmetricmultiprocessing (SMP), and the synchronizing ofdata access, programming operations, and accessto resources.

Part II Interrupts and Condition Handling.Describes the use of asynchronous system traps(ASTs), and the use of routines and services forhandling conditions.

Part III Addressing and Memory Management.Describes 32-bit and 64-bit address space,and the support offered for 64-addressing. Italso provides guidelines for 64-bit applicationprogramming interfaces (APIs); and Alpha, I64,VAX, and VLM memory management with run-time routines for memory management, andalignment on OpenVMS Alpha, VAX, and I64systems.

Part IV Appendixes: Macros and Examples of 64-Bit Programming. Describes the macros usedin 64-bit programming, along with two examplesof 64-bit programmming.

Volume II

Part I OpenVMS Programming Interfaces: Callinga System Routine. Describes the basic callingformat for OpenVMS routines and systemservices. It also describes the STARLETstructures and definitions for C programmers.

Part II I/O, System and Programming Routines.Describes the I/O operations, and the systemand programming routines used by run-timelibraries and system services.

Part III Generic Macros for Calling SystemServices. Describes in appendixes the genericmacros used for calling system services,OpenVMS data types, and the distributed nameservices on OpenVMS VAX systems.

1.2 Overview of the OpenVMS Operating SystemThe OpenVMS operating system is a highly flexible, general-purpose, multiusersystem that supports the full range of computing capabilities, providing thehigh integrity and dependability of commercial-strength systems along with thebenefits of open, distributed client/server systems.

OpenVMS operating systems can be integrated with systems from differentvendors in open systems computing environments. HP has opened thetraditional VMS system to support software that conforms to internationalstandards for an open environment. These industry-accepted, open standardsspecify interfaces and services that permit applications and users to movebetween systems and allow applications on different systems to operate together.

12 Overview of Manuals and Introduction to Development on OpenVMS Systems

Overview of Manuals and Introduction to Development on OpenVMS Systems1.2 Overview of the OpenVMS Operating System

The OpenVMS operating system configuration includes OpenVMS integratedsoftware, services and routines, applications, and networks. The system supportsall styles of computing, from timesharing to real-time processing to transactionprocessing. OpenVMS systems configured with optional software supportdistributed computing capabilities and can function as servers in multivendorclient/server configurations.

The OpenVMS operating system is designed to provide software compatibilityacross all the processors on which it runs.

The following sections describe the components of the OpenVMS operatingsystem, give a general overview of the system software, and describe thevarious styles of computing that OpenVMS software supports. The sections alsosummarize the basic ways in which OpenVMS software can be configured andconnected to other software, and the hardware platforms and processors on whichthe OpenVMS software runs.

1.3 Components of the OpenVMS Operating SystemThe OpenVMS operating system is a group of software programs (or images)that control computing operations. The base operating system is made up of corecomponents and an array of services, routines, utilities, and related software.The OpenVMS operating system serves as the foundation from which all optionalsoftware products and applications operate. The services and utilities in the baseOpenVMS operating system support functions such as system management, datamanagement, and program development. Other integrated software that addsvalue to the system provides functions such as clustering and volume shadowing.

Optional software products, including application programs developed byOpenVMS programmers and other programmers, run on the core operatingsystem. The OpenVMS system supports a powerful, integrated developmentenvironment with a wide selection of software development tools supplied byHP and other vendors. Application programs written in multiple languagesprovide computational, data-processing, and transaction-processing capabilities.Thousands of applications have been developed for OpenVMS systems by HP andindependent software vendors.

Compatibility Between Software VersionsOpenVMS VAX, OpenVMS Alpha, and OpenVMS I64 software exhibitscompatibility from version to version:

User-mode programs and applications created under earlier versions ofOpenVMS VAX, OpenVMS Alpha, and OpenVMS I64 run under subsequentversions with no change.

Command procedures written under one version of OpenVMS continue to rununder newer versions of the software.

OpenVMS software developed on VAX platforms can migrate easily to Alpha andI64 platforms (see Section 1.3.1.1):

Most user-mode OpenVMS VAX sources can be recompiled, relinked, and runon an OpenVMS Alpha and OpenVMS I64 system without modification. Codethat explicitly relies on the VAX architecture requires modification.

Most OpenVMS Alpha images run under translation on OpenVMS I64.

Translation is available for OpenVMS VAX applications without sources orthat you do not want to recompile.

Overview of Manuals and Introduction to Development on OpenVMS Systems 13

Overview of Manuals and Introduction to Development on OpenVMS Systems1.3 Components of the OpenVMS Operating System

1.3.1 OpenVMS Systems on Multiple PlatformsThe OpenVMS operating system is available on three hardware platforms:

A complex instruction set computer (CISC) architecture based on the VAXarchitecture

A reduced instruction set computer (RISC) architecture based on the Alphaarchitecture

The explicitly parallel instruction computing (EPIC) architecture used byItanium systems.

1.3.1.1 System Compatibility and Program Portability Across PlatformsThe OpenVMS Alpha and OpenVMS I64 operating systems are compatible withOpenVMS VAX systems in terms of user, system manager, and programmerenvironments. For general users and system managers, OpenVMS Alphaand OpenVMS I64 have the same interfaces as OpenVMS VAX. Virtually allOpenVMS VAX system management utilities, command formats, and tasksare identical in the OpenVMS Alpha and OpenVMS I64 environments. Mixed-architecture and mixed-version clusters that contain both Alpha systems and VAXsystems are supported.

1.3.2 OpenVMS Computing EnvironmentsThe OpenVMS operating system provides an array of capabilities that supportthe full range of computing environments. A computing environment is made upof resources that are compatible with each other and all work together toward acommon goal. In general, OpenVMS environments can supply the follow