CONTENTS Title Page Copyright Page Preface 1 Overview of the LIB$ Facility 2 Access to VMS System Components 2.1 System Service Access Routines 2.2 Access to the Command Language Interpreter 2.2.1 Obtaining the Command Line 2.2.2 Chaining from One Program to Another 2.2.3 Executing a CLI Command 2.2.4 Using Symbols and Logical Names 2.2.5 Disabling and Enabling Control Characters 2.2.6 Creating and Connecting to a Subprocess 2.3 Access to VAX Machine Instructions 2.3.1 Variable-Length Bit Field Instruction Routines 2.3.2 Integer and Floating-Point Routines 2.3.3 Queue Access Routines 2.3.4 Character String Routines 2.3.5 Miscellaneous Instruction Routines 2.4 Processwide Resource Allocation Routines 2.4.1 Allocating Logical Unit Numbers 2.4.2 Allocating Event Flag Numbers 2.5 Performance Measurement Routines 2.6 Output Formatting Control Routines 2.7 Miscellaneous Interface Routines 2.7.1 Indicating Asynchronous System Trap in Progress 2.7.2 Assigning an I/O Channel Along with a Mailbox 2.7.3 Create a Directory or Subdirectory 2.7.4 File Searching Routines 2.7.5 Insert Entry in a Balanced Binary Tree 2.7.6 Common I/O Routines 3 Date/Time Manipulation 3.1 Date/Time Utility Routines 3.2 Date/Time Manipulation Routines 3.3 Date/Time Formatting Routines 3.3.1 Date/Time Logical Initialization 3.3.2 Selecting a Format 3.3.2.1 Run-Time Format Mnemonics 3.3.2.2 Specifying Formats at Run Time 3.3.2.2.1 Specifying Input Formats at Run Time 3.3.2.2.2 Specifying Output Formats at Run Time 3.3.2.3 Specifying Formats at Compile Time 3.3.2.3.1 Specifying Input Format Mnemonics at Compile Time 3.3.2.3.2 Specifying Output Formats at Compile Time 3.3.3 The LIB$CONVERT_DATE_STRING Routine 3.3.4 The LIB$GET_DATE_FORMAT Routine 3.3.5 User-Defined Output Formats 4 Condition Handling Routines 4.1 An Overview of the VAX Condition Handling Facility 4.1.1 Exception Conditions 4.1.2 The Condition Value 4.1.3 Signaling 4.1.3.1 Signal Argument Vector 4.1.3.2 Mechanism Argument Vector 4.1.4 Condition Handlers 4.1.4.1 Default Condition Handlers 4.1.4.2 Possible Condition Handler Actions 4.1.4.3 Interaction Between Default and User-Supplied Handlers 4.1.5 Displaying Messages 4.1.6 Multiple Active Signals 4.2 Using the VAX Condition Handling Facility 4.2.1 Establishing a Condition Handler 4.2.2 Writing a Condition Handler 4.2.2.1 Continuing Execution 4.2.2.2 Resignaling 4.2.2.3 Unwinding the Call Stack 4.2.3 Generating Signals 4.2.4 Signaling User-Defined Messages 4.2.5 Logging Error Messages to a File 4.3 Run-Time Library Condition Handling Routines 4.3.1 Convert a Floating-Point Fault to a Floating-Point Trap 4.3.2 Change a Signal to a Return Status 4.3.3 Change a Signal to a Stop 4.3.4 Match Condition Values 4.3.5 Correct a Reserved Operand Condition 4.3.6 Decode the Instruction That Generated a Fault 4.4 How Run-Time Library Routines Handle Exceptions 4.4.1 Exception Conditions Signaled from Mathematics Routines 4.4.1.1 Integer Overflow and Floating-Point Overflow 4.4.1.2 Floating-Point Underflow 4.4.2 Overflow/Underflow Detection Enabling Routines 5 Memory Allocation Routines 5.1 Overview 5.1.1 Virtual Address Space 5.1.2 Memory Allocation Routines 5.2 Allocating and Freeing Pages 5.3 Zones 5.3.1 Zone Attributes 5.3.2 The Default Zone 5.3.3 Zone Identification 5.3.4 Creating a Zone 5.3.5 Deleting a Zone 5.3.6 Resetting a Zone 5.4 Allocating and Freeing Blocks 5.5 Allocation Algorithms 5.5.1 The First Fit Algorithm 5.5.2 The Quick Fit Algorithm 5.5.3 The Frequent Sizes Algorithm 5.5.4 The Fixed Size Algorithm 5.6 User-Defined Zones 5.7 Interactions with Other Run-Time Library Routines 5.8 Interactions with VMS System Services 6 Debugging Programs That Use Virtual Memory Zones 7 Image Initialization and Termination 7.1 Image Initialization 7.2 Initialization Argument List 7.3 Declaring Initialization Routines 7.4 Dispatching to Initialization Routines 7.5 Initialization Routine Options 7.6 An Example 7.7 Image Termination 8 Cross-Reference Routines 8.1 Using the Cross-Reference Routines 8.2 $CRFCTLTABLE Macro 8.3 $CRFFIELD Macro 8.4 $CRFFIELDEND Macro 8.5 Cross-Reference Output 8.6 Example 8.6.1 Defining Control Tables 8.6.2 Inserting Table Information 8.6.3 Formatting Information for Output 8.7 How to Link to the Cross-Reference Shareable Image LIB$ Reference Section LIB$ADAWI LIB$ADD_TIMES LIB$ADDX LIB$ANALYZE_SDESC LIB$ASN_WTH_MBX LIB$AST_IN_PROG LIB$ATTACH LIB$BBCCI LIB$BBSSI LIB$CALLG LIB$CHAR LIB$CONVERT_DATE_STRING LIB$CRC LIB$CRC_TABLE LIB$CREATE_DIR LIB$CREATE_USER_VM_ZONE LIB$CREATE_VM_ZONE LIB$CRF_INS_KEY LIB$CRF_INS_REF LIB$CRF_OUTPUT LIB$CURRENCY LIB$CVT_DX_DX LIB$CVT_FROM_INTERNAL_TIME LIB$CVTF_FROM_INTERNAL_TIME LIB$CVT_TO_INTERNAL_TIME LIB$CVTF_TO_INTERNAL_TIME LIB$CVT_xTB LIB$CVT_VECTIM LIB$DATE_TIME LIB$DAY LIB$DAY_OF_WEEK LIB$DECODE_FAULT LIB$DEC_OVER LIB$DELETE_FILE LIB$DELETE_LOGICAL LIB$DELETE_SYMBOL LIB$DELETE_VM_ZONE LIB$DIGIT_SEP LIB$DISABLE_CTRL LIB$DO_COMMAND LIB$EDIV LIB$EMODD LIB$EMODF LIB$EMODG LIB$EMODH LIB$EMUL LIB$ENABLE_CTRL LIB$ESTABLISH LIB$EXTV LIB$EXTZV LIB$FFx LIB$FID_TO_NAME LIB$FILE_SCAN LIB$FILE_SCAN_END LIB$FIND_FILE LIB$FIND_FILE_END LIB$FIND_IMAGE_SYMBOL LIB$FIND_VM_ZONE LIB$FIXUP_FLT LIB$FLT_UNDER LIB$FORMAT_DATE_TIME LIB$FREE_DATE_TIME_CONTEXT LIB$FREE_EF LIB$FREE_LUN LIB$FREE_TIMER LIB$FREE_VM LIB$FREE_VM_PAGE LIB$GETDVI LIB$GETJPI LIB$GETQUI LIB$GETSYI LIB$GET_COMMAND LIB$GET_COMMON LIB$GET_DATE_FORMAT LIB$GET_EF LIB$GET_FOREIGN LIB$GET_INPUT LIB$GET_LUN LIB$GET_MAXIMUM_DATE_LENGTH LIB$GET_SYMBOL LIB$GET_USERS_LANGUAGE LIB$GET_VM LIB$GET_VM_PAGE LIB$ICHAR LIB$INDEX LIB$INIT_DATE_TIME_CONTEXT LIB$INIT_TIMER LIB$INSERT_TREE LIB$INSQHI LIB$INSQTI LIB$INSV LIB$INT_OVER LIB$LEN LIB$LOCC LIB$LOOKUP_KEY LIB$LOOKUP_TREE LIB$LP_LINES LIB$MATCHC LIB$MATCH_COND LIB$MOVC3 LIB$MOVC5 LIB$MOVTC LIB$MOVTUC LIB$MULT_DELTA_TIME LIB$MULTF_DELTA_TIME LIB$PAUSE LIB$POLYD LIB$POLYF LIB$POLYG LIB$POLYH LIB$PUT_COMMON LIB$PUT_OUTPUT LIB$RADIX_POINT LIB$REMQHI LIB$REMQTI LIB$RENAME_FILE LIB$RESERVE_EF LIB$RESET_VM_ZONE LIB$REVERT LIB$RUN_PROGRAM LIB$SCANC LIB$SCOPY_DXDX LIB$SCOPY_R_DX LIB$SET_LOGICAL LIB$SET_SYMBOL LIB$SFREE1_DD LIB$SFREEN_DD LIB$SGET1_DD LIB$SHOW_TIMER LIB$SHOW_VM LIB$SHOW_VM_ZONE LIB$SIGNAL LIB$SIG_TO_RET LIB$SIG_TO_STOP LIB$SIM_TRAP LIB$SKPC LIB$SPANC LIB$SPAWN LIB$STAT_TIMER LIB$STAT_VM LIB$STOP LIB$SUB_TIMES LIB$SUBX LIB$SYS_ASCTIM LIB$SYS_FAO LIB$SYS_FAOL LIB$SYS_GETMSG LIB$TPARSE LIB$TRA_ASC_EBC LIB$TRA_EBC_ASC LIB$TRAVERSE_TREE LIB$TRIM_FILESPEC LIB$VERIFY_VM_ZONE LIB$WAIT EXAMPLES 5-1 Monitoring Heap Operations with a User-Defined Zone FIGURES 2-1 Variable-Length Bit Field 4-1 Format of the Condition Value 4-2 Sample Stack Scan for Condition Handlers 4-3 Format of the Signal Argument Vector 4-4 Signal Argument Vector for the Reserved Operand Error Conditions 4-5 Signal Argument Vector for RTL Mathematics Routine Errors 4-6 Format of a Mechanism Argument Vector 4-7 Interaction Between Handlers and Default Handlers 4-8 Formats of Message Sequences 4-9 Stack After Second Exception Condition Is Signaled 4-10 Arguments Passed to Condition Handler During Unwind 4-11 Using a Condition Handler to Log an Error Message 5-1 Virtual Address Overview 5-2 Hierarchy of Memory Management Routines 5-3 Memory Fragmentation 5-4 Boundary Tags 7-1 Sequence of Events During Image Initialization 8-1 Using Cross-Reference Routines 8-2 Summary of Symbol Names and Values 8-3 Summary of Symbol Names, Values, and Name of Referring Modules 8-4 Summary Indicating Defining Module LIB-1 Structure of a Protection Mask LIB-2 Summary of Symbol Names and Values LIB-3 Summary of Symbol Names, Values, and Name of Referring Modules LIB-4 Summary Indicating Defining Module LIB-5 Acceptable Subset of VAX Standard Data Types LIB-6 Data Types Accepted by LIB$CVT_DX_DX LIB-7 Keyword Table LIB-8 LIB$AB_ASC_EBC LIB-9 LIB$AB_ASC_EBC_REV LIB-10 LIB$AB_EBC_ASC LIB-11 LIB$AB_EBC_ASC_REV LIB-12 LIB$AB_CVTPT_O LIB-13 LIB$AB_CVTPT_U LIB-14 LIB$AB_CVTTP_O LIB-15 LIB$AB_CVTTP_U LIB-16 LIB$AB_CVT_O_U LIB-17 LIB$AB_CVT_U_O LIB-18 LIB$AB_CVTPT_Z LIB-19 LIB$AB_CVTTP_Z LIB-20 LIB$AB_UPCASE LIB-21 LIB$AB_LOWERCASE LIB-22 LIB$TPARSE Argument Block LIB-23 Transition Diagram for the Mythical Utility LIB-24 Diagram of the Mythical Utility LIB-25 LIB$AB_ASC_EBC LIB-26 LIB$AB_EBC_ASC TABLES 1-1 LIB$ Routines 2-1 System Service Access Routines 2-2 CLI Access Routines 2-3 Variable Bit Field Routines 2-4 Integer and Floating-Point Routines 2-5 Queue Access Routines 2-6 Character String Routines 2-7 Miscellaneous Instruction Routines 2-8 Processwide Resource Allocation Routines 2-9 Performance Measurement Routines 2-10 The Code Argument in LIB$SHOW_TIMER and LIB$STAT_TIMER 2-11 Routines for Customizing Output 2-12 Miscellaneous Interface Routines 3-1 Date/Time Formatting Routines 3-2 Available Languages 3-3 Format Mnemonics 3-4 Input String Punctuation and Defaults 3-5 Predefined Output Date Formats 3-6 Predefined Output Time Formats 3-7 Available Components 3-8 Legible Format Mnemonics 3-9 Example Input Format Strings 4-1 Condition Handling and Signaling Routines 4-2 Fields in a Condition Value 5-1 Overhead for Area Control Blocks 5-2 Possible Values for the Block Size Attribute 5-3 Attribute Values for the Default Zone 5-4 Allocation Algorithms 8-1 Cross-Reference Routines LIB-1 Destination NBDS Formats LIB-2 Symbols for Fields and Values for Operand Access and Data Types LIB-3 Formats Used for LIB$GETDVI Strings LIB-4 Item Code Formats for LIB$GETJPI LIB-5 Item Code Formats for LIB$GETQUI LIB-6 LIB$SHOW_VM_ZONE Error Messages LIB-7 The Alphabet of LIB$TPARSE LIB-8 Argument Block Fields LIB-9 Symbol Types Accepted by LIB$TPARSE