CONTENTS Title Page Copyright Page Preface 1 Introduction 1.1 What Is a Portable Programming Interface? 1.2 Criteria for a Portable Programming Interface 1.3 Guidelines for Interface Design 2 An Architecture for Portable Programming Interfaces 2.1 Separating the Interface Definition from the Implementation 2.2 Defining the Interface Definition 2.3 Defining the Interface Implementation 2.3.1 VAX Calling Standard Binding 2.3.2 C Binding 2.3.3 f77 Binding 2.3.4 Noncompliant Bindings 3 Implementation of a Portable Programming Interface 3.1 Guidelines for Implementation 3.2 Procedures 3.2.1 Naming the Procedures 3.2.2 Implementing the Procedures 3.2.2.1 Implementing the Procedures on VMS Operating Systems 3.2.2.2 Implementing the Procedures on UNIX Operating Systems 3.2.2.3 Implementing the Procedures on Other Systems 3.3 Arguments 3.3.1 Allowable Data Types for Portable Interfaces 3.3.2 Passing Mechanisms 3.4 Return Values and Exception Handling 4 Naming Conventions 4.1 Purpose of Naming Conventions 4.2 Guidelines for Constructing Names 4.3 Procedure Names 4.3.1 Naming Public Procedures 4.3.2 Naming Private Procedures 4.4 Modules 4.5 Global Variables 4.6 Status Codes and Condition Values 4.7 Constants 4.8 Macros 4.9 Platform-Specific Conventions 5 Allowable Data Types 5.1 Atomic Data Types 5.1.1 Boolean 5.1.2 Character Data Types 5.1.2.1 ISO Latin-1 Character 5.1.2.2 ISO Multilingual Character 5.1.2.3 ISO Multioctet Character 5.1.3 Integer 5.1.4 Single-Precision Floating Point 5.1.5 Double-Precision Floating Point 5.1.6 Procedure 5.1.7 Typed Pointer 5.2 String Data Types 5.2.1 Fixed-Length ISO Latin-1 String (ISO Standard 8859-1) 5.2.2 Fixed-Length ISO Multilingual String (ISO DP 10646) 5.2.3 Fixed-Length ISO Multioctet String (ISO DP 10646) 5.2.4 Compound String 5.3 Miscellaneous Data Types 5.3.1 Structure 5.3.1.1 Designing Structures for Correct Alignment 5.3.1.2 Using Nested Structures 5.3.2 Discriminated Union 5.3.2.1 Designing Unions for Correct Alignment 5.3.3 Array 5.3.4 Opaque Object 5.4 Data Types Excluded from Portable Interfaces 6 Designing for Extensibility 6.1 Defining Extensibility 6.2 Extending the Functions of the Interface 6.3 Extending the Functions of a Procedure 6.3.1 Adding New Arguments 6.3.2 Modifying Existing Arguments 6.4 Identifying Versions 7 Guidelines for Documenting a Portable Programming Interface 7.1 Documenting Procedures for Portable Programming Interfaces 7.1.1 Name and Brief Description 7.1.2 Syntax 7.1.3 C Binding 7.1.4 Arguments 7.1.5 Description 7.1.6 Environment 7.1.7 Return Value 7.1.8 Examples 7.1.9 See Also 7.1.10 Interface-Specific Sections 7.2 Documenting Data Types for Portable Programming Interfaces 7.2.1 Naming NAS-Conforming Data Types 7.2.2 Naming Non-NAS-Conforming Data Types 7.3 Documenting Supplementary Information 7.3.1 Include Files 7.3.2 Data Structures 7.4 Documenting Noncompliant or Supplementary Interfaces 7.4.1 Documenting Noncompliant Interfaces 7.4.1.1 Documenting Interfaces with One Binding 7.4.1.2 Documenting Interfaces with Two Bindings 7.4.1.3 Documenting Interfaces with Three or More Bindings 7.4.2 Documenting Supplementary Bindings A Sample Programming Interface term_open_session term_close_session B New Features to Support the NAS Architecture B.1 New Features in VAX C B.2 Extensions to the VMS Linker Utility and Image Libraries B.3 Support for Lowercase Names in the VAX MACRO Assembler B.4 Documenting Portable Programming Interfaces B.5 Extending the Architecture to Additional Platforms B.6 Extending the Architecture to Additional Languages B.7 Making Callbacks to the Calling Application FIGURES 2-1 Separating the Interface Definition from the Implementation 3-1 Using a Jacket Routine to Share Source Code 5-1 Effects of Different Alignment Rules 5-2 Resolving Different Alignment Rules TABLES 3-1 Required Bindings 3-2 Data Type Passing Mechanisms