CONTENTS Title Page Copyright Page Preface 1 Introduction to Modular Procedures 1.1 Defining the Modular Procedure 1.2 Existing VMS System Procedures 1.2.1 Run-Time Library Procedures 1.2.2 System Services 1.2.3 Utility Routines 1.2.4 Record Management Services 1.3 Tools for Developing Applications on VMS 2 Design 2.1 Organizing New Applications 2.1.1 Organizing Files and Modules 2.1.2 Organizing Procedures into Modules 2.2 Defining a Modular Procedure Interface 2.2.1 Explicit Arguments 2.2.2 Implicit Arguments 2.2.2.1 Implicit Arguments Allocated by the Calling Program 2.2.2.2 Implicit Arguments Allocated by the Called Procedure 2.2.3 How to Avoid Using Implicit Arguments 2.2.3.1 Combining Procedures 2.2.3.2 User Action Routine 2.2.3.3 Designating Responsibility to the Calling Program 2.2.4 Order of Arguments 2.2.5 Using Optional Arguments 2.3 JSB Entry Points 2.4 Using System Resources 2.4.1 Choosing a Storage Type 2.4.1.1 Stack Storage 2.4.1.2 Heap Storage 2.4.1.3 Static Storage 2.4.1.4 Avoiding Use of Static Storage 2.4.1.5 Summary of Storage Use by Language 2.4.2 Using Event Flags 2.4.3 Using Logical Unit Numbers 2.5 Using Input/Output 2.5.1 Terminal Input/Output 2.5.2 File Input/Output 2.6 Beginning the Internal Documentation 2.6.1 How to Write a Module Description 2.6.2 How to Write a Procedure Description 2.7 Planning for Signaling and Condition Handling 2.7.1 Guidelines for Signaling Error Conditions 2.7.2 Guidelines for Returning Condition Values 2.7.3 When to Signal or Return Condition Values 3 Coding 3.1 Coding Guidelines 3.1.1 Writing Position-Independent Code (Required) 3.1.2 Adhering to the Naming Conventions 3.1.2.1 Facility Naming Conventions (Recommended) 3.1.2.2 Procedure Naming Conventions (Recommended) 3.1.2.3 File Naming Conventions (Recommended) 3.1.2.4 Module Naming Conventions (Required) 3.1.2.5 PSECT Naming Conventions (Required) 3.1.2.6 Lock Resource Naming Conventions (Recommended) 3.1.2.7 Global Variable Naming Conventions (Recommended) 3.1.2.8 Status Code and Condition Value Naming Conventions (Required) 3.1.3 Using Common Source Files (Recommended) 3.1.4 Maintaining Code Readability 3.1.4.1 Using Symbols in Place of Numbers (Recommended) 3.1.4.2 Using Uppercase and Lowercase Characters (Recommended) 3.1.4.3 Adding Optional Spaces (Recommended) 3.1.4.4 Inserting Block Comments (Recommended) 3.1.5 Using VMS System Services 3.1.6 Invoking Optional User Action Routines 3.1.6.1 Procedure Entry Mask 3.1.6.2 Bound Procedure Value 3.2 Initializing Modular Procedures 3.2.1 Initializing Storage 3.2.2 Testing and Setting a First-Time Flag 3.2.3 Using LIB$INITIALIZE 3.3 Writing AST-Reentrant Code 3.3.1 What is an AST? 3.3.2 AST-Reentrancy Versus Full-Reentrancy 3.3.3 Guidelines for Writing AST-Reentrant Modular Procedures 3.3.4 How to Eliminate Race Conditions During Concurrent Access 3.3.4.1 Performing All Accesses in One Instruction 3.3.4.2 Using "Test and Set" Instructions 3.3.4.3 Keeping a Call-in-Progress Count 3.3.4.4 Disabling AST Interrupts 3.3.5 Performing Input/Output at AST-Level 3.3.6 Condition Handling at AST Level 4 Testing 4.1 Unit Testing 4.1.1 Black Box Testing 4.1.2 White Box Testing 4.2 Language-Independence Testing 4.3 Integration Testing 4.3.1 The "All at Once" Approach to Integration Testing 4.3.2 The Incremental Approach to Integration Testing 4.4 Testing for Reentrancy 4.4.1 Checking for AST Reentrancy 4.4.1.1 Checking for AST Reentrancy using the Debugger 4.4.1.2 Checking for AST Reentrancy by Desk Checking 4.4.2 Checking for Full Reentrancy 4.5 Performance Analysis 4.5.1 SHOW Entry Point 4.5.2 STAT Entry Point 4.6 Monitoring Procedures in the Run-Time Library 5 Integration 5.1 Creating Facility Prefixes 5.2 Creating Object Module Libraries 5.3 Shareable Library Images 5.3.1 Creating Shareable Library Images 5.3.2 Creating the Transfer Vector 5.3.3 Creating the Linker Options File 5.3.4 Creating the Shareable Library Image 5.3.5 Combining Shareable Images into a Shareable Image Library 5.4 Linking to Libraries of Modular Procedures 6 Maintenance 6.1 Making Your Procedures Upwardly Compatible 6.2 Regression Testing 6.2.1 Updating the Transfer Vector 6.3 Adding Arguments to Existing Routines 6.3.1 Adding New Arguments to the Procedure 6.3.2 Using Argument Blocks 6.4 Updating Libraries 6.4.1 Updating Object Libraries 6.4.2 Updating Shareable Images 6.4.2.1 Changing the Transfer Vector 6.4.2.2 Updating the Linker Options File 6.4.3 Updating Shareable Image Libraries A VMS Modular Programming Standard A.1 Purpose of this Standard A.2 Applicability A.3 Coding Rules A.3.1 The Calling Interface A.3.2 Initialization A.3.3 Reporting Exception Conditions A.3.4 AST Reentrancy A.3.5 Resource Allocation A.3.6 The Format and Content of Coded Modules A.3.7 Shareable Images A.3.8 Upward Compatibility B Argument Characteristics B.1 VMS Usage B.2 Data Type B.3 Access Mechanism B.4 Passing Mechanisms EXAMPLES 2-1 FORTRAN Program Showing the Improper Use of Implicit Arguments 2-2 FORTRAN Program Combining Procedures to Avoid Implicit Arguments 2-3 Static Storage and AST Reentrancy 2-4 A Sample Module Description 2-5 A Sample Procedure Description 3-1 A Sample Cross-Reference Listing Showing the References to the Symbol SPEED_OF_LIGHT 3-2 PASCAL Program Showing Use of Uppercase and Lowercase Characters in Code 3-3 BASIC Program Showing Use of Optional Spaces in Code 3-4 FORTRAN Program Showing Use of Block Comments in Code 3-5 PASCAL Program Which Uses a First-Time Flag 3-6 BASIC Initialization Procedure for LIB$INITIALIZE 3-7 Program to Add Address to PSECT LIB$INITIALIZE 3-8 BASIC Main Program 3-9 MACRO Program Showing Use of Queue Instructions to Perform All Accesses in a Single Instruction 3-10 MACRO Program Showing Use of Test and Set Instructions 3-11 A FORTRAN Program Disabling and Restoring ASTs 5-1 Transfer Vector Template 5-2 Template for a Linker Options File FIGURES 1-1 The Software Life Cycle 1-2 Developing a Program that Calls Library Procedures 1-3 Procedures Available in the Run-Time Library 2-1 Levels of Abstraction 2-2 Possible Procedure Groupings 2-3 Designating Storage Responsibility to the Caller 2-4 Use of Storage Types 3-1 Examples of Facility Prefixes as Used in Procedure Names 3-2 Methods of Initializing 3-3 How to Initialize Static Storage 4-1 Black Box Testing Methods 4-2 White Box Testing Methods 4-3 A Sample Procedure for Integration Testing 5-1 Development of a User-Created Object Module Library 5-2 Creating a Shareable Image 6-1 Regression Testing 6-2 One Type of Argument Block, the Signal Argument Vector B-1 Procedure Argument Passing Mechanisms TABLES 2-1 Summary of Storage Use by Language 3-1 Common Library Facilities - Prefixes and Content 3-2 Naming Procedure Entry Points 3-3 Code for the Content and Usage of Global Variables 3-4 How to Declare Common Source Files B-1 VMS Data Structures B-2 VAX Standard Data Types B-3 VAX Standard Passing Mechanisms