CONTENTS Title Page Copyright Page Preface 1 Introduction to System Services 1.1 Documentation Format for System Service Routines 1.1.1 Format Heading 1.1.2 Returns Heading 1.1.3 Arguments Heading 1.1.3.1 VMS Usage Entry 1.1.3.2 Type Entry 1.1.3.3 Access Entry 1.1.3.4 Mechanism Entry 1.1.3.5 Explanatory Text Entry 1.1.4 Condition Values Returned Heading 1.1.5 Condition Values Returned in the I/O Status Block Heading 2 Calling System Services 2.1 System Services and System Integrity 2.1.1 User Privileges 2.1.2 Resource Quotas 2.1.3 Access Modes 2.2 Determining Arguments for System Services 2.3 Obtaining Values for Symbolic Codes 2.4 Calling System Services from VAX MACRO 2.4.1 Using Macros to Construct Argument Lists 2.4.1.1 Specifying Arguments with the $name_S Macro and the $name Macro 2.4.1.2 Conventions for Specifying Arguments to System Services 2.4.1.3 Defining Symbolic Names for Argument List Offsets: $name and $nameDEF 2.4.2 Using Macros to Call System Services 2.4.2.1 The $name_S Macro 2.4.2.2 Example of $name_S Macro Call 2.4.2.3 The $name_G Macro 2.4.2.4 Example of $NAME and $name_G Macro Calls 2.5 System Service Completion 2.5.1 Synchronous and Asynchronous System Services 2.5.2 Process Execution Modes 2.5.2.1 Resource Wait Mode 2.6 Condition Values Returned from System Services 2.6.1 Information Provided by Condition Values 2.7 Testing Return Condition Values 2.7.1 System Messages Generated by Condition Values 2.8 High-Level Language Calls 2.8.1 Testing Return Condition Values in High-Level Languages 2.9 Interpreting the Programming Examples 3 Security Services 3.1 Overview of the VMS Protection Scheme 3.2 Identifiers 3.2.1 Identifier Format 3.2.2 Identifier Names 3.2.3 System-Defined Identifiers 3.2.4 General Identifiers 3.2.5 Identifier Attributes 3.3 Rights Database 3.3.1 Initializing a Rights Database 3.3.2 Using System Services to Affect a Rights Database 3.3.2.1 Translating Identifier Names and Binary Values 3.3.2.2 Adding Identifiers and Holders to Rights Database 3.3.2.3 Determining Holders of Identifiers 3.3.2.4 Determining Identifiers Held 3.3.2.5 Modifying the Identifier Record 3.3.2.6 Modifying a Holder Record 3.3.2.7 Removing Identifiers and Holders from the Rights Database 3.3.3 Search Operations 3.4 Creating, Translating, and Maintaining Access Control List Entries 3.4.1 Format of ACE Types 3.4.1.1 Alarm ACE 3.4.1.2 Application-Dependent ACE 3.4.1.3 Default Protection ACE 3.4.1.4 Identifier ACE 3.4.2 Translating ACEs 3.4.3 Creating and Maintaining ACEs 3.5 Modifying a Rights List 3.6 Checking Access Protection 3.6.1 SYS$CHKPRO 3.6.2 SYS$CHECK_ACCESS 3.7 Additional Security Services 4 Event Flag Services 4.1 Event Flag Numbers and Event Flag Clusters 4.2 Examples of Event Flag Services 4.3 Event Flag Waits 4.4 Setting and Clearing Event Flags 4.5 Creating Common Event Flag Clusters 4.6 Disassociating and Deleting Common Event Flag Clusters 4.7 Example of Using a Common Event Flag Cluster 4.8 Cluster Name 4.9 Example of Using Event Flag Services 5 AST (Asynchronous System Trap) Services 5.1 Access Modes for AST Execution 5.2 ASTs and Process Wait States 5.2.1 Event Flag Waits 5.2.2 Hibernation 5.2.3 Resource Waits and Page Faults 5.3 How ASTs Are Declared 5.4 The AST Service Routine 5.5 AST Delivery 5.6 Example of Using AST Services 6 Name Services 6.1 Logical Name System Services 6.1.1 Logical Names and Equivalence Names 6.1.2 Logical Name Tables 6.1.2.1 Logical Name Directory Tables 6.1.2.2 Default Logical Name Tables 6.1.2.3 User-Defined Logical Name Tables 6.1.3 Privileges 6.1.4 Access Modes 6.1.5 Attributes 6.1.6 Logical Name Table Quotas 6.1.6.1 Directory Table Quotas 6.1.6.2 Default Logical Name Table Quotas 6.1.6.3 Job Logical Name Table Quotas 6.1.6.4 User-Defined Logical Name Table Quotas 6.1.7 Logical Name and Equivalence Name Format Conventions 6.1.8 Specifying the Logical Name Table Search List 6.2 Creating a Logical Name-$CRELNM 6.2.1 Duplication of Logical Names 6.3 Creating Logical Name Tables-$CRELNT 6.3.1 Shareable Logical Name Tables 6.3.2 $CRELNT System Service Call 6.4 Deleting Logical Names-$DELLNM 6.5 Translating Logical Names-$TRNLNM 6.6 Example of Using the Logical Name System Services 6.7 The DECdns Clerk System Service 6.7.1 Functions Provided by the DECdns System Service and Run-Time Library Routines 6.7.1.1 The $DNS System Service 6.7.1.2 The Run-Time Library Routines 6.8 Using the $DNS System Service Call 6.8.1 Creating Objects 6.8.2 Modifying Objects and Their Attributes 6.8.3 Requesting Information from DECdns 6.8.3.1 Reading Attributes 6.8.3.2 Enumerating DECdns Names and Attributes 6.9 DECdns Logical Names 7 Input/Output Services 7.1 Quotas, Privileges, and Protection 7.1.1 Buffered I/O Quota 7.1.2 Buffered I/O Byte Count Quota 7.1.3 Direct I/O Quota 7.1.4 AST Quota 7.1.5 Physical I/O Privilege 7.1.6 Logical I/O Privilege 7.1.7 Mount Privilege 7.1.8 Volume Protection 7.1.9 Device Protection 7.1.10 System Privilege 7.1.11 Bypass Privilege 7.2 Summary of VMS QIO Operations 7.3 Physical, Logical, and Virtual I/O 7.3.1 Physical I/O Operations 7.3.2 Logical I/O Operations 7.3.3 Virtual I/O Operations 7.4 I/O Function Encoding 7.4.1 Function Codes 7.4.2 Function Modifiers 7.5 Assigning Channels 7.6 Queuing I/O Requests 7.7 Synchronizing Service Completion 7.8 Recommended Method for Testing Asynchronous Completion 7.9 Synchronous Forms of Input/Output Services 7.10 I/O Completion Status 7.11 Deassigning I/O Channels 7.12 Example of Using Complete Terminal I/O 7.13 Canceling I/O Requests 7.14 Device Allocation 7.14.1 Implicit Allocation 7.14.2 Deallocation 7.15 Mounting, Dismounting, and Initializing Volumes 7.15.1 Mounting a Volume 7.15.1.1 Calling the $MOUNT System Service 7.15.1.2 Calling the $DISMOU System Service 7.15.2 Initializing Volumes 7.15.2.1 Calling the Initialize Volume System Service 7.16 Logical Names and Physical Device Names 7.17 Device Name Defaults 7.18 Obtaining Information About Physical Devices 7.19 Formatting Output Strings 7.20 Mailboxes 7.20.1 Mailbox Name 7.20.2 System Mailboxes 7.20.3 Mailboxes for Process Termination Messages 7.21 Example of Using I/O Services 8 Process Control Services 8.1 Subprocesses and Detached Processes 8.2 The Execution Context of a Process 8.3 Process Creation 8.3.1 Defining an Image for a Subprocess to Execute 8.3.2 Input, Output, and Error Devices for Subprocesses 8.3.3 Disk and Directory Defaults for Created Processes 8.3.4 Controlling Resources of Created Processes 8.3.5 Detached Processes 8.4 Interprocess Control and Communication 8.4.1 Privileges for Process Creation and Control 8.4.2 Process Identification 8.4.2.1 Process Naming Within Groups 8.4.3 Techniques for Interprocess Communication 8.5 Process Hibernation and Suspension 8.5.1 Process Hibernation 8.5.2 Alternate Methods of Hibernation 8.5.3 Suspension 8.6 Image Exit 8.6.1 Image Rundown Activities 8.6.2 The $EXIT System Service 8.6.3 Exit Handlers 8.6.4 Forced Exit 8.7 Process Deletion 8.7.1 The Delete Process System Service 8.7.2 Termination Mailboxes 8.8 Example of Using Process Control Services 9 Process Information Services 9.1 Overview of $GETJPI and $GETJPI with $PROCESS_SCAN 9.1.1 Using the Process ID to Obtain Information 9.1.2 Using the Process Name to Obtain Information 9.2 Using $GETJPI Alone 9.2.1 Requesting Information About a Single Process 9.2.2 Requesting Information About All Processes on the Local System 9.3 Using $GETJPI with $PROCESS_SCAN 9.3.1 Using the $PROCESS_SCAN Item List and Item-Specific Flags 9.3.2 Requesting Information About Processes That Match One Criterion 9.3.3 Requesting Information About Processes That Match Multiple Values for One Criterion 9.3.4 Requesting Information About Processes That Match Multiple Criteria 9.3.5 Specifying a Node as Selection Criterion 9.3.6 Scanning All Nodes on the Cluster for Processes 9.3.7 Scanning Specific Nodes on the Cluster for Processes 9.3.8 Conducting Multiple Simultaneous Searches with $PROCESS_SCAN 9.4 Programming Considerations 9.4.1 Using Item Lists Correctly 9.4.2 Improving Performance by Using Buffered $GETJPI Operations 9.4.3 Meeting Remote $GETJPI Quota Requirements 9.4.4 Using $GETJPI Control Flags 10 Timer and Time Conversion Services 10.1 The System Time Format 10.2 Obtaining the Current Date and Time 10.3 Obtaining an Absolute Time in System Format 10.4 Obtaining a Delta Time in System Format 10.5 Timer Requests 10.6 Scheduled Wakeups 10.7 Numeric and ASCII Time 10.8 Setting the System Time 10.9 Example of Using the Timer Service 11 Condition-Handling Services 11.1 Types of Exception 11.2 Specifying Condition Handlers 11.3 The Exception Dispatcher 11.4 The Argument List Passed to a Condition Handler 11.4.1 Signal Array Arguments 11.4.2 Mechanism Array Arguments 11.5 Courses of Action for the Condition Handler 11.5.1 Example of Condition-Handling Routines 11.5.2 Unwinding the Call Stack 11.6 Multiple Exceptions 11.7 Example of Using Condition-Handling Services 12 Memory Management Services 12.1 Virtual Address Space 12.2 Increasing and Decreasing Virtual Address Space 12.3 Input Address Arrays and Return Address Arrays 12.4 Page Ownership and Page Protection 12.5 Working Set Paging 12.6 Process Swapping 12.7 Sections 12.7.1 Creating Sections 12.7.2 Opening the Disk File 12.7.3 Defining the Section Extents 12.7.4 Defining the Section Characteristics 12.7.5 Defining Global Section Characteristics 12.7.6 Global Section Name 12.7.7 Mapping Sections 12.7.8 Mapping Global Sections 12.7.9 Global Page-File Sections 12.7.10 Section Paging 12.7.11 Reading and Writing Data Sections 12.7.12 Releasing and Deleting Sections 12.7.13 Writing Back Sections 12.7.14 Image Sections 12.7.15 Page Frame Sections 12.8 Example of Using Memory Management System Services 13 Lock Management Services 13.1 Concepts of Resources and Locks 13.1.1 Granularity 13.1.2 Resource Names 13.1.3 Choosing a Lock Mode 13.1.4 Levels of Locking and Compatibility 13.1.5 Lock Management Queues 13.1.6 Lock Conversion Concepts 13.1.7 Deadlock Detection 13.2 Queuing Lock Requests 13.3 Advanced Locking Techniques 13.3.1 Synchronizing Locks 13.3.2 Notification of Synchronous Completion 13.3.3 Expediting Lock Requests 13.3.4 Lock Status Block 13.3.5 Blocking ASTs 13.3.6 Lock Conversions 13.3.7 Forced Queuing of Conversions 13.3.8 Parent Locks 13.3.9 Lock Value Blocks 13.4 Dequeuing Locks 13.5 Local Buffer Caching with the Lock Management Services 13.5.1 Using the Lock Value Block 13.5.2 Using Blocking ASTs 13.5.2.1 Deferring Buffer Writes 13.5.2.2 Buffer Caching 13.5.3 Choosing a Buffer Caching Technique 13.6 Example of Using Lock Management Services 14 DECdtm Services 14.1 Using Transaction Management System Services 14.1.1 Transaction Processing System Model 14.1.2 Transaction Management 14.1.3 Starting a Transaction 14.1.4 Completing a Transaction 14.1.5 Calling a Planned Abort 14.1.6 Example of Using Transaction Management System Services 15 Programming Examples 15.1 ORION Program Example 15.2 CYGNUS Program Example 15.3 LYRA Program Example A User-Written System Services A.1 Coding a User-Written System Service A.1.1 Change-Mode Vector A.1.2 Entry Point to the User-Written System Service A.1.3 Kernel-Mode or Executive-Mode Dispatcher A.1.4 Enabling and Disabling User Privileges A.2 Linking the User-Written System Service A.2.1 Specifying Protection for the Image or Clusters A.3 Installing the User-Written System Service A.4 Using the User-Written System Service A.5 Program Listings B Using Shared Memory B.1 Preparing Multiport Memory for Use B.2 Privileges Required for Shared Memory Use B.3 Naming Facilities in Shared Memory B.4 Assigning Logical Names and Logical Name Translation B.5 How VMS Finds Facilities in Shared Memory B.6 Using Common Event Flags in Shared Memory B.7 Using Mailboxes in Shared Memory B.8 Using Global Sections in Shared Memory B.8.1 Removing Shared Memory Global Sections B.8.2 Create and Map Section System Service C Implementing Site-Specific Security Policies C.1 Creating Loadable Security Services C.1.1 Preparing and Loading a System Service C.1.2 Removing an Executive Loaded Image C.2 Installing Site-Specific Password Policy Filters C.2.1 Creating a Shareable Image C.2.2 Installing a Shareable Image EXAMPLES 2-1 Interpreting MACRO Examples 9-1 Using $GETJPI to Obtain Information About the Calling Process 9-2 Using $GETJPI and the Process Name to Obtain Information About a Process 9-3 Using $GETJPI to Request Information About All Processes on the Local System 9-4 Using $GETJPI and $PROCESS_SCAN to Select Process Information by User Name 9-5 Using $GETJPI and $PROCESS_SCAN with Multiple Values for One Criterion 9-6 Selecting Processes That Match Multiple Criteria 9-7 Searching the Cluster for Process Information 9-8 Searching for Process Information on Specific Nodes in the Cluster 9-9 Using a $GETJPI Buffer to Improve Performance 9-10 Using $GETJPI Control Flags to Avoid Swapping a Process into the Balance Set 14-1 Using Transaction Management Services FIGURES 2-1 Procedure Argument Passing Mechanisms 3-1 Flowchart of $CHKPRO Operation 7-1 Files-11 Volume Protection Fields 7-2 Foreign Volume Protection Fields 7-3 Mailbox Protection Fields 7-4 Physical I/O Access Checks 7-5 Logical I/O Access Checks 7-6 Physical, Logical, and Virtual I/O 7-7 I/O Function Format 7-8 Function Modifier Format 7-9 I/O Status Block 7-10 $MOUNT Item Descriptor 8-1 Image Exit and Process Deletion 11-1 Search of Stack for Condition Handler 11-2 Argument List and Arrays Passed to Condition Handler 11-3 Unwinding the Call Stack 12-1 Layout of Process Virtual Address Space 13-1 Model Database 13-2 Three Lock Queues 13-3 A Deadlock 13-4 The Lock Status Block 14-1 Transaction Processing Components TABLES 1-1 Main Headings in the Routine Template 1-2 Language Conventions for Optional Arguments 3-1 ACE Type-Independent Information 4-1 Summary of Event Flag and Cluster Numbers 6-1 Summary of Privileges 7-1 Read and Write I/O Functions 7-2 Default Device Names for I/O Services 8-1 Process Identification 8-2 Process Hibernation and Suspension 11-1 Summary of Exception Conditions 12-1 Sample Virtual Address Arrays 12-2 Flag Bits to Set for Specific Section Characteristics 13-1 Compatibility of Lock Modes 13-2 Legal QUECVT Conversions 13-3 Effect of Lock Conversion on Lock Value Block