CONTENTS Title Page Copyright Page Preface Summary of Technical Changes Part I Developing VAX BASIC Programs on VMS 1 Overview of the VAX BASIC Language 2 Introduction to the VMS Operating System 2.1 Logging In and Out 2.2 Accessing the HELP Facility 2.3 Entering and Editing DCL Commands 2.4 Understanding the Directory Structure 2.5 Using DCL File-Handling Commands 2.5.1 Displaying Files 2.5.2 Printing and Typing Files 2.5.3 Deleting Files 2.5.4 Purging Files 2.5.5 Renaming and Moving Files 2.5.6 Searching Files 2.5.7 Setting File Protection 2.6 Using Command Procedures 2.6.1 Defining DCL Symbols and Logical Names 2.6.2 Creating and Executing Command Procedures 2.6.3 Sample Command Procedure 2.6.4 Login Command Procedures 2.7 DCL Commands for Program Development 3 Developing Programs in the BASIC Environment 3.1 Entering the Environment 3.2 Creating and Running Programs 3.3 Immediate Mode 3.4 Debugging in Immediate Mode 3.5 Compiler Commands 3.5.1 Entering Comments 3.5.2 Entering DCL Commands 3.5.3 The APPEND Command 3.5.4 The ASSIGN Command 3.5.5 The COMPILE Command 3.5.6 The CONTINUE Command 3.5.7 The DELETE Command 3.5.8 The EDIT Command 3.5.9 The EXIT Command 3.5.10 The HELP Command 3.5.11 The IDENTIFY Command 3.5.12 The LIST and LISTNH Commands 3.5.13 The LOAD Command 3.5.14 The LOCK Command 3.5.15 The NEW Command 3.5.16 The OLD Command 3.5.17 The RENAME Command 3.5.18 The REPLACE Command 3.5.19 The RESEQUENCE Command 3.5.20 The RUN and RUNNH Commands 3.5.21 The SAVE Command 3.5.22 The SCALE Command 3.5.23 The SCRATCH Command 3.5.24 The SEQUENCE Command 3.5.25 The SET Command 3.5.26 The SHOW Command 3.5.27 The UNSAVE Command 4 Developing VAX BASIC Programs at DCL Command Level 4.1 Creating a VAX BASIC Program 4.1.1 Using VAX EDT 4.1.2 Using VAXTPU 4.1.2.1 The EVE Interface 4.1.2.2 The EDT Keypad Emulator Interface 4.2 Compiling a VAX BASIC Program 4.2.1 The BASIC Command 4.2.2 BASIC Command Qualifiers 4.2.3 Compiler Listings 4.2.3.1 Source Program Listing 4.2.3.2 Cross-Reference Listing 4.2.3.3 Allocation Map 4.2.3.4 Qualifier Summary 4.2.3.5 Machine Code Listing 4.3 Linking a VAX BASIC Program 4.3.1 The LINK Command 4.3.2 LINK Command Qualifiers 4.3.3 Linker Input Files 4.3.4 Linker Output Files 4.3.5 Using an Object Module Library 4.3.6 Linker Error Messages 4.4 Running a VAX BASIC Program 5 Using the VMS Debugger 5.1 Overview of the Debugger 5.2 Features of the Debugger 5.3 Getting Started with the Debugger 5.3.1 Compiling and Linking to Prepare for Debugging 5.3.1.1 Establishing the Debugging Configuration 5.3.2 Starting and Terminating a Debugging Session 5.3.3 Issuing Debugger Commands 5.3.4 Viewing Your Source Code 5.3.4.1 Noscreen Mode 5.3.4.2 Screen Mode 5.3.5 Controlling and Monitoring Program Execution 5.3.5.1 Starting and Resuming Program Execution 5.3.5.2 Determining the Current Location of the Program Counter 5.3.5.3 Suspending Program Execution 5.3.5.4 Tracing Program Execution 5.3.5.5 Monitoring Changes in Variables 5.3.6 Examining and Manipulating Data 5.3.6.1 Displaying the Values of Variables 5.3.6.2 Changing the Values of Variables 5.3.6.3 Evaluating Expressions 5.3.6.4 Stepping Into VAX BASIC Routines 5.3.7 Controlling Symbol References 5.3.7.1 Module Setting 5.3.7.2 Resolving Multiply-Defined Symbols 5.4 A Sample Debugging Session 5.5 Debugger Command Summary Part II VAX BASIC Programming Concepts 6 Getting Started with VAX BASIC 6.1 Line Numbers 6.1.1 Programs with Line Numbers 6.1.2 Programs Without Line Numbers 6.1.3 Labels 6.1.4 Continuation of Long Program Statements 6.2 Identifying Program Units 6.3 The VAX BASIC Character Set 6.4 Program Documentation 6.5 Declarations and Data Types 6.5.1 Implicit Data Typing 6.5.2 Explicit Data Typing 6.6 Constants 6.7 Variables 6.7.1 Floating-Point Variables 6.7.2 Integer Variables 6.7.3 Packed Decimal Variables 6.7.4 String Variables 6.7.5 Subscripted Variables 6.8 Keywords and Reserved Words 6.9 Operands, Operators, and Expressions 6.10 Assignment Statements 7 Simple Input and Output 7.1 Program Input 7.1.1 Providing Input Interactively 7.1.1.1 The INPUT Statement 7.1.1.2 The INPUT LINE and LINPUT Statements 7.1.1.3 Enabling and Disabling the Question Mark Prompt 7.1.2 Providing Input from the Source Program 7.1.2.1 The READ and DATA Statements 7.1.2.2 The RESTORE Statement 7.2 Program Output 7.2.1 Print Zones-The Comma and the Semicolon 7.2.2 Output Format for Numbers and Strings 7.3 Terminal-Format Files 7.3.1 Opening and Closing a Terminal-Format File 7.3.2 Writing Records to a Terminal-Format File 8 Arrays 8.1 Introduction 8.2 Creating Arrays Explicitly 8.2.1 Creating Arrays with the DECLARE Statement 8.2.2 Creating Arrays with the DIM Statement 8.2.2.1 Declarative DIM Statements 8.2.2.2 Executable DIM Statements 8.2.3 Creating Arrays with the COMMON Statement 8.2.4 Creating Arrays with the MAP Statement 8.3 Determining the Bounds of an Array 8.4 Creating Arrays Implicitly 8.5 Assigning and Displaying Array Values 8.5.1 Assigning Values with the LET Statement 8.5.2 Listing Array Elements with the PRINT Statement 8.6 Using MAT Statements 8.6.1 The MAT Statement 8.6.2 The MAT READ Statement 8.6.3 The MAT INPUT [#] Statement 8.6.4 The MAT LINPUT [#] Statement 8.6.5 The MAT PRINT [#] Statement 8.6.6 Matrix I/O Functions (NUM and NUM2) 8.7 Matrix Operators 8.7.1 Arithmetic Matrix Operations 8.7.1.1 Assignment 8.7.1.2 Addition and Subtraction 8.7.1.3 Multiplication 8.7.2 Matrix Functions 8.7.2.1 The TRN Function 8.7.2.2 The INV Function 8.7.2.3 The DET Function 9 Data Definition 9.1 Declarative Statements 9.2 Data Types 9.3 Setting the Default Data Type and Size 9.4 Declaring Variables Explicitly 9.5 Declaring Named Constants Explicitly 9.5.1 Declaring Constants Within a Program Unit 9.5.2 Declaring Constants External to the Program Unit 9.5.3 Declaring a Default Constant Type 9.6 Operations with Multiple Data Types 9.7 Allocating Static Storage 9.7.1 The COMMON Statement 9.7.2 The MAP Statement 9.7.2.1 Single Maps 9.7.2.2 Multiple Maps 9.7.3 FILL Items 9.7.4 Using COMMON and MAP in Subprograms 9.8 Dynamic Mapping 10 Creating and Using Data Structures 10.1 The RECORD Statement 10.1.1 Grouping RECORD Components 10.1.2 RECORD Variants 10.1.3 Accessing RECORD Components 11 Program Control 11.1 Statement Modifiers 11.1.1 The IF Modifier 11.1.2 The UNLESS Modifier 11.1.3 The FOR Modifier 11.1.4 The UNTIL Modifier 11.1.5 The WHILE Modifier 11.1.6 Nesting Modifiers 11.2 Loops 11.2.1 FOR...NEXT Loops 11.2.2 WHILE...NEXT Loops 11.2.3 UNTIL...NEXT Loops 11.2.4 Nesting Loops 11.3 Unconditional Branching (the GOTO Statement) 11.4 Conditional Branching 11.4.1 The ON...GOTO...OTHERWISE Statement 11.4.2 The IF...THEN...ELSE Statement 11.4.3 The SELECT...CASE Statement 11.5 The EXIT and ITERATE Statements 11.6 Executing Local Subroutines 11.6.1 The GOSUB and RETURN Statements 11.6.2 The ON...GOSUB...OTHERWISE Statement 11.7 Suspending and Halting Program Execution 11.7.1 The SLEEP Statement 11.7.2 The WAIT Statement 11.7.3 The STOP Statement 11.7.4 The END Statement 12 Functions 12.1 Built-In Functions 12.1.1 Numeric Functions 12.1.1.1 The ABS Function 12.1.1.2 The INT and FIX Functions 12.1.1.3 The SIN, COS, and TAN Functions 12.1.1.4 The LOG10 Function 12.1.1.5 The EXP Function 12.1.1.6 The RND Function 12.1.2 Data Conversion Functions 12.1.2.1 The ASCII Function 12.1.2.2 The CHR$ Function 12.1.3 String Numeric Functions 12.1.3.1 The FORMAT$ Function 12.1.3.2 The NUM$ and NUM1$ Functions 12.1.3.3 The VAL% and VAL Functions 12.1.4 String Arithmetic Functions 12.1.4.1 The SUM$ and DIF$ Functions 12.1.4.2 The QUO$, PLACE$, and PROD$ Functions 12.1.5 Date and Time Functions 12.1.5.1 The DATE$ Function 12.1.5.2 The TIME$ Function 12.1.5.3 The TIME Function 12.1.6 Terminal Control Functions 12.1.6.1 The CTRLC and RCTRLC Functions 12.1.6.2 The ECHO and NOECHO Functions 12.1.6.3 The INKEY$ Function 12.2 User-Defined Functions 12.2.1 Single-Line DEF Functions 12.2.2 Multiline DEF Functions 13 String Handling 13.1 Introduction 13.2 Using Dynamic Strings 13.3 Using Fixed-Length Strings 13.4 Using String Virtual Arrays 13.5 Assigning String Data 13.5.1 The LET Statement 13.5.2 The LSET Statement 13.5.3 The RSET Statement 13.5.4 The MID$ Assignment Statement 13.6 Manipulating String Data with String Functions 13.6.1 The LEN Function 13.6.2 The POS Function 13.6.3 The SEG$ Function 13.6.4 The MID$ Function 13.6.5 The STRING$ Function 13.6.6 The SPACE$ Function 13.6.7 The TRM$ Function 13.6.8 The EDIT$ Function 13.7 Manipulating String Data with Multiple Maps 14 Program Segmentation 14.1 VAX BASIC Subprograms 14.1.1 SUB Subprograms 14.1.2 FUNCTION Subprograms 14.2 Declaring Subprograms and Parameters 14.3 Compiling Subprograms 14.4 Invoking Subprograms 14.4.1 Invoking SUB Subprograms 14.4.2 Invoking FUNCTION Subprograms 14.5 Returning Program Status 15 File Input and Output 15.1 Record Formats 15.1.1 Fixed-Length Records 15.1.2 Variable-Length Records 15.1.3 Stream Records 15.2 File Organizations 15.2.1 Terminal-Format Files 15.2.2 Sequential Files 15.2.3 Relative Files 15.2.4 Indexed Files 15.2.5 Virtual Files 15.3 Record Access and Record Context 15.4 I/O and Record Buffers 15.5 Accessing the Contents of a Record 15.5.1 The MAP Statement 15.5.2 The MAP DYNAMIC and REMAP Statements 15.5.3 The MOVE Statement 15.6 File and Record Operations 15.6.1 Opening Files 15.6.2 Creating Virtual Array Files 15.6.3 Locating Records 15.6.4 Reading Records 15.6.5 Writing Records 15.6.6 Deleting Records 15.6.7 Updating Records 15.6.8 Controlling Record Access 15.6.9 Gaining Access to Locked Records 15.6.10 Accessing Records by Record File Address 15.6.11 Transferring Data to Terminal-Format Files 15.6.12 Resetting the File Position 15.6.13 Truncating Files 15.6.14 Renaming Files 15.6.15 Closing Files and Ending I/O 15.6.16 Deleting Files 15.7 File-Related Functions 15.7.1 The FSP$ Function 15.7.2 The RECOUNT Function 15.7.3 The STATUS, VMSSTATUS, and RMSSTATUS Functions 15.8 OPEN Statement Options 15.8.1 The BUCKETSIZE Clause 15.8.2 The BUFFER Clause 15.8.3 The CONNECT Clause 15.8.4 The CONTIGUOUS Clause 15.8.5 The DEFAULTNAME Clause 15.8.6 The EXTENDSIZE Clause 15.8.7 The FILESIZE Clause 15.8.8 The NOSPAN Clause 15.8.9 The RECORDTYPE Clause 15.8.10 The TEMPORARY Clause 15.8.11 The USEROPEN Clause 15.8.12 The WINDOWSIZE Clause 16 Formatting Output with the PRINT USING Statement 16.1 Introduction 16.2 Using Format Strings 16.3 Printing Numbers 16.3.1 Specifying the Number of Digits 16.3.2 Specifying Decimal Point Location 16.3.3 Printing Numbers with Special Symbols 16.3.3.1 Commas 16.3.3.2 Asterisk Fill Fields 16.3.3.3 Currency Symbols 16.3.3.4 Negative Fields 16.3.3.5 E (Exponential) Format 16.3.3.6 Leading Zeros 16.3.3.7 Blank-If-Zero Fields 16.3.3.8 Debits and Credits 16.4 Printing Strings 16.4.1 Left-Justified Format 16.4.2 Right-Justified Format 16.4.3 Centered Fields 16.4.4 Extended Fields 16.5 PRINT USING Statement Error Conditions 17 Handling Run-Time Errors 17.1 Default Error Handling 17.2 User-Supplied Error Handlers 17.2.1 Protected Regions 17.2.2 Handlers 17.2.3 Exiting from Handlers 17.2.3.1 The RETRY Statement 17.2.3.2 The CONTINUE Statement 17.2.3.3 The EXIT HANDLER Statement 17.2.4 Selecting the Severity of Errors to Handle 17.2.5 Identifying Errors 17.2.5.1 Determining the Error Number (ERR) 17.2.5.2 Determining the Error Line Number (ERL) 17.2.5.3 Determining Where the Error Occurred (ERN$) 17.2.5.4 Determining the Error Message Text (ERT$) 17.2.5.5 Determining VMS Error Information 17.2.5.6 Determining RMS Error Information 17.2.6 CTRL/C Trapping 17.2.7 Handling Errors in Multiple-Unit Programs 17.2.8 Forcing Errors 17.3 Using the ON ERROR Statements 18 Compiler Directives 18.1 Introduction 18.2 Controlling the Compilation Listing 18.2.1 The %TITLE and %SBTTL Directives 18.2.2 The %IDENT Directive 18.2.3 The %PAGE Directive 18.2.4 The %LIST and %NOLIST Directives 18.2.5 The %CROSS and %NOCROSS Directives 18.3 Accessing External Source Files 18.4 Controlling Compilation 18.4.1 The %LET Directive 18.4.2 The %VARIANT Directive 18.4.3 The %ABORT Directive 18.4.4 The %PRINT Directive 18.4.5 The %IF-%THEN-%ELSE-%END %IF Directive 18.5 Record Dependency Relationships in CDD/Plus 19 Data Representation 19.1 Integer Format 19.1.1 Byte-Length Integer Format 19.1.2 Word-Length Integer Format 19.1.3 Longword Integer Format 19.2 Real Number Format 19.2.1 SINGLE Floating-Point Number Format (F_floating) 19.2.2 DOUBLE Floating-Point Number Format (D_floating) 19.2.3 GFLOAT Floating-Point Number Format (G_floating) 19.2.4 HFLOAT Floating-Point Number Format (H_floating) 19.3 Packed Decimal Number Format 19.4 String and Array Descriptor Format 19.4.1 Fixed-Length String Descriptor Format 19.4.2 Dynamic String Descriptor Format 19.5 Array Descriptors 19.5.1 The Prototype Block 19.5.2 The Multiplier Block 19.5.3 The Bounds Block 19.6 Decimal Scalar String Descriptor (Packed Decimal String Descriptor) Part III Using VAX BASIC Features on VMS 20 Advanced File Input and Output 20.1 Introduction 20.2 RMS I/O to Magnetic Tape 20.2.1 Allocating and Mounting a Tape 20.2.2 Opening a Tape File for Output 20.2.3 Opening a Tape File for Input 20.2.4 Positioning a Tape 20.2.5 Writing Records to a File 20.2.6 Reading Records from a File 20.2.7 Controlling Tape Output Format 20.2.8 Rewinding a Tape 20.2.9 Closing a File 20.3 Device-Specific I/O 20.3.1 Device-Specific I/O to Unit Record Devices 20.3.2 Device-Specific I/O to Magnetic Tape Devices 20.3.2.1 Allocating and Mounting a Tape 20.3.2.2 Opening a Tape File for Output 20.3.2.3 Opening a Tape File for Input 20.3.2.4 Writing Records to a File 20.3.2.5 Reading Records from a File 20.3.2.6 Rewinding a Tape 20.3.2.7 Closing a Tape 20.3.3 Device-Specific I/O to Disks 20.3.3.1 Assigning and Mounting a Disk 20.3.3.2 Opening a Disk File for Output 20.3.3.3 Opening a Disk File for Input 20.3.3.4 Writing Records to a Disk File 20.3.3.5 Reading Records from a Disk File 20.4 I/O to Mailboxes 20.5 Network I/O 20.5.1 Remote File Access 20.5.2 Task-to-Task Communication 20.5.3 Accessing an Rdb/VMS Database 21 Using VAX BASIC in the Common Language Environment 21.1 Specifying Parameter-Passing Mechanisms 21.1.1 Passing Parameters by Reference 21.1.2 Passing Parameters by Descriptor 21.1.3 Passing Parameters by Value 21.1.4 VAX BASIC Default Parameter-Passing Mechanisms 21.1.5 Creating Local Copies 21.2 Calling External Routines 21.2.1 Determining the Type of Call 21.2.2 Declaring an External Routine and Its Arguments 21.2.3 Calling the Routine 21.3 Calling VAX BASIC Subprograms from Other Languages 21.4 Calling System Routines 21.4.1 VMS Run-Time Library Routines 21.4.2 System Service Routines 21.4.3 System Routine Arguments 21.4.4 Including Symbolic Definitions 21.4.5 Condition Values 21.5 Examples of Calling System Routines 21.6 The VAX Procedure Calling and Condition Handling Standard 21.6.1 The Argument List 21.6.2 The Return of the Function Value 21.6.3 Register and Stack Usage 21.7 Additional Information 22 Libraries and Shareable Images 22.1 Introduction 22.2 System-Supplied Libraries 22.3 Creating User-Supplied Object Module Libraries 22.3.1 Accessing User-Supplied Object Module Libraries in the BASIC Environment 22.3.2 Accessing User-Supplied Object Module Libraries at DCL Level 22.4 Shareable Images 22.4.1 Accessing Shareable Images in the BASIC Environment 22.4.2 Accessing Shareable Images at DCL Level 23 CDD/Plus Support in VAX BASIC 23.1 Overview of VAX CDD/Plus 23.2 CDD/Plus Concepts 23.2.1 Dictionary Formats 23.2.2 Dictionary Path Names 23.2.3 Dictionary Entities 23.2.4 Dictionary Relationships 23.2.5 Extracting CDD/Plus Data Definitions in VAX BASIC 23.3 Using CDD/Plus with VAX BASIC 23.3.1 The /DEPENDENCY_DATA Qualifier 23.3.2 Creating Relationships with Included Record Definitions 23.4 Creating Relationships for Referenced Dictionary Entities 23.5 Specifying a CDD History List Entry 23.6 CDD/Plus Arrays 23.7 CDD/Plus Variants 23.8 The NAME FOR BASIC Clause 23.9 CDD/Plus Data Types 23.9.1 Character String Data Types 23.9.2 Integer Data Types 23.9.3 Floating-Point Data Types 23.9.4 Decimal String Data Types 23.9.5 Other Data Types A Compile-Time Error Messages A.1 Compile-Time Errors B Run-Time Error Messages B.1 VAX BASIC Run-Time Errors By Mnemonic B.2 VAX BASIC Run-time Errors By Number B.3 Errors Not Generated By VAX BASIC C Optional Programming Productivity Tools C.1 VAX Language-Sensitive Editor (LSE) and the VAX Source Code Analyzer (SCA) C.1.1 Preparing an SCA Library C.1.2 Starting and Terminating an LSE or an SCA Session C.1.3 Compiling from Within LSE C.1.4 Notes on VAX BASIC Support C.1.4.1 Programming Language Placeholders and Tokens C.1.4.2 Placeholder and Design Comment Processing C.1.5 LSE and SCA Examples C.1.5.1 FUNCTION Declaration C.1.5.2 FIND Statement C.1.5.3 FOR Statement C.2 VAX CDD/Plus C.3 VAX Database Management System (VAX DBMS) C.4 VAX DEC/Test Manager C.5 VAX DEC/Code Management System (CMS) EXAMPLES 2-1 Sample Command Procedure 4-1 VAX BASIC Compiler Listing 4-2 Source Program Listing 4-3 Cross-Reference Listing 4-4 Qualifier Summary 4-5 Machine Code Listing 21-1 VAX BASIC Main Program 21-2 VAX FORTRAN Subprogram 21-3 Calling System Services 21-4 Program Displaying the $QIOW System Service Routine C-1 LSE Placeholders in a VAX BASIC Program FIGURES 2-1 Complete File Specification 2-2 A Directory Hierarchy 2-3 DCL Commands for Developing Programs 3-1 Running Multiple-Unit Programs 5-1 Keypad Key Functions Predefined by the Debugger 9-1 Mixed-Mode Expression Results 9-2 Multiple Maps 19-1 Byte-Length Integer Format 19-2 Word-Length Integer Format 19-3 Longword Integer Format 19-4 Single-Precision Real Number Format 19-5 Double-Precision Real Number Format 19-6 Fixed-Length String Descriptor Format 19-7 Dynamic String Descriptor Format 19-8 Array Descriptor Format 19-9 Decimal Scalar String Descriptor 21-1 Structure of a VAX Argument List 21-2 Example of a VAX Argument List TABLES 2-1 File Protection User Categories 2-2 File Access Variations 3-1 VAX BASIC Compiler Commands 3-2 Examples of Editing in Line Mode 5-1 Debugger Command Summary 6-1 Predefined Constants 8-1 MAT Statements 8-2 MAT Statement Keywords 9-1 VAX BASIC Data Types 9-2 Result Data Types in VAX BASIC Expressions 9-3 FILL Item Formats, Representations, and Default Allocations 12-1 String Arithmetic Functions 12-2 Precision of String Arithmetic Functions 13-1 String Modification 13-2 EDIT$ Options 15-1 Record Context After a FIND Operation 15-2 Record Context After a GET Operation 15-3 Record Context After a PUT Operation 15-4 VAX RMS Control Structures Set for the USEROPEN Clause 16-1 Format Characters for Numeric Fields 16-2 Format Characters for String Fields 21-1 Valid Parameter-Passing Mechanisms 21-2 Run-Time Library Facilities 21-3 System Services 21-4 VMS Usages 21-5 VAX Register Usage 23-1 Supported CDD/Plus Data Types 23-2 Unsupported CDD/Plus Data Types B-1 Errors Not Generated by VAX BASIC C-1 LSE Commands Used to Examine Source Code C-2 Types of LSE Placeholders C-3 LSE Commands Used to Manipulate Tokens and Placeholders