CONTENTS Title Page Copyright Page Preface New and Changed Features 1 Introduction to the VAX Ada Program Development Environment 1.1 Getting Started with VAX Ada 1.1.1 Creating a Working Directory and Defining a Current Default Directory 1.1.2 Creating a Source File 1.1.3 Creating a Program Library 1.1.4 Defining the Current Program Library 1.1.5 Compiling the Program 1.1.6 Displaying Unit Information 1.1.7 Linking the Program 1.1.8 Executing the Program 1.1.9 Debugging the Program 1.1.10 Compiling and Recompiling a Modified Program 1.2 Using the VAX Ada Program Library Manager 1.2.1 Overview of ACS Commands 1.2.2 Entering ACS Commands 1.2.3 Exiting from the Program Library Manager and Interrupting ACS Commands 1.2.4 Defining Synonyms for ACS Commands 1.2.5 Using DCL Commands with Program Libraries 1.3 Concepts and Terminology 1.3.1 Program and Compilation Units 1.3.1.1 Compilation Unit Dependences 1.3.1.2 Current and Obsolete Units 1.3.1.3 Unit and File-Name Conventions 1.3.2 Order-of-Compilation Rules 1.3.3 Closure 2 Working with VAX Ada Program Libraries and Sublibraries 2.1 Program Library and Sublibrary Operations 2.1.1 Creating a Program Library or Sublibrary 2.1.2 Defining the Current Program Library 2.1.3 Identifying the Current Program Library 2.1.4 Obtaining Library Information 2.1.5 Controlling Library Access 2.1.5.1 Read-Only Access 2.1.5.2 Exclusive Access 2.1.6 Deleting a Program Library or Sublibrary 2.2 Unit Operations 2.2.1 Specifying Units in ACS Commands 2.2.2 Displaying General Unit Information 2.2.3 Displaying Dependence and Portability Information 2.2.4 Checking Unit Currency and Completeness 2.2.5 Using Units from Other Program Libraries 2.2.5.1 Copying Units into the Current Program Library 2.2.5.2 Entering Units into the Current Program Library 2.2.6 Introducing Foreign (Non-Ada) Code into a Library 2.2.7 Deleting Units from the Current Program Library 2.3 Using Program Sublibraries 2.3.1 Using ACS Commands with Program Sublibraries 2.3.2 Creating a Nested Sublibrary Structure 2.3.3 Changing the Parent of a Sublibrary 2.3.4 Merging Modified Units into the Parent Library 2.3.5 Modifying and Testing Units in a Sublibrary Environment 3 Compiling and Recompiling VAX Ada Programs 3.1 Compiling Units into a Program Library 3.2 Recompiling Obsolete Units 3.3 Completing Incomplete Generic Instantiations 3.4 Compiling a Modified Program 3.5 Forcing the Compilation or Recompilation of a Set of Units 3.6 Using Search Lists for External Source Files 3.7 Choosing Optimization Options 3.8 Processing and Output Options 3.8.1 Executing Compilations in Batch Mode 3.8.2 Saving the Load or Compiler Command File 3.8.3 Loading Units and Executing Compilations in a Subprocess 3.8.4 Conventions for Defaults, Symbols, and Logical Names 3.8.5 Directing Program Library Manager and Compiler Output 3.9 Compiler Diagnostic Messages 3.9.1 Diagnostic Messages and Their Severity 3.9.2 Informational Messages and the /[NO]WARNINGS Qualifier 3.9.3 Setting Compiler Error Limits 3.10 Compiler Listing Format 4 Linking Programs 4.1 Linking Programs Having Only VAX Ada Units 4.2 Linking Mixed-Language Programs 4.2.1 Using the ACS COPY FOREIGN and ENTER FOREIGN Commands 4.2.2 Using the ACS LINK Command 4.2.3 Using the ACS EXPORT and DCL LINK Commands 4.3 Processing and Output Options 4.3.1 Conventions for Defaults, Symbols, and Logical Names 4.3.2 Executing the Link Operation in a Subprocess or in Batch Mode 4.3.3 Saving the Linker Command File and Package Elaboration File 5 Managing Program Development 5.1 Decomposing Your Program for Efficient Development 5.2 Setting up an Efficient Program Library Structure 5.3 Integration with Other VAX Tools 5.3.1 Setting up Source Code Directories 5.3.2 Managing Source Code Modifications 5.4 System Considerations 5.5 Distributed Programming Considerations 5.5.1 Configuring a Library Structure Across DECnet 5.5.2 Accessing a Program Library Across DECnet 5.5.3 Achieving Efficient DECnet Access to Program Libraries 5.5.4 Effect of Network Failures 5.5.5 Restrictions on Using Program Libraries Across DECnet 5.6 Protecting Program Libraries 5.6.1 Program-Library Access Requirements for ACS Commands 5.6.2 Standard User-Identification-Code (UIC) Based Program Library Protection 5.6.3 Program Library Protection Through Access Control Lists 5.7 Maintaining Program Libraries 5.7.1 Making References to Program Libraries Independent of Specific Devices and Directories 5.7.1.1 Using Concealed-Device Logical Names 5.7.1.2 Using Rooted Directory Syntax 5.7.2 Copying Program Libraries 5.7.3 Backing Up and Restoring Program Libraries 5.7.4 Reorganizing Program Libraries 5.7.5 Verifying and Repairing Program Libraries 5.7.6 Recompiling Units After a New Release or Update of VAX Ada 5.8 Working with Multiple Targets 5.8.1 Determining VAX Ada Program Portability 5.8.1.1 Factors Affecting Portability 5.8.1.2 Features Listed in the Portability Summary 5.8.2 Setting the System Name 6 Debugging VAX Ada Programs 6.1 VMS Debugger Overview 6.2 Getting Started with the Debugger 6.2.1 Compiling and Linking a Program to Prepare for Debugging 6.2.2 Starting and Ending a Debugging Session 6.2.3 Entering Debugger Commands 6.2.4 Viewing Your Source Code 6.2.4.1 Noscreen Mode 6.2.4.2 Screen Mode 6.2.4.3 Source Code Display Considerations 6.3 Controlling and Monitoring Program Execution 6.3.1 Starting and Resuming Program Execution 6.3.1.1 The GO Command 6.3.1.2 The STEP Command 6.3.2 Determining Where Execution is Suspended 6.3.3 Suspending Program Execution 6.3.4 Tracing Program Execution 6.3.5 Monitoring Changes in Variables 6.3.6 Debugging Ada Library Packages 6.3.7 Monitoring Ada Exceptions 6.3.7.1 Monitoring Any Exception 6.3.7.2 Monitoring Specific Exceptions 6.3.7.3 Monitoring Handled Exceptions and Exception Handlers 6.4 Examining and Manipulating Data 6.4.1 Displaying the Values of Variables 6.4.2 Changing the Values of Variables 6.4.3 Current, Previous, and Next Locations 6.4.4 Evaluating Expressions 6.4.5 Debugger Support for VAX Ada Data 6.4.5.1 Ada Names 6.4.5.2 Ada Language Expressions 6.4.6 Special EXAMINE, DEPOSIT, and EVALUATE Options 6.4.6.1 Specifying Data Type and Radix 6.4.6.2 Obtaining Virtual Addresses 6.4.7 Ada Data Types-Debugging Examples 6.4.7.1 Scalar Types 6.4.7.2 Array Types 6.4.7.3 Record Types 6.4.7.4 Access Types 6.5 Controlling Symbol References 6.5.1 Creating Symbol Information for the Debugger 6.5.2 Module Setting 6.5.2.1 Dynamic and Related Module Setting 6.5.2.2 The SHOW MODULE Command 6.5.2.3 The SHOW MODULE/RELATED Command 6.5.2.4 The SET MODULE Command 6.5.2.5 The CANCEL MODULE Command 6.5.3 Resolving Multiply-Defined Symbols 6.5.3.1 Scope 6.5.3.2 Path Name Conventions 6.5.3.3 Symbol Lookup Conventions 6.5.3.4 Using the SHOW SYMBOL Command and Path Names to Specify Symbols Uniquely 6.5.3.5 Using the SET SCOPE Command to Specify a Symbol Search Scope 6.5.4 Resolving Overloaded Names and Symbols 6.6 Supplementary Debugger Features 6.6.1 Logging a Debugging Session into a File 6.6.2 Invoking an Editor from the Debugger 6.6.3 Using a Debugger Initialization File 6.6.4 Using Command Procedures to Control Debugging Sessions 6.6.5 The CALL Command 6.7 Sample Debugging Session 7 Debugging VAX Ada Tasks 7.1 A Sample Tasking Program 7.2 Referring to Tasks in Debugger Commands 7.2.1 Ada Language Expressions for Tasks 7.2.2 Task ID (%TASK) 7.2.3 Pseudotask Names 7.2.3.1 Active Task (%ACTIVE_TASK) 7.2.3.2 Visible Task (%VISIBLE_TASK) 7.2.3.3 Next Task (%NEXT_TASK) 7.2.3.4 Caller Task (%CALLER_TASK) 7.2.4 Debugger Support of Ada Task Attributes 7.3 Displaying Task Information (SHOW TASK) 7.3.1 Displaying Basic Information on All Tasks 7.3.2 Selecting Tasks for Display 7.3.2.1 Task List 7.3.2.2 Task-Selection Qualifiers 7.3.2.3 Task List and Task Selection Qualifiers 7.3.3 Obtaining Additional Information 7.4 Examining and Manipulating Tasks 7.5 Changing Task Characteristics (SET TASK) 7.6 Setting Breakpoints and Tracepoints 7.6.1 Task-Specific and Task-Independent Debugger Eventpoints 7.6.2 Task Bodies, Entry Calls, and Accept Statements 7.6.3 Monitoring Ada Task Events 7.7 Additional Task-Debugging Topics 7.7.1 Debugging Programs with Deadlock 7.7.2 Debugging Programs that Use Time Slicing 7.7.3 Using CTRL/Y when Debugging Tasks 7.7.4 Automatic Stack Checking in the Debugger A ACS Command Dictionary ($) ADA ATTACH CHECK COMPILE CONVERT LIBRARY COPY FOREIGN COPY UNIT CREATE LIBRARY CREATE SUBLIBRARY DELETE LIBRARY DELETE SUBLIBRARY DELETE UNIT DIRECTORY ENTER FOREIGN ENTER UNIT EXIT EXPORT EXTRACT SOURCE HELP LINK LOAD MERGE RECOMPILE REENTER REORGANIZE SET LIBRARY SET PRAGMA SET SOURCE SHOW LIBRARY SHOW PROGRAM SHOW SOURCE SHOW VERSION SPAWN VERIFY B Debugger Command Summary B.1 Starting and Terminating a Debugging Session B.2 Controlling and Monitoring Program Execution B.3 Examining and Manipulating Data B.4 Controlling Type Selection and Symbolization B.5 Controlling Symbol Lookup B.6 Displaying Source Code B.7 Using Screen Mode B.8 Editing Source Code B.9 Defining Symbols B.10 Using Keypad Mode B.11 Using Command Procedures and Log Files B.12 Using Control Structures B.13 Additional Commands C Using VAX Ada with the VAX Language-Sensitive Editor and Source Code Analyzer C.1 Using VAX Ada with LSE C.1.1 Starting and Ending an Editing Sesssion C.1.2 Obtaining Help C.1.3 Entering Source Code Using Tokens and Placeholders C.1.4 Compiling and Reviewing Source Code C.1.5 Sample LSE Session C.2 Using VAX Ada with SCA C.2.1 Setting Up an SCA Environment C.2.1.1 Creating an SCA Library C.2.1.2 Generating Data Analysis Files C.2.1.3 Loading Data Analysis Files into a Local Library C.2.2 Using SCA for Cross-Referencing C.2.2.1 Finding Files C.2.2.2 Finding Ada Symbols C.2.2.2.1 Declarations C.2.2.2.2 References C.2.2.2.3 Symbol Classes C.2.3 Navigating Through Ada Source Code C.2.4 Using SCA for Static Analysis C.2.5 Multimodular Development C.2.6 Additional Ada-Specific SCA Considerations C.2.6.1 Library Differences C.2.6.2 Ada-Related Effects and Restrictions D Program Library and Sublibrary Structure and Contents E Efficient Compilation E.1 Memory Usage E.1.1 Working Sets E.1.1.1 Effect of Working Set on Paging Rate E.1.1.2 Effect of Working Set on Compilation Rate E.1.1.3 Suggestions for Controlling Working Set Sizes E.1.2 Virtual Address Space E.2 Resource Requirements E.2.1 ASTLM-AST Queue Limit Parameter E.2.2 ENQLM-Enqueue Quota Parameter E.2.3 FILLM-Open File Limit Parameter E.2.4 PRCLM-Subprocess Creation Limit Parameter E.2.5 TQELM-Timer Queue Entry Limit Parameter E.2.6 Virtual Memory Usage E.2.6.1 VIRTUALPAGECNT-Maximum Number of Virtual Pages Parameter E.2.6.2 PGFLQUOTA-Paging File Quota Parameter E.2.6.3 System Paging File E.2.6.4 WSQUOTA and WSEXTENT-Working Set Quota and Extent Parameters E.2.6.5 Batch Queue Parameters E.2.6.6 WSMAX-Working Set Maximum Number of Pages Parameter E.2.7 Program Library Networking Effects E.2.8 Channel Count Parameters F Compile-Time Diagnostic Messages F.1 Diagnostic Message Format F.2 Diagnostic Message Severity Codes F.3 VAX Ada Compiler Informational Messages F.4 VAX Ada Compiler Diagnostic Messages G ACS Diagnostic Messages G.1 Diagnostic Message Format G.2 Diagnostic Message Severity Codes G.3 ACS Diagnostic Messages H Run-Time Diagnostic Messages H.1 Diagnostic Message Format H.2 Diagnostic Message Severity Codes H.3 VAX Ada Run-Time Diagnostic Messages I Reporting Problems EXAMPLES 3-1 Sample VAX Ada Compiler Listing 5-1 Decomposed Stack Application 5-2 Command Procedure for Doing LSE Ada Compilations in Batch Mode 7-1 Procedure TASK_EXAMPLE 7-2 Sample Debugger Initialization File for VAX Ada Tasking Programs C-1 Complete Ada Program Developed Using LSE FIGURES 1 Figure Conventions 1-1 Dependences Among the Hotel Reservation Program Compilation Units 1-2 Source Files for the Hotel Reservation Program 1-3 Directory Structure for the Hotel Reservation Program 1-4 Sample Compilation Units Used to Show Closure 2-1 Simple Nested Sublibrary Structure 2-2 Sublibrary Configuration for the HOTEL Program 5-1 Diagram of Decomposed Stack Application 5-2 Efficient Program Library and Sublibrary Structure 5-3 Ada Program Library and Sublibrary Structure with CMS Libraries 5-4 DECnet Program Library Configuration 6-1 Debugger Keypad Key Functions 6-2 Access Objects in Virtual Memory 6-3 Depositing to Access Object Components 7-1 Task State Transitions 7-2 Diagram of a Task Stack C-1 Using LSE and SCA for Multimodular Development D-1 Current Default Directory and Current Program Library After Compilation D-2 Compilation Units as Entries in the Library Index File E-1 Page Faults Versus Working Set Size E-2 Compilation Rate Versus Working Set Size TABLES 1-1 ACS Program Library Management Commands 1-2 Compilation, Linking, and Execution Commands 1-3 Additional ACS Commands 1-4 Conventions for Naming VAX Ada Source Files 3-1 Summary Comparison of the DCL ADA and ACS LOAD, RECOMPILE, and COMPILE Commands 3-2 Comparison of the DCL ADA and ACS LOAD Commands 3-3 Differences Between ACS RECOMPILE and COMPILE in Recompiling Obsolete Units 5-1 Program Library Access Needed to Use ACS Commands 5-2 Minimum UIC Protection for Each Kind of Library Access 5-3 Features or Constructs that May Appear in a Portability Summary 6-1 Debugger Exception Symbols 6-2 Exception-Related VAX Ada Event Names 6-3 Debugger Support for Ada Names 6-4 Debugger Support for Ada Predefined Attributes 6-5 Debugger Support for Ada Language Expressions 6-6 Debugger Support for Ada Predefined Operators 7-1 Task States 7-2 Task Substates 7-3 SHOW TASK Command Qualifiers for Task Selection 7-4 SHOW TASK Command Qualifiers for Information Selection 7-5 SET TASK Command Qualifiers 7-6 VAX Ada Event Names 7-7 Kinds of Deadlock and Debugger Commands for Diagnosing Them C-1 VAX LSE Commands for Manipulating Tokens and Placeholders C-2 VAX LSE Commands for Compiling a Program and Reviewing Errors C-3 VAX LSE Commands for Making SCA Queries C-4 Ada Constructs Associated with SCA PRIMARY and ASSOCIATED Keywords C-5 Comparison of SCA and ACS Library Characteristics E-1 Description of Test Programs