CONTENTS Title Page Copyright Page Preface Summary of Changes 1 Compiling VAX FORTRAN Programs 1.1 Functions of the Compiler 1.2 The FORTRAN Command 1.2.1 Specifying Input Files 1.2.2 Specifying Output Files 1.2.3 Qualifiers to the FORTRAN Command 1.2.3.1 /ANALYSIS_DATA Qualifier 1.2.3.2 /CHECK Qualifier 1.2.3.3 /CONTINUATIONS Qualifier 1.2.3.4 /CROSS_REFERENCE Qualifier 1.2.3.5 /DEBUG Qualifier 1.2.3.6 /DESIGN Qualifier 1.2.3.7 /D_LINES Qualifier 1.2.3.8 /DIAGNOSTICS Qualifier 1.2.3.9 /DML Qualifier 1.2.3.10 /EXTEND_SOURCE Qualifier 1.2.3.11 /F77 Qualifier 1.2.3.12 /G_FLOATING Qualifier 1.2.3.13 /I4 Qualifier 1.2.3.14 /LIBRARY Qualifier 1.2.3.15 /LIST Qualifier 1.2.3.16 /MACHINE_CODE Qualifier 1.2.3.17 /OBJECT Qualifier 1.2.3.18 /OPTIMIZE Qualifier 1.2.3.19 /PARALLEL Qualifier 1.2.3.20 /SHOW Qualifier 1.2.3.21 /STANDARD Qualifier 1.2.3.22 /WARNINGS Qualifier 1.3 Using Text Libraries 1.3.1 Using the LIBRARY Commands 1.3.2 Naming Text Modules 1.3.3 Specifying Library Files on the FORTRAN Command Line 1.3.4 Search Order of Libraries 1.3.4.1 User-Supplied Default Libraries 1.3.4.2 System-Supplied Default Library 1.4 Using the VAX Common Data Dictionary 1.4.1 Accessing the CDD from VAX FORTRAN Programs 1.4.2 Creating CDD Structure Declarations 1.4.3 VAX FORTRAN and CDDL Data Types 1.5 Compiler Diagnostic Messages and Error Conditions 1.6 Compiler Output Listing Format 1.6.1 Source Code Section 1.6.2 Machine Code Section 1.6.3 Storage Map Section 1.6.4 Compilation Summary Section 2 Linking and Running VAX FORTRAN Programs 2.1 Linking VAX FORTRAN Programs 2.1.1 Functions of the Linker 2.1.2 The LINK Command 2.1.2.1 Linker Output File Qualifiers 2.1.2.2 /DEBUG and /TRACEBACK Qualifiers 2.1.2.3 Linker Input File Qualifiers 2.1.3 Linker Messages 2.2 Running VAX FORTRAN Programs 2.2.1 The RUN Command 2.2.2 System Processing at Image Exit 2.2.3 Interrupting a Program 2.2.4 Returning Status Values to the Command Interpreter 2.3 Finding and Correcting Run-Time Errors 2.3.1 Effects of Error-Related Command Qualifiers 3 Using the VMS Debugger 3.1 Overview 3.2 Features of the Debugger 3.3 Getting Started with the Debugger 3.3.1 Compiling and Linking a Program to Prepare for Debugging 3.3.2 Starting and Terminating a Debugging Session 3.3.3 Aborting Program Execution or Debugger Commands 3.3.4 Issuing Debugger Commands 3.3.5 Viewing Your Source Code 3.3.5.1 Noscreen Mode 3.3.5.2 Screen Mode 3.3.6 Controlling and Monitoring Program Execution 3.3.6.1 Starting and Resuming Program Execution-GO and STEP 3.3.6.2 Determining Where Execution Is Suspended-SHOW CALLS 3.3.6.3 Suspending Program Execution-SET BREAK 3.3.6.4 Tracing Program Execution-SET TRACE 3.3.6.5 Monitoring Changes in Variables-SET WATCH 3.3.7 Examining and Manipulating Data 3.3.7.1 Displaying the Values of Variables-EXAMINE 3.3.7.2 Changing the Values of Variables-DEPOSIT 3.3.7.3 Evaluating Expressions-EVALUATE 3.3.7.4 Notes on Debugger Support for VAX FORTRAN 3.3.8 Controlling Symbol References 3.3.8.1 Module Setting-SET MODULE 3.3.8.2 Resolving Multiply Defined Symbols 3.4 Sample Debugging Session 3.5 Debugger Command Summary 3.5.1 Starting and Terminating a Debugging Session 3.5.2 Controlling and Monitoring Program Execution 3.5.3 Examining and Manipulating Data 3.5.4 Controlling Type Selection and Symbolization 3.5.5 Controlling Symbol Lookup 3.5.6 Displaying Source Code 3.5.7 Using Screen Mode 3.5.8 Editing Source Code 3.5.9 Defining Symbols 3.5.10 Using Keypad Mode 3.5.11 Using Command Procedures and Log Files 3.5.12 Using Control Structures 3.5.13 Debugging Multiprocess Programs 3.5.14 Additional Commands 4 VAX FORTRAN Input/Output 4.1 Overview of VAX FORTRAN I/O 4.1.1 Identifying Logical Input/Output Units 4.1.2 Types of I/O Statements 4.1.3 Interprocess Communication 4.1.4 Forms of I/O Statements 4.2 Elements of I/O Processing 4.2.1 File Specifications 4.2.2 Logical Names and Logical Unit Numbers 4.2.2.1 FORTRAN Logical Names 4.2.2.2 Implied FORTRAN Logical Unit Numbers 4.2.2.3 File Specification in the OPEN Statement 4.2.2.4 Assigning Files to Logical Units-Summary 4.2.3 File Organizations, I/O Record Formats, and Access Modes 4.2.3.1 File Organizations 4.2.3.2 Internal Files 4.2.3.3 I/O Record Formats 4.2.3.4 Record Access Modes 5 Error Processing 5.1 Run-Time Library Default Error Processing 5.2 Using the ERR and END Specifiers 5.3 Using the IOSTAT Specifier 6 Using VAX FORTRAN in the Common Language Environment 6.1 VAX Procedure-Calling Standard 6.1.1 Register and Stack Usage 6.1.2 Return Values of Procedures 6.1.3 Argument Lists 6.2 Argument-Passing Mechanisms 6.2.1 Passing Arguments by Reference-%REF Function 6.2.2 Passing Arguments by Descripton-%DESCR Function 6.2.3 Passing Arguments by Immediate Value-%VAL Function 6.2.4 Passing Addresses-%LOC Function 6.2.5 Examples of Argument Passing Built-in Functions 6.2.6 Object Code Examples 6.2.6.1 Argument-Passing Examples 6.2.6.2 Examples of Argument List Built-In Functions 6.2.6.3 Character Function Example 6.3 VMS System Routines 6.3.1 VMS Run-Time Library Routines 6.3.2 VMS System Services Routines 6.4 Calling Routines-General Considerations 6.5 Calling VMS System Services 6.5.1 Obtaining Values for System Symbols 6.5.2 Calling System Services by Function Reference 6.5.3 Calling System Services as Subroutines 6.5.4 Passing Arguments to System Services 6.5.4.1 Immediate Value Arguments 6.5.4.2 Address Arguments 6.5.4.3 Descriptor Arguments 6.5.4.4 Data Structure Arguments 6.5.4.5 Examples of Passing Arguments 7 Using VMS Record Management Services 7.1 RMS Data Structures and Services 7.1.1 RMS Data Structures 7.1.1.1 Using FORSYSDEF Modules to Manipulate RMS Data Structures 7.1.1.2 The File Access Block 7.1.1.3 The Record Access Block 7.1.1.4 The Name Block 7.1.1.5 Extended Attributes Blocks 7.1.2 RMS Services 7.1.2.1 Declaring RMS System Service Names 7.1.2.2 Arguments to RMS Services 7.1.2.3 Checking Status from RMS Services 7.1.2.4 Opening a File 7.1.2.5 Closing a File 7.1.2.6 Writing Data 7.1.2.7 Reading Data 7.1.2.8 Other Services 7.2 User-Written Open Procedures 7.2.1 Examples of USEROPEN Routines 7.2.2 RMS Control Structures 7.3 Example of Block Mode I/O Usage 8 Interprocess Communications 8.1 Local Processes-Sharing and Exchanging Data 8.1.1 Sharing Images in Shareable Image Libraries 8.1.2 Sharing Data in Installed Common Areas 8.1.2.1 Synchronizing Access 8.1.3 Sharing Data in Files 8.1.4 Using Mailboxes to Pass Information 8.1.4.1 Creating a Mailbox 8.1.5 Sending and Receiving Data Using Mailboxes 8.2 Remote Processes-Sharing and Exchanging Data 8.2.1 Remote File Access 8.2.2 Network Task-to-Task Communication 9 Condition-Handling Facilities 9.1 Using the Condition-Handling Facility 9.1.1 Default Condition Handler 9.1.2 User-Program Interactions with the CHF 9.1.2.1 Establishing and Removing Condition Handlers 9.1.2.2 Signaling a Condition 9.1.2.3 Condition Values and Symbols Passed to CHF 9.1.3 How to Write a Condition Handler 9.1.3.1 Operations Performed in Handlers 9.1.3.2 Coding Requirements of Condition Handlers 9.1.3.3 Returning from a Condition Handler 9.1.4 Use of LIB$ Routines as Condition Handlers 9.1.4.1 Overflow/Underflow Detection Enabling Routines 9.1.4.2 Floating Underflow Exceptions 9.1.4.3 Floating Reserved Operand Faults 9.1.4.4 Matching Condition Values to Determine Program Behavior 9.1.4.5 Converting Faults and Traps 9.1.4.6 Changing a Signal to a Return Status 9.1.4.7 Changing a Signal to a Stop 9.1.5 Condition Handler Examples 10 VAX FORTRAN Implementation Notes 10.1 VAX FORTRAN Program Section Usage 10.2 Storage Allocation and Fixed-Point Data Types 10.2.1 Integer Data Types 10.2.1.1 Relationship of INTEGER * 2 and INTEGER * 4 Values 10.2.1.2 Integer Constant Typing 10.2.1.3 Integer-Valued Intrinsic Functions 10.2.2 BYTE (LOGICAL * 1) Data Type 10.2.3 Zero-Extend Intrinsic Functions for Converting Data Types 10.3 Iteration Count Model for Indexed DO Loops 10.3.1 Cautions Concerning Program Transportability 10.3.2 Iteration Count Computation 10.4 ENTRY Statement Arguments 10.5 Floating-Point Data 10.5.1 Floating-Point Data Characteristics 10.5.1.1 Reserved Operand Faults 10.5.1.2 Representation of 0.0 10.5.1.3 Sign Bit Tests 10.5.2 Effect of the /G_FLOATING Qualifier 10.5.3 Conversion Between D_floating and G_floating Data Types 10.5.3.1 Run-Time Library Conversion Functions 10.5.3.2 Run-Time Library Conversion Subroutines 10.5.3.3 Sample Conversions 11 Performance Optimization 11.1 General Optimization Issues 11.1.1 Importance of Algorithms Used in Source Programs 11.1.2 Characteristics of Optimized and Unoptimized Programs 11.1.3 Compiler Structure 11.2 Effects of Compiler Optimizations on Debugging 11.3 Global Analysis of the Use of Variables and Arrays 11.3.1 Criteria for Selecting Variables and Arrays for Global Analysis 11.3.2 Factors Influencing Global Analysis 11.3.2.1 Effects of EQUIVALENCE Statements 11.3.2.2 Effects of Volatile Declarations 11.3.2.3 Effects of Inline Expansion of Statement Functions 11.3.2.4 Effects of Variable Format Expressions 11.4 Speed Optimizations 11.4.1 Effects of Global Analysis on Speed Optimizations 11.4.2 Removal Optimizations 11.4.2.1 Compile-Time Operations 11.4.2.2 Flow Boolean Operations 11.4.2.3 Compound Logical Expressions in IF Statements 11.4.2.4 Common Subexpression Elimination 11.4.2.5 Code Motions 11.4.2.6 Value Propagations 11.4.2.7 Dead Store Elimination 11.4.3 Replacement Optimizations 11.4.3.1 Store Delaying Optimizations 11.4.3.2 Register Usage 11.4.3.3 Using Autoincrement and Autodecrement Mode Addressing 11.4.3.4 Strength Reduction Optimizations 11.4.3.5 Tradeoff Policy Applied to Register Use 11.4.3.6 Block Moves and Block Initializations 11.4.3.7 Locality of Reference 11.4.4 Operation-Specific Optimizations 11.4.4.1 Constants as Code Literals 11.4.4.2 JSB for Floating Math Functions 11.4.4.3 Code Alignment 11.4.4.4 SIN and COS Functions 11.4.4.5 Mixed Real/Complex 11.4.4.6 Peephole Optimizations 11.4.5 Improving Performance of I/O Operations 11.4.5.1 Using Unformatted I/O 11.4.5.2 Using the OPEN Statement's RECORDTYPE Keyword 11.4.5.3 Avoiding Run-Time Formats 11.4.5.4 Avoiding the Use of the BACKSPACE Statement 11.4.5.5 Using OPEN Statement Keywords to Control I/O 11.4.5.6 Using Alternative I/O Methods 11.4.5.7 Implied-DO Loop Collapsing 11.4.5.8 Additional I/O Optimizations 11.5 Space Optimizations 11.5.1 Data Size Optimizations 11.5.1.1 Constant Pooling 11.5.1.2 Dead Variable Elimination 11.5.2 Code Size Optimizations 11.5.2.1 Local Storage Allocation 11.5.2.2 Jump Branch Resolution 11.5.2.3 Dead Code Eliminations 11.6 Compiler Optimization Example 12 Using Structures and Records 12.1 Structures 12.2 Records 12.3 Uses of Records 13 Using Character Data 13.1 Character Substrings 13.2 Building Character Strings 13.3 Character Constants 13.4 Declaring Character Data 13.5 Initializing Character Variables 13.6 Passed-Length Character Arguments 13.7 Character Intrinsic Functions 13.7.1 CHAR Intrinsic Function 13.7.2 ICHAR Intrinsic Function 13.7.3 INDEX Intrinsic Function 13.7.4 LEN Intrinsic Function 13.7.5 LGE, LGT, LLE, LLT Intrinsic Functions 13.8 Character I/O 13.9 Character Data Examples 14 Using Indexed Files 14.1 Creating an Indexed File 14.2 Writing Indexed Files 14.2.1 Duplicate Values in Key Fields 14.2.2 Preventing the Indexing of Alternate Key Fields 14.3 Reading Indexed Files 14.4 Updating Records 14.5 Deleting Records 14.6 Current Record and Next Record Pointers 14.7 Exception Conditions 15 VAX FORTRAN Support for Parallel Processing 15.1 Overview of VAX FORTRAN Parallel Processing 15.2 Preparing Programs for Parallel Processing 15.2.1 Coding Restrictions Within Parallel DO Loops 15.2.1.1 Coding Restrictions Flagged by the Compiler 15.2.1.2 Coding Practices that May Cause Unpredictable Results 15.2.2 Coding Techniques for Improving Execution Efficiency 15.2.3 Use of Other Languages in Parallel-Processing Programs 15.2.4 Use of Random Number Generators Within Parallel DO Loops 15.2.5 Influence of Parallel Processing on Exception Handling 15.3 Data Dependence Problems Caused by Parallel Processing 15.3.1 Acceptable Forms of Dependence 15.3.1.1 Temporary Variables 15.3.1.2 Read-Only Variables 15.3.1.3 Variables Defined and Not Used 15.3.2 Using Code Transformations to Resolve Dependences 15.3.2.1 Loop Alignment 15.3.2.2 Code Replication 15.3.2.3 Loop Distribution 15.3.3 Using Locks to Resolve Dependences 15.4 Tuning Issues Related to Parallel Processing 15.4.1 System Parameters Set with the SYSGEN Utility 15.4.2 User Parameters Set with the Authorize Utility 15.4.3 Other Tuning Considerations 15.5 Debugging Programs with Parallel DO Loops 15.6 Sample Use of Parallel Processing 15.6.1 Matrix Arithmetic 15.6.2 Linear Recurrences 15.7 VAX FORTRAN Parallel-Processing Support Mechanisms 15.7.1 /PARALLEL Qualifier on FORTRAN Command Line 15.7.2 Compiler Directives for Parallel Processing 15.7.2.1 DO_PARALLEL Directive 15.7.2.2 SHARED, CONTEXT_SHARED, and PRIVATE Directives 15.7.2.3 LOCKON and LOCKOFF Directives 15.7.3 Customizing the Parallel-Processing Run-Time Environment 15.7.4 NWORKERS Intrinsic Function A Working with the Multiprocess Debugging Configuration A.1 Getting Started A.1.1 Establishing a Multiprocess Debugging Configuration A.1.2 Invoking the Debugger A.1.3 The Visible Process and Process-Specific Commands A.1.4 Obtaining Information About Processes A.1.5 Bringing a Spawned Process Under Debugger Control A.1.6 Broadcasting Commands to Selected Processes A.1.7 Controlling Execution A.1.7.1 Controlling Execution with SET MODE NOINTERRUPT A.1.7.2 Putting Selected Processes on Hold A.1.8 Changing the Visible Process A.1.9 Dynamic Process Setting A.1.10 Monitoring the Termination of Images A.1.11 Terminating the Debugging Session A.1.12 Releasing Selected Processes from Debugger Control A.1.13 Aborting Debugger Commands and Interrupting Program Execution A.2 Supplemental Information A.2.1 Specifying Processes in Debugger Commands A.2.2 Monitoring Process Activation and Termination A.2.3 Interrupting the Execution of an Image to Connect It to the Debugger A.2.3.1 Using the CTRL/Y - DEBUG Sequence to Invoke the Debugger A.2.3.2 Using the CONNECT Command to Interrupt an Image A.2.4 Screen Mode Features for Multiprocess Debugging A.2.5 Setting Watchpoints in Global Sections A.2.6 Compatibility of Multiprocess Commands with the Default Configuration A.3 System Management Considerations for Multiprocess Debugging A.3.1 User Quotas A.3.2 System Resources B Contents of the FORTRAN System Library FORSYSDEF C Using System Services-Examples C.1 Calling RMS Procedures C.2 Synchronizing Processes Using an AST Routine C.3 Accessing Devices Using Synchronous I/O C.4 Communicating with Other Processes C.5 Sharing Data C.6 Displaying Data at Terminals C.7 Creating, Accessing, and Ordering Files C.8 Measuring and Improving Performance C.9 Accessing Help Libraries C.10 Creating and Managing Other Processes D Compatibility: VAX FORTRAN and FORTRAN-66 D.1 Minimum Iteration Count for DO Loops D.2 EXTERNAL Statement D.3 OPEN Statement Keyword Defaults D.3.1 BLANK Keyword Default D.3.2 OPEN Statement's STATUS Keyword Default D.4 X Format Edit Descriptor D.5 Open Operation on a Connected Unit E Compatibility: VAX FORTRAN and PDP-11 FORTRAN E.1 Language Differences E.1.1 Logical Tests E.1.2 Floating-Point Results E.1.3 Character and Hollerith Constants E.1.4 Logical Unit Numbers E.1.5 Assigned GO TO Label List E.1.6 DISPOSE= ' PRINT ' Specification E.2 Run-Time Support Differences E.2.1 Run-Time Library Error Numbers E.2.2 Error Handling and Reporting E.2.2.1 Continuing After Errors E.2.2.2 I/O Errors with IOSTAT or ERR Specified E.2.2.3 OPEN/CLOSE Statement Errors E.2.3 OPEN Statement Keywords E.3 Utility Subroutines E.3.1 ASSIGN Subroutine E.3.2 CLOSE Subroutine E.3.3 ERRSET Subroutine E.3.4 ERRTST Subroutine E.3.5 FDBSET Subroutine E.3.6 IRAD50 Subroutine E.3.7 RAD50 Function E.3.8 RAN Function E.3.9 RANDU Subroutine E.3.10 R50ASC Subroutine E.3.11 USEREX Subroutine F Diagnostic Messages F.1 Diagnostic Messages from the VAX FORTRAN Compiler F.1.1 Source Program Diagnostic Messages F.1.2 Compiler-Fatal Diagnostic Messages F.1.3 Compiler Limits F.2 Diagnostic Messages from the VAX Run-Time System F.3 DICTIONARY Error Messages EXAMPLES 1-1 Sample Listing of Source Code 1-2 Sample Listing of Machine Code 1-3 Sample Storage Map Section 1-4 Sample Compilation Summary 2-1 Sample VAX FORTRAN Program and Traceback 6-1 Subroutine Using a Data Structure Argument 6-2 CTRL/C Trapping Example 11-1 RELAX Source Program 11-2 RELAX Machine Code (Optimized) 13-1 Character Data Program Example 15-1 Sample VAX FORTRAN Parallel-Processing Source Program 15-2 Sample Parallel-Processing Debugging Session F-1 Sample Diagnostic Messages (Listing Format) FIGURES 1-1 Creating and Using a Text Library 3-1 Debugger Keypad Key Functions 6-1 Structure of a VAX Argument List 6-2 Example of a VAX Argument List 9-1 Sample Stack Scan for Condition Handlers 9-2 Effects of Calls to LIB$SIGNAL or LIB$STOP 10-1 General Format of Floating-Point Data 15-1 Processing an Indexed DO Loop in Parallel TABLES 1-1 FORTRAN Command Qualifiers 1-2 Commands to Control Library Files 2-1 LINK Command Qualifiers 2-2 /DEBUG and /TRACEBACK Qualifiers 4-1 Available I/O Statements 4-2 Predefined System Logical Names 4-3 Implicit FORTRAN Logical Units 4-4 Valid Combinations of Record Access Mode and File Organization 5-1 Summary of Run-Time Errors 6-1 VAX Register Usage 6-2 Function Return Values 6-3 Run-Time Library Facilities 6-4 System Services 6-5 VAX FORTRAN Implementation of VMS Data Types 6-6 Variable Data Type Requirements 7-1 RMS Fields Available with USEROPEN 9-1 Severity Codes for Exception Condition Values 9-2 Condition-Handler Function Return Values 10-1 PSECT Names and Attributes 10-2 VAX FORTRAN PSECT Attributes 15-1 VAX FORTRAN Parallel-Processing Support Mechanisms 15-2 Sysgen Parameters Requiring Changes for Parallel Processing A-1 Debugging States A-2 Process Specifications A-3 Changed and New Keypad Key Functions B-1 Contents of System Library FORSYSDEF E-1 Default Logical Unit Numbers F-1 Source Program Diagnostic Messages F-2 Compiler-Fatal Diagnostic Messages F-3 Compiler Limits F-4 Run-Time Diagnostic Messages F-5 Run-Time Diagnostic Messages for Parallel Processing F-6 CRX Error Messages