HP for OpenVMS Fortran User Manual

PDF

Dokument

Reklamë

HP Fortran for OpenVMS

User Manual

Order Number: AA–QJRWD–TE

January 2005

This manual provides information about the HP Fortran program development environment on HP OpenVMS systems.

Revision/Update Information: This revised manual supersedes the

Compaq Fortran User Manual for

OpenVMS Alpha Systems, Version 7.4.

Software Version: HP Fortran for OpenVMS Systems Version

8.0

Operating System: OpenVMS Industry Standard 64 Systems

Version 8.2

OpenVMS Alpha Systems Version 8.2

Hewlett-Packard Company

Palo Alto, California

Confidential computer software. Valid license from HP required for possession, use or copying.

Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software

Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor’s standard commercial license.

The information contained herein is subject to change without notice. The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein.

Intel and Itanium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries.

Printed in the US

ZK6443

This manual is available on CD-ROM.

This document was prepared using DECdocument, Version 3.3-1b.

Preface

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1 Getting Started

1.1

1.2

1.3

1.4

1.4.1

1.4.2

1.4.3

1.5

Fortran Standards Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . .

HP Fortran Programming Environment . . . . . . . . . . . . . . . . . . .

Commands to Create and Run an Executable Program . . . . . . . .

Creating and Running a Program Using a Module and Separate

Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Commands to Create the Executable Program . . . . . . . . . . . .

Running the Sample Program . . . . . . . . . . . . . . . . . . . . . . . .

Debugging the Sample Program . . . . . . . . . . . . . . . . . . . . . . .

Program Development Stages and Tools . . . . . . . . . . . . . . . . . . .

2 Compiling HP Fortran Programs

2.1

2.2

2.2.1

2.2.2

2.2.3

2.2.3.1

2.2.3.2

2.2.4

2.2.4.1

2.2.4.2

2.2.4.3

2.2.4.4

2.2.5

Functions of the Compiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

FORTRAN Command Syntax, Use, and Examples . . . . . . . . . . . .

Specifying Input Files and Source Form . . . . . . . . . . . . . . . .

Specifying Multiple Input Files . . . . . . . . . . . . . . . . . . . . . . .

Creating and Using Module Files . . . . . . . . . . . . . . . . . . . . . .

Creating Module Files . . . . . . . . . . . . . . . . . . . . . . . . . . .

Using Module Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Using Include Files and Include Text Library Modules . . . . .

Using Include Files and INCLUDE Statement Forms . . .

INCLUDE Statement Forms for Including Text Library

Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Using Include Text Library Modules for a Specified

Library Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Using Include Text Library Modules for an Unspecified

Library Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Specifying Output Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

xxiii

1–1

1–2

1–5

1–6

1–8

1–9

1–10

2–1

2–2

2–3

2–4

2–5

2–6

2–7

2–8

2–9

2–10

2–11

2–14 iii

2.3.7

2.3.8

2.3.9

2.3.10

2.3.11

2.3.12

2.3.13

2.3.14

2.3.15

2.3.16

2.3.17

2.3.18

2.3.19

2.2.6

2.2.6.1

2.2.6.2

2.2.6.3

2.2.6.4

2.2.6.5

2.2.6.6

2.2.6.7

2.3

2.3.1

2.3.2

2.3.3

2.3.4

2.3.5

2.3.6

2.3.20

2.3.21

2.3.22

2.3.23

2.3.24

2.3.25

2.3.26

2.3.27

2.3.28

Examples of the FORTRAN Command . . . . . . . . . . . . . . . . .

Naming the Object File . . . . . . . . . . . . . . . . . . . . . . . . . .

Compiler Source Checking Only (No Object File) . . . . . . .

Requesting a Listing File and Contents . . . . . . . . . . . . . .

Compiling Multiple Files . . . . . . . . . . . . . . . . . . . . . . . . .

Requesting Additional Compile-Time and Run-Time

Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Checking Fortran 90 or 95 Standard Conformance . . . . .

Requesting Additional Optimizations . . . . . . . . . . . . . . . .

FORTRAN Command Qualifiers . . . . . . . . . . . . . . . . . . . . . . . . .

FORTRAN Command Qualifier Syntax . . . . . . . . . . . . . . . . .

Summary of FORTRAN Command Qualifiers . . . . . . . . . . . .

/ALIGNMENT — Data Alignment . . . . . . . . . . . . . . . . . . . . .

/ANALYSIS_DATA—Create Analysis Data File . . . . . . . . . . .

/ANNOTATIONS — Code Descriptions . . . . . . . . . . . . . . . . .

/ARCHITECTURE — Architecture Code Instructions (Alpha only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

/ASSUME — Compiler Assumptions . . . . . . . . . . . . . . . . . . .

/AUTOMATIC — Data Storage . . . . . . . . . . . . . . . . . . . . . . .

/BY_REF_CALL — Character Literal Argument Passing . . .

/CCDEFAULT — Carriage Control for Terminals . . . . . . . . . .

/CHECK — Generate Code for Run-Time Checking . . . . . . . .

/CONVERT — Unformatted Numeric Data Conversion . . . . .

/D_LINES — Debugging Statement Indicator, Column 1 . . . .

/DEBUG — Object File Traceback and Symbol Table . . . . . .

/DIAGNOSTICS — Create Diagnostics File . . . . . . . . . . . . .

/DML — Invoke Fortran DML Preprocessor . . . . . . . . . . . . .

/DOUBLE_SIZE — DOUBLE PRECISION Data Size . . . . . .

/ERROR_LIMIT — Limit Compiler Messages . . . . . . . . . . . .

/EXTEND_SOURCE — Line Length for Fixed-Form

Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

/F77 — FORTRAN IV or FORTRAN-77 Compatibility . . . . . .

/FAST — Request Fast Run-Time Performance . . . . . . . . . . .

/FLOAT — Specify Floating-Point Format in Memory . . . . . .

/GRANULARITY — Control Shared Memory Access to

Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

/IEEE_MODE — Control IEEE Arithmetic Exception

Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

/INCLUDE — Add Directory for INCLUDE and Module File

Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

/INTEGER_SIZE — Integer and Logical Data Size . . . . . . . .

/LIBRARY — Specify File as Text Library . . . . . . . . . . . . . . .

/LIST — Request Listing File . . . . . . . . . . . . . . . . . . . . . . . .

2–33

2–35

2–40

2–41

2–42

2–45

2–49

2–50

2–51

2–52

2–53

2–54

2–15

2–16

2–17

2–18

2–27

2–31

2–32

2–57

2–58

2–60

2–62

2–63

2.4

2.4.1

2.4.2

2.5

2.5.1

2.5.2

2.6

2.6.1

2.6.2

2.3.29

2.3.30

2.3.31

2.3.32

2.3.33

2.3.34

2.3.35

2.3.36

2.3.37

2.3.38

2.3.39

2.3.40

2.3.41

2.3.42

2.3.43

2.3.44

2.3.45

2.3.46

2.3.47

2.3.48

2.3.49

2.3.50

2.3.51

/MACHINE_CODE — Request Machine Code in Listing

File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

/MATH_LIBRARY — Fast or Accurate Math Library

Routines (Alpha only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

/MODULE — Placement of Module Files . . . . . . . . . . . . . . . .

/NAMES — Control Case of External Names . . . . . . . . . . . . .

/OBJECT — Specify Name or Prevent Object File

Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

/OLD_F77 — Use Old FORTRAN 77 Compiler (Alpha only)

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

/OPTIMIZE — Specify Compiler Optimizations . . . . . . . . . .

/PAD_SOURCE — Pad Source Lines with Spaces . . . . . . . . .

/REAL_SIZE — Floating-Point Data Size . . . . . . . . . . . . . . .

/RECURSIVE — Data Storage and Recursion . . . . . . . . . . .

/REENTRANCY — Specify Threaded or Asynchronous

Reentrancy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

/ROUNDING_MODE — Specify IEEE Floating-Point

Rounding Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

/SEPARATE_COMPILATION — Control Compilation Unit

Use in Object Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

/SEVERITY — Specify Compiler Diagnostic Severity . . . . . . .

/SHOW — Control Source Content in Listing File . . . . . . . . .

/SOURCE_FORM — Fortran 90/95 Source Form . . . . . . . . . .

/STANDARD — Perform Fortran 90/95 Standards

Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

/SYNCHRONOUS_EXCEPTIONS — Report Exceptions More

Precisely (Alpha only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

/SYNTAX_ONLY — Do Not Create Object File . . . . . . . . . . .

/VERSION — Display the HP Fortran Version Number . . . .

/TIE — Enable Code for Shared Translated Images . . . . . . .

/VMS — Request Compaq Fortran 77 for OpenVMS VAX

Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

/WARNINGS — Warning Messages and Compiler

Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Creating and Maintaining Text Libraries . . . . . . . . . . . . . . . . . . .

Using the LIBRARY Commands . . . . . . . . . . . . . . . . . . . . . .

Naming Text Library Modules . . . . . . . . . . . . . . . . . . . . . . . .

Using CDD/Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Accessing CDD/Repository from HP Fortran Programs . . . . .

HP Fortran and CDD/Repository Data Types . . . . . . . . . . . . .

Compiler Limits, Diagnostic Messages, and Error Conditions . . .

Compiler Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Compiler Diagnostic Messages and Error Conditions . . . . . . .

2–68

2–76

2–78

2–79

2–65

2–67

2–68

2–81

2–82

2–83

2–84

2–86

2–87

2–88

2–89

2–93

2–95

2–96

2–98

2–99

2–101

2–102 v

2.7

2.7.1

2.7.2

2.7.3

2.7.4

2.7.5

Compiler Output Listing Format . . . . . . . . . . . . . . . . . . . . . . . . .

Source Code Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Machine Code Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Annotations Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Storage Map Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Compilation Summary Section . . . . . . . . . . . . . . . . . . . . . . . .

3 Linking and Running HP Fortran Programs

3.2.3

3.2.4

3.2.5

3.2.6

3.2.7

3.3

3.3.1

3.3.2

3.3.3

3.3.4

3.4

3.1

3.2

3.2.1

3.2.1.1

3.2.1.2

3.2.1.3

3.2.2

3.4.1

3.4.2

Linker Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

LINK Command Qualifiers and Messages . . . . . . . . . . . . . . . . . .

Linker Output File Qualifiers . . . . . . . . . . . . . . . . . . . . . . . .

Image File Qualifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . .

/NATIVE_ONLY Qualifier . . . . . . . . . . . . . . . . . . . . . . . .

Map File Qualifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

/DEBUG and /TRACEBACK Qualifiers . . . . . . . . . . . . . . . . .

Linker Input File Qualifiers . . . . . . . . . . . . . . . . . . . . . . . . . .

Linker Symbol Table Qualifier . . . . . . . . . . . . . . . . . . . . . . . .

Linker Options File Qualifier . . . . . . . . . . . . . . . . . . . . . . . . .

Other Linker Qualifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Linker Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Running HP Fortran Programs . . . . . . . . . . . . . . . . . . . . . . . . . .

RUN Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

System Processing at Image Exit . . . . . . . . . . . . . . . . . . . . . .

Interrupting a Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Returning Status Values to the Command Interpreter . . . . . .

Symbol Table and Traceback Information: Locating Run-Time

Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Effects of Error-Related Command Qualifiers . . . . . . . . . . . .

Sample Source Program and Traceback . . . . . . . . . . . . . . . . .

4 Using the OpenVMS Debugger

4.1

4.2

4.2.1

4.2.2

4.2.3

4.2.4

4.2.5

4.2.6

4.2.7

Debugger Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Getting Started with the Debugger . . . . . . . . . . . . . . . . . . . . . . .

Compiling and Linking a Program to Prepare for

Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Establishing the Debugging Configuration and Interface . . . .

Invoking the Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Debugger Commands Used Often . . . . . . . . . . . . . . . . . . . . .

Debugger Breakpoints, Tracepoints, and Watchpoints . . . . . .

Ending a Debugging Session . . . . . . . . . . . . . . . . . . . . . . . . .

Notes on Debugger Support for HP Fortran . . . . . . . . . . . . . .

2–103

2–104

2–105

2–111

2–112

2–114

3–7

3–9

3–10

3–11

3–12

3–1

3–3

3–4

3–5

3–6

3–7

3–13

3–14

4–1

4–2

4–3

4–4

4–6

4–8

4–8 vi

4.5.1

4.5.2

4.5.3

4.5.4

4.5.5

4.5.6

4.5.7

4.5.8

4.3

4.4

4.4.1

4.4.2

4.4.3

4.4.4

4.4.5

4.5

4.5.9

4.5.10

4.5.11

4.5.12

4.5.13

4.6

4.7

Sample Debugging Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Displaying HP Fortran Variables . . . . . . . . . . . . . . . . . . . . . . . . .

Accessing HP Fortran Common Block Variables . . . . . . . . . .

Accessing HP Fortran Derived-Type Variables . . . . . . . . . . . .

Accessing HP Fortran Record Variables . . . . . . . . . . . . . . . . .

Accessing HP Fortran Array Variables . . . . . . . . . . . . . . . . . .

Accessing HP Fortran Module Variables . . . . . . . . . . . . . . . .

Debugger Command Summary . . . . . . . . . . . . . . . . . . . . . . . . . .

Starting and Terminating a Debugging Session . . . . . . . . . . .

Controlling and Monitoring Program Execution . . . . . . . . . . .

Examining and Manipulating Data . . . . . . . . . . . . . . . . . . . .

Controlling Type Selection and Symbolization . . . . . . . . . . . .

Controlling Symbol Lookup . . . . . . . . . . . . . . . . . . . . . . . . . .

Displaying Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Using Screen Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Editing Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Defining Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Using Keypad Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Using Command Procedures and Log Files . . . . . . . . . . . . . .

Using Control Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Additional Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Locating an Exception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Locating Unaligned Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5 Performance: Making Programs Run Faster

5.1

5.1.1

5.1.2

5.1.3

5.2

5.2.1

5.2.1.1

5.2.1.2

5.2.2

5.3

5.3.1

5.3.2

Software Environment and Efficient Compilation . . . . . . . . . . . .

Install the Latest Version of HP Fortran and Performance

Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Compile Using Multiple Source Files and Appropriate

FORTRAN Qualifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Process Environment and Related Influences on

Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Analyzing Program Performance . . . . . . . . . . . . . . . . . . . . . . . . .

Measuring Performance Using LIB$xxxx_TIMER Routines or

Command Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

The LIB$xxxx_TIMER Routines . . . . . . . . . . . . . . . . . . . .

Using a Command Procedure . . . . . . . . . . . . . . . . . . . . . .

Performance and Coverage Analyzer (PCA) . . . . . . . . . . . . . .

Data Alignment Considerations . . . . . . . . . . . . . . . . . . . . . . . . . .

Causes of Unaligned Data and Ensuring Natural

Alignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Checking for Inefficient Unaligned Data . . . . . . . . . . . . . . . .

4–18

4–19

4–20

4–21

4–22

4–23

4–9

4–15

4–16

4–17

4–18

4–23

4–24

4–25

4–27

5–1

5–2

5–3

5–7

5–8

5–9

5–13

5–16

5–17

5–18

5–21 vii

viii

5.5.3

5.5.4

5.5.5

5.5.6

5.5.7

5.5.8

5.5.9

5.6

5.6.1

5.3.4

5.4

5.4.1

5.4.2

5.5

5.5.1

5.5.2

5.6.2

5.6.3

5.6.4

5.6.5

5.6.6

5.6.7

5.7

5.7.1

5.7.2

5.7.2.1

5.7.2.2

5.7.2.3

5.7.2.4

5.7.2.5

5.7.2.6

5.7.2.7

5.7.3

5.7.4

5.7.4.1

5.7.4.2

5.3.3

5.3.3.1

5.3.3.2

5.3.3.3

Ordering Data Declarations to Avoid Unaligned Data . . . . . .

Arranging Data Items in Common Blocks . . . . . . . . . . . .

Arranging Data Items in Derived-Type Data . . . . . . . . . .

Arranging Data Items in Compaq Fortran 77 Record

Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Qualifiers Controlling Alignment . . . . . . . . . . . . . . . . . . . . . .

Using Arrays Efficiently . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Accessing Arrays Efficiently . . . . . . . . . . . . . . . . . . . . . . . . . .

Passing Array Arguments Efficiently . . . . . . . . . . . . . . . . . . .

Improving Overall I/O Performance . . . . . . . . . . . . . . . . . . . . . . .

Use Unformatted Files Instead of Formatted Files . . . . . . . .

Write Whole Arrays or Strings . . . . . . . . . . . . . . . . . . . . . . . .

Write Array Data in the Natural Storage Order . . . . . . . . . .

Use Memory for Intermediate Results . . . . . . . . . . . . . . . . . .

Defaults for Blocksize and Buffer Count . . . . . . . . . . . . . . . .

Specify RECL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Use the Optimal Record Type . . . . . . . . . . . . . . . . . . . . . . . .

Enable Implied-DO Loop Collapsing . . . . . . . . . . . . . . . . . . .

Use of Variable Format Expressions . . . . . . . . . . . . . . . . . . .

Additional Source Code Guidelines for Run-Time Efficiency . . . .

Avoid Small or Large Integer and Logical Data Items (Alpha only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Avoid Mixed Data Type Arithmetic Expressions . . . . . . . . . .

Use Efficient Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Avoid Using Slow Arithmetic Operators . . . . . . . . . . . . . . . . .

Avoid EQUIVALENCE Statement Use . . . . . . . . . . . . . . . . . .

Use Statement Functions and Internal Subprograms . . . . . .

Code DO Loops for Efficiency . . . . . . . . . . . . . . . . . . . . . . . . .

Optimization Levels: /OPTIMIZE=LEVEL=n Qualifier . . . . . . . .

Optimizations Performed at All Optimization Levels . . . . . . .

Local (Minimal) Optimizations . . . . . . . . . . . . . . . . . . . . . . . .

Common Subexpression Elimination . . . . . . . . . . . . . . . .

Integer Multiplication and Division Expansion . . . . . . . .

Compile-Time Operations . . . . . . . . . . . . . . . . . . . . . . . . .

Value Propagation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Dead Store Elimination . . . . . . . . . . . . . . . . . . . . . . . . . .

Mixed Real/Complex Operations . . . . . . . . . . . . . . . . . . .

Global Optimizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Additional Global Optimizations . . . . . . . . . . . . . . . . . . . . . .

Loop Unrolling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Code Replication to Eliminate Branches . . . . . . . . . . . . .

5–22

5–24

5–35

5–36

5–37

5–25

5–26

5–28

5–32

5–33

5–34

5–43

5–44

5–45

5–46

5–47

5–48

5–50

5–51

5–38

5–39

5–40

5–42

5–43

5.7.5

5.7.5.1

5.7.5.2

5.7.5.3

5.7.6

5.8

5.8.1

5.8.2

5.8.3

5.8.4

5.8.5

5.8.6

5.8.7

5.8.8

5.8.9

5.9

5.9.1

5.9.2

5.9.3

Automatic Inlining and Software Pipelining . . . . . . . . . . . . .

Interprocedure Analysis . . . . . . . . . . . . . . . . . . . . . . . . . .

Inlining Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Software Pipelining . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Loop Transformation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Other Qualifiers Related to Optimization . . . . . . . . . . . . . . . . . .

Loop Transformation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Software Pipelining . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Setting Multiple Qualifiers with the /FAST Qualifier . . . . . . .

Controlling Loop Unrolling . . . . . . . . . . . . . . . . . . . . . . . . . .

Controlling the Inlining of Procedures . . . . . . . . . . . . . . . . . .

Requesting Optimized Code for a Specific Processor

Generation (Alpha only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Requesting Generated Code for a Specific Processor

Generation (Alpha only) . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Arithmetic Reordering Optimizations . . . . . . . . . . . . . . . . . .

Dummy Aliasing Assumption . . . . . . . . . . . . . . . . . . . . . . . . .

Compiler Directives Related to Performance . . . . . . . . . . . . . . . .

Using the cDEC$ OPTIONS Directive . . . . . . . . . . . . . . . . . .

Using the cDEC$ UNROLL Directive to Control Loop

Unrolling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Using the cDEC$ IVDEP Directive to Control Certain Loop

Optimizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6 HP Fortran Input/Output

6.1

6.2

6.3

6.4

6.5

6.5.1

6.5.2

6.5.3

6.5.3.1

6.5.3.2

6.5.3.3

6.5.3.4

6.5.3.5

6.5.3.6

6.5.4

6.6

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Logical I/O Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Types of I/O Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Forms of I/O Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Types of Files and File Characteristics . . . . . . . . . . . . . . . . . . . .

File Organizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Internal Files and Scratch Files . . . . . . . . . . . . . . . . . . . . . . .

I/O Record Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Portability Considerations of Record Types . . . . . . . . . . .

Fixed-Length Records . . . . . . . . . . . . . . . . . . . . . . . . . . .

Variable-Length Records . . . . . . . . . . . . . . . . . . . . . . . . .

Segmented Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Stream Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Stream_CR and Stream_LF Records . . . . . . . . . . . . . . . .

Other File Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . .

Opening Files and the OPEN Statement . . . . . . . . . . . . . . . . . . .

6–11

6–12

6–13

6–14

6–15

6–1

6–2

6–3

6–5

6–7

6–9

6–10

5–52

5–53

5–54

5–55

5–56

5–57

5–58

5–60

5–61

5–63

5–64

5–64 ix

6.6.1

6.6.1.1

6.6.1.2

6.6.2

6.6.3

6.7

6.7.1

6.7.2

6.7.3

6.8

6.9

6.9.1

6.9.2

6.9.2.1

6.9.2.2

6.9.2.3

Preconnected Files and Fortran Logical Names . . . . . . . . . . .

Preconnected Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

HP Fortran Logical Names . . . . . . . . . . . . . . . . . . . . . . .

Disk Files and File Specifications . . . . . . . . . . . . . . . . . . . . .

OPEN Statement Specifiers . . . . . . . . . . . . . . . . . . . . . . . . . .

Obtaining File Information: The INQUIRE Statement . . . . . . . .

Inquiry by Unit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Inquiry by File Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Inquiry by Output Item List . . . . . . . . . . . . . . . . . . . . . . . . .

Closing a File: The CLOSE Statement . . . . . . . . . . . . . . . . . . . .

Record Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Record I/O Statement Specifiers . . . . . . . . . . . . . . . . . . . . . . .

Record Access Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Sequential Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Direct Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Keyed Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6.9.3

6.9.4

6.9.5

6.9.6

Shared File Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Specifying the Initial Record Position . . . . . . . . . . . . . . . . . .

Advancing and Nonadvancing Record I/O . . . . . . . . . . . . . . .

Record Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6.10

Output Data Buffering and RMS Journaling . . . . . . . . . . . . . . . .

7 Run-Time Errors

7.1

7.2

7.2.1

7.2.2

7.3

7.3.1

7.3.2

7.4

Run-Time Error Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

HP Fortran RTL Default Error Processing . . . . . . . . . . . . . . . . .

Run-Time Message Format . . . . . . . . . . . . . . . . . . . . . . . . . .

Run-Time Message Severity Levels . . . . . . . . . . . . . . . . . . . .

Handling Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Using the ERR, EOR, and END Branch Specifiers . . . . . . . .

Using the IOSTAT Specifier . . . . . . . . . . . . . . . . . . . . . . . . . .

List of Run-Time Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8 Data Types and Representation

8.1

8.2

8.2.1

8.2.2

8.2.3

8.2.4

8.2.5

8.3

Summary of Data Types and Characteristics . . . . . . . . . . . . . . . .

Integer Data Representations . . . . . . . . . . . . . . . . . . . . . . . . . . .

Integer Declarations and FORTRAN Command Qualifiers . .

INTEGER (KIND=1) or INTEGER*1 Representation . . . . . .

INTEGER (KIND=2) or INTEGER*2 Representation . . . . . .

INTEGER (KIND=4) or INTEGER*4 Representation . . . . . .

INTEGER (KIND=8) or INTEGER*8 Representation . . . . . .

Logical Data Representations . . . . . . . . . . . . . . . . . . . . . . . . . . .

6–27

6–28

6–29

6–30

6–31

6–32

6–16

6–17

6–18

6–19

6–22

6–25

6–26

6–32

6–35

6–36

6–37

6–39

7–1

7–2

7–3

7–4

7–5

7–6

7–8

8–2

8–5

8–6

8–7

8.4

8.4.1

8.4.2

8.4.2.1

8.4.2.2

8.4.3

8.4.3.1

8.4.3.2

8.4.3.3

8.4.4

8.4.5

8.4.6

8.4.7

8.4.8

8.5

8.6

Native Floating-Point Representations and IEEE Exceptional

Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

REAL, COMPLEX, and DOUBLE PRECISION Declarations and FORTRAN Qualifiers . . . . . . . . . . . . . . . . . . . . . . . . . . .

REAL (KIND=4) or REAL*4 Representations . . . . . . . . . . . .

IEEE S_float Representation . . . . . . . . . . . . . . . . . . . . . .

VAX F_float Representation . . . . . . . . . . . . . . . . . . . . . . .

REAL (KIND=8) or REAL*8 Representations . . . . . . . . . . . .

IEEE T_float Representation . . . . . . . . . . . . . . . . . . . . . .

VAX G_float Representation . . . . . . . . . . . . . . . . . . . . . . .

VAX D_float Representation . . . . . . . . . . . . . . . . . . . . . . .

REAL (KIND=16) or REAL*16 X_float Representation . . . . .

COMPLEX (KIND=4) or COMPLEX*8 Representations . . . .

COMPLEX (KIND=8) or COMPLEX*16 Representations . . .

COMPLEX (KIND=16) or COMPLEX*32 Representation . . .

Exceptional IEEE Floating-Point Representations . . . . . . . . .

Character Representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Hollerith Representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

9 Converting Unformatted Numeric Data

9.1

9.2

9.3

9.4

9.5

9.5.1

9.5.2

9.5.3

9.5.4

9.5.5

9.6

Overview of Converting Unformatted Numeric Data . . . . . . . . . .

Endian Order of Numeric Formats . . . . . . . . . . . . . . . . . . . . . . .

Native and Supported Nonnative Numeric Formats . . . . . . . . . .

Limitations of Numeric Conversion . . . . . . . . . . . . . . . . . . . . . . .

Methods of Specifying the Unformatted Numeric Format . . . . . .

Logical Name FOR$CONVERTnnn Method . . . . . . . . . . . . . .

Logical Name FOR$CONVERT.ext (and FOR$CONVERT_ext)

Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

OPEN Statement CONVERT=’keyword’ Method . . . . . . . . . .

OPTIONS Statement /CONVERT=keyword Method . . . . . . . .

FORTRAN Command /CONVERT=keyword Qualifier

Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Additional Information on Nonnative Data . . . . . . . . . . . . . . . . .

10 Using HP Fortran in the Common Language Environment

10.1

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

10.2

HP Fortran Procedures and Argument Passing . . . . . . . . . . . . . .

10.2.1

Explicit and Implicit Interfaces . . . . . . . . . . . . . . . . . . . . . . .

10.2.2

10.2.3

Types of HP Fortran Subprograms . . . . . . . . . . . . . . . . . . . . .

Using Procedure Interface Blocks . . . . . . . . . . . . . . . . . . . . .

10.2.4

Passing Arguments and Function Return Values . . . . . . . . . .

9–1

9–2

9–3

9–7

9–8

9–10

9–13

9–14

9–15

8–9

8–10

8–11

8–12

8–13

8–14

8–15

8–16

8–18

8–19

8–23

8–24

10–1

10–2

10–3

10–4

10–5

10–6 xi

xii

10.2.5

10.2.6

Passing Arrays as Arguments . . . . . . . . . . . . . . . . . . . . . . . .

Passing Pointers as Arguments . . . . . . . . . . . . . . . . . . . . . . .

10.2.7

HP Fortran Array Descriptor Format . . . . . . . . . . . . . . . . . .

10.3

Argument-Passing Mechanisms and Built-In Functions . . . . . . .

10.3.1

10.3.2

Passing Arguments by Descriptor—%DESCR Function . . . . .

Passing Addresses—%LOC Function . . . . . . . . . . . . . . . . . . .

10.3.3

Passing Arguments by Immediate Value—%VAL

Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

10.3.4

Passing Arguments by Reference—%REF Function . . . . . . . .

10.3.5

Examples of Argument Passing Built-in Functions . . . . . . . .

10.4

Using the cDEC$ ALIAS and cDEC$ ATTRIBUTES

Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

10.4.1

10.4.2

10.4.2.1

10.4.2.2

The cDEC$ ALIAS Directive . . . . . . . . . . . . . . . . . . . . . . . . .

The cDEC$ ATTRIBUTES Directive . . . . . . . . . . . . . . . . . . .

C Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

ALIAS Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

10.4.2.3

10.4.2.4

REFERENCE and VALUE Properties . . . . . . . . . . . . . . .

EXTERN and VARYING Properties . . . . . . . . . . . . . . . . .

10.4.2.5

ADDRESS64 Property . . . . . . . . . . . . . . . . . . . . . . . . . . .

10.5

OpenVMS Procedure-Calling Standard . . . . . . . . . . . . . . . . . . . .

10.5.1

10.5.1.1

10.5.2

10.5.3

Argument Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

10.6

OpenVMS System Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

10.6.1

10.6.2

Return Values of Procedures . . . . . . . . . . . . . . . . . . . . . . . . .

OpenVMS Run-Time Library Routines . . . . . . . . . . . . . . . . .

OpenVMS System Services Routines . . . . . . . . . . . . . . . . . . .

10.7

Calling Routines: General Considerations . . . . . . . . . . . . . . . . . .

10.8

Calling OpenVMS System Services . . . . . . . . . . . . . . . . . . . . . . .

10.8.1

10.8.2

Obtaining Values for System Symbols . . . . . . . . . . . . . . . . . .

Calling System Services by Function Reference . . . . . . . . . . .

10.8.3

10.8.4

10.8.4.1

10.8.4.2

Calling System Services as Subroutines . . . . . . . . . . . . . . . . .

Passing Arguments to System Services . . . . . . . . . . . . . . . . .

Immediate Value Arguments . . . . . . . . . . . . . . . . . . . . . .

Address Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

10.8.4.3

Descriptor Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . .

10.8.4.4

10.8.4.5

Data Structure Arguments . . . . . . . . . . . . . . . . . . . . . . . .

Examples of Passing Arguments . . . . . . . . . . . . . . . . . . .

10.9

Calling Between Compaq Fortran 77 and HP Fortran . . . . . . . . .

10.9.1

Argument Passing and Function Return Values . . . . . . . . . .

10.9.2

10.9.3

Using Data Items in Common Blocks . . . . . . . . . . . . . . . . . .

I/O to the Same Unit Number . . . . . . . . . . . . . . . . . . . . . . . .

10.10

Calling Between HP Fortran and HP C . . . . . . . . . . . . . . . . . . . .

10–8

10–9

10–10

10–11

10–12

10–13

10–14

10–26

10–28

10–29

10–30

10–31

10–38

10–40

10–41

10–44

10–48

10–49

10–15

10–16

10–17

10–19

10–20

10–21

10–23

10–24

10–25

10.10.1

10.10.2

10.10.3

10.10.4

Compiling and Linking Files . . . . . . . . . . . . . . . . . . . . . . . . .

Procedures and External Names . . . . . . . . . . . . . . . . . . . . . .

Invoking a C Function from HP Fortran . . . . . . . . . . . . . . . .

Invoking an HP Fortran Function or Subroutine from C . . . .

10.10.5

10.10.6

Equivalent Data Types for Function Return Values . . . . . . . .

Argument Association and Equivalent Data Types . . . . . . . .

10.10.6.1

10.10.6.2

HP Fortran Intrinsic Data Types . . . . . . . . . . . . . . . . . . .

Equivalent HP Fortran and C Data Types . . . . . . . . . . . .

10.10.7

Example of Passing Integer Data to C Functions . . . . . . . . . .

10.10.8

Example of Passing Complex Data to C Functions . . . . . . . .

10.10.9

Handling User-Defined Structures . . . . . . . . . . . . . . . . . . . . .

10.10.10

Handling Scalar Pointer Data . . . . . . . . . . . . . . . . . . . . . . . .

10.10.11

Handling Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

10.10.12

Handling Common Blocks of Data . . . . . . . . . . . . . . . . . . . . .

11 Using OpenVMS Record Management Services

11.1

Overview of OpenVMS Record Management Services . . . . . . . . .

11.2

RMS Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

11.2.1

Using FORSYSDEF Library Modules to Manipulate RMS

11.2.2

Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

File Access Block (FAB) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

11.2.3

Record Access Block (RAB) . . . . . . . . . . . . . . . . . . . . . . . . . .

11.2.4

Name Block (NAM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

11.2.5

Extended Attributes Blocks (XABs) . . . . . . . . . . . . . . . . . . . .

11.3

RMS Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

11.3.1

Declaring RMS System Service Names . . . . . . . . . . . . . . . . .

11.3.2

11.3.3

11.3.4

11.3.5

Arguments to RMS Services . . . . . . . . . . . . . . . . . . . . . . . . . .

Checking Status from RMS Services . . . . . . . . . . . . . . . . . . .

Opening a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Closing a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

11.3.6

11.3.7

Writing Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Reading Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

11.3.8

Other Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

11.4

User-Written Open Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . .

11.4.1

Examples of USEROPEN Routines . . . . . . . . . . . . . . . . . . . .

11.4.2

RMS Control Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

11.5

Example of Block Mode I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

11.5.1

Main Block Mode I/O Program—BIO . . . . . . . . . . . . . . . . . . .

11.5.2

Block Mode I/O USEROPEN Functions—BIOCREATE and

BIOREAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

11.5.2.1

11.5.2.2

OUTPUT Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

INPUT Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

10–49

10–50

10–51

10–52

10–53

10–55

10–56

10–58

10–59

10–61

10–63

11–1

11–2

11–4

11–6

11–8

11–11

11–13

11–15

11–16

11–17

11–18

11–19

11–20

11–21

11–23

11–24

11–31

11–32

11–33

11–35

11–36 xiii

12 Using Indexed Files

12.1

Overview of Indexed Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

12.2

Creating an Indexed File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

12.3

Writing Records to an Indexed File . . . . . . . . . . . . . . . . . . . . . . .

12.3.1

Duplicate Values in Key Fields . . . . . . . . . . . . . . . . . . . . . . .

12.3.2

Preventing the Indexing of Alternate Key Fields . . . . . . . . . .

12.4

Reading Records from an Indexed File . . . . . . . . . . . . . . . . . . . . .

12.5

Updating Records in an Indexed File . . . . . . . . . . . . . . . . . . . . . .

12.6

Deleting Records from an Indexed File . . . . . . . . . . . . . . . . . . . .

12.7

Current Record and Next Record Pointers . . . . . . . . . . . . . . . . . .

12.8

Exception Conditions When Using Indexed Files . . . . . . . . . . . . .

13 Interprocess Communication

13.1

HP Fortran Program Section Usage . . . . . . . . . . . . . . . . . . . . . . .

13.2

Local Processes: Sharing and Exchanging Data . . . . . . . . . . . . .

13.2.1

13.2.2

13.2.2.1

Sharing Images in Shareable Image Libraries . . . . . . . . . . . .

Sharing Data in Installed Common Areas . . . . . . . . . . . . . . .

Creating and Installing the Shareable Image Common

Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

13.2.2.2

13.2.2.3

13.2.3

13.2.3.1

13.2.3.2

Creating Programs to Access the Shareable Image

Common Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Synchronizing Access . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Creating and Using Mailboxes to Pass Information . . . . . . . .

Creating a Mailbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Sending and Receiving Data Using Mailboxes . . . . . . . . .

13.3

Remote Processes: Sharing and Exchanging Data . . . . . . . . . . . .

13.3.1

Remote File Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

13.3.2

Network Task-to-Task Communication . . . . . . . . . . . . . . . . .

14 Condition-Handling Facilities

14.1

Overview of Condition-Handling Facilities . . . . . . . . . . . . . . . . . .

14.2

Overview of the Condition-Handling Facility . . . . . . . . . . . . . . . .

14.3

Default Condition Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

14.4

User-Program Interactions with the CHF . . . . . . . . . . . . . . . . . .

14.4.1

Establishing and Removing Condition Handlers . . . . . . . . . .

14.4.2

14.4.3

Signaling a Condition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Condition Values and Symbols Passed to CHF . . . . . . . . . . . .

14.5

Operations Performed in Condition Handlers . . . . . . . . . . . . . . .

14.6

Coding Requirements of Condition Handlers . . . . . . . . . . . . . . . .

14.7

Returning from a Condition Handler . . . . . . . . . . . . . . . . . . . . . .

14–1

14–3

14–4

14–5

14–6

14–7

14–9

14–12

14–13

14–17

13–1

13–3

13–4

13–5

13–6

13–8

13–9

13–10

13–11

13–13

13–14

12–1

12–2

12–4

12–6

12–7

12–8

12–9 xiv

14.8

Matching Condition Values to Determine Program Behavior . . . .

14.9

Changing a Signal to a Return Status . . . . . . . . . . . . . . . . . . . . .

14.10

Changing a Signal to a Stop . . . . . . . . . . . . . . . . . . . . . . . . . . . .

14.11

Checking for Arithmetic Exceptions . . . . . . . . . . . . . . . . . . . . . . .

14.12

Checking for Data Alignment Traps . . . . . . . . . . . . . . . . . . . . . . .

14.13

Condition Handler Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

15 Using the Compaq Extended Math Library (CXML) (Alpha

Only)

15.1

What Is CXML? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

15.2

CXML Routine Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

15.3

Using CXML from Fortran . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

15.4

CXML Program Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

A Differences Between HP Fortran on OpenVMS I64 and

OpenVMS Alpha Systems

A.1

A.2

A.3

A.4

A.5

A.5.1

A.5.2

A.6

A.6.1

A.6.1.1

A.6.1.2

A.6.1.3

A.6.1.4

A.6.2

HP Fortran Commands on OpenVMS I64 That Are Not Available on OpenVMS Alpha . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

HP Fortran Commands on OpenVMS Alpha That Are Not

Available on OpenVMS I64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Differences in Default Values . . . . . . . . . . . . . . . . . . . . . . . . . . .

Support for VAX-Format Floating-Point . . . . . . . . . . . . . . . . . . . .

Changes in Exception Numbers and Places . . . . . . . . . . . . . . . . .

Ranges of Representable Values . . . . . . . . . . . . . . . . . . . . . . .

Underflow in VAX Format with /CHECK=UNDERFLOW . . .

Changes in Exception-Mode Selection . . . . . . . . . . . . . . . . . . . . .

How to Change Exception-Handling or Rounding Mode . . . . .

Calling DFOR$GET_FPE and DFOR$SET_FPE . . . . . . .

Calling SYS$IEEE_SET_FP_CONTROL,

SYS$IEEE_SET_PRECISION_MODE, and

SYS$IEEE_SET_ROUNDING_MODE . . . . . . . . . . . . . . .

Additional Rules That You Should Follow . . . . . . . . . . . .

Whole-Program Mode and Library Calls . . . . . . . . . . . . .

Example of Changing Floating-Point Exception-Handling

Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

14–19

14–21

14–22

14–23

14–24

15–1

15–2

15–3

15–4

A–6

A–7

A–1

A–2

A–3

A–4

A–5

A–5 xv

B Compatibility: Compaq Fortran 77 and HP Fortran

B.1

B.2

B.3

B.3.1

B.3.2

B.3.3

B.3.4

B.4

B.5

B.5.1

B.5.2

B.6

B.7

B.8

HP Fortran and Compaq Fortran 77 Compatibility on Various

Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Major Language Features for Compatibility with Compaq

Fortran 77 for OpenVMS Systems . . . . . . . . . . . . . . . . . . . . . . . .

Language Features and Interpretation Differences Between

Compaq Fortran 77 and HP Fortran on OpenVMS Systems . . . .

Compaq Fortran 77 for OpenVMS Language Features Not

Implemented . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Compaq Fortran 77 for OpenVMS VAX Systems Language

Features Not Implemented . . . . . . . . . . . . . . . . . . . . . . . . . .

Compaq Fortran 77 for OpenVMS Language Interpretation

Differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Compaq Fortran 77 for OpenVMS VAX Systems

Interpretation Differences . . . . . . . . . . . . . . . . . . . . . . . . . . .

Improved HP Fortran Compiler Diagnostic Detection . . . . . . . . .

Compiler Command-Line Differences . . . . . . . . . . . . . . . . . . . . . .

Qualifiers Not Available on OpenVMS VAX Systems . . . . . . .

Qualifiers Specific to Compaq Fortran 77 for OpenVMS VAX

Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Interoperability with Translated Shared Images . . . . . . . . . . . . .

Porting Compaq Fortran 77 for OpenVMS VAX Systems Data . .

VAX H_float Representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

C Diagnostic Messages

C.1

C.2

C.2.1

C.2.2

C.3

Overview of Diagnostic Messages . . . . . . . . . . . . . . . . . . . . . . . . .

Diagnostic Messages from the HP Fortran Compiler . . . . . . . . . .

Source Program Diagnostic Messages . . . . . . . . . . . . . . . . . .

Compiler-Fatal Diagnostic Messages . . . . . . . . . . . . . . . . . . .

Messages from the HP Fortran Run-Time System . . . . . . . . . . . .

D HP Fortran Logical Names

D.1

D.2

D.3

Commands for Assigning and Deassigning Logical Names . . . . .

Compile-Time Logical Names . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Run-Time Logical Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

B–7

B–9

B–13

B–14

B–19

B–20

B–22

B–24

B–26

B–1

B–4

B–6

C–1

C–2

C–4

C–5

D–1

D–2

D–2 xvi

E Contents of the HP Fortran System Library FORSYSDEF

F Using System Services: Examples

F.1

F.2

F.3

F.4

Calling RMS Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Using an AST Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Accessing Devices Using Synchronous I/O . . . . . . . . . . . . . . . . . .

Communicating with Other Processes . . . . . . . . . . . . . . . . . . . . .

F.5

F.6

F.7

F.8

Sharing Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Displaying Data at Terminals . . . . . . . . . . . . . . . . . . . . . . . . . . .

Creating, Accessing, and Ordering Files . . . . . . . . . . . . . . . . . . .

Measuring and Improving Performance . . . . . . . . . . . . . . . . . . . .

F.9

Accessing Help Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

F.10

Creating and Managing Other Processes . . . . . . . . . . . . . . . . . . .

Index

Examples

1–1

1–2

1–3

1–4

2–1

2–2

2–3

2–4

2–5

2–6

2–7

3–1

4–1

4–2

5–1

Sample Main Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Sample Main Program That Uses a Module and Separate

Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Sample Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Sample Separate Function Declaration . . . . . . . . . . . . . . . . .

Sample Listing of Source Code on OpenVMS I64 . . . . . . . . . .

Sample Listing of Source Code on OpenVMS Alpha . . . . . . .

Sample (Partial) Listing of Machine Code on OpenVMS

I64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Sample (Partial) Listing of Machine Code on OpenVMS

Alpha . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Sample (Partial) Listing of Annotations . . . . . . . . . . . . . . . .

Sample Storage Map Section . . . . . . . . . . . . . . . . . . . . . . . . .

Sample Compilation Summary . . . . . . . . . . . . . . . . . . . . . . . .

Sample HP Fortran Program . . . . . . . . . . . . . . . . . . . . . . . .

Sample Program SQUARES . . . . . . . . . . . . . . . . . . . . . . . . . .

Sample Debugging Session Using Program SQUARES . . . . .

Measuring Program Performance Using LIB$SHOW_TIMER and LIB$INIT_TIMER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1–5

1–7

1–8

2–104

2–105

2–106

2–108

2–112

2–114

2–115

3–15

4–10

4–11

5–10

F–1

F–3

F–6

F–8

F–12

F–14

F–16

F–18

F–19

F–21 xvii

Figures

2–1

2–2

5–1

5–2

5–3

5–4

10–1

10–2

10–3

10–4

10–5

10–6

10–7

5–2

5–3

7–1

8–1

9–1

10–8

10–9

10–10

10–11

10–12

10–13

10–14

A–1

B–1

C–1

Command Procedure that Measures Program

Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Using the /ASSUME=DUMMY_ALIASES Qualifier . . . . . . . .

Handling OPEN Statement File Name Errors . . . . . . . . . . . .

Testing for a NaN Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Example Showing the Use of the FOR$CONVERT.ext

Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Calling C Functions and Passing Integer Arguments . . . . . .

Use of LIB$GET_VM and POINTER . . . . . . . . . . . . . . . . . . .

Subroutine Using a Data Structure Argument . . . . . . . . . . . .

Ctrl/C Trapping Example . . . . . . . . . . . . . . . . . . . . . . . . . . . .

HP Fortran Program Calling a Compaq Fortran 77

Subroutine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Compaq Fortran 77 Subroutine Called by an HP Fortran

Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

C Functions Called by an HP Fortran Program . . . . . . . . . . .

Calling C Functions and Passing Integer Arguments . . . . . .

Calling C Functions and Passing Complex Arguments . . . . .

Calling C Functions and Passing Pointer Arguments . . . . . .

C Functions Receiving Pointer Arguments . . . . . . . . . . . . . . .

C Function That Receives an Explicit-Shape Array . . . . . . . .

HP Fortran Program That Passes an Explicit-Shape

Array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Changing Floating-Point Exception Mode . . . . . . . . . . . . . . .

Using the CVT$CONVERT_FLOAT Routine . . . . . . . . . . . . .

Sample Diagnostic Messages (Listing Format) . . . . . . . . . . . .

5–14

5–62

7–7

8–22

9–11

10–18

10–27

10–41

10–43

10–46

10–47

10–55

10–56

10–57

10–60

10–62

10–63

A–8

B–25

C–4

Specifying the Format of Numeric Data for Unformatted

Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Creating and Using a Text Library . . . . . . . . . . . . . . . . . . . .

Common Block with Unaligned Data . . . . . . . . . . . . . . . . . . .

Common Block with Naturally Aligned Data . . . . . . . . . . . . .

Common Block with Naturally Aligned Reordered Data . . . .

Derived-Type Naturally Aligned Data (in

CATALOG_SPRING( )) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2–54

2–94

5–23

5–24

5–25 xviii

5–5

6–1

6–2

8–1

8–2

8–3

8–4

8–5

8–6

8–7

8–8

8–9

8–10

8–11

8–12

8–13

8–14

8–15

8–16

8–17

8–18

9–1

9–2

14–1

B–1

Memory Diagram of REC for Naturally Aligned Records . . .

Segmented Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Stream_CR and Stream_LF Records . . . . . . . . . . . . . . . . . . .

INTEGER (KIND=1) or INTEGER*1 Representation . . . . . .

INTEGER (KIND=2) or INTEGER*2 Representation . . . . . .

INTEGER (KIND=4) or INTEGER*4 Representation . . . . . .

INTEGER (KIND=8) or INTEGER*8 Representation . . . . . .

LOGICAL Representations . . . . . . . . . . . . . . . . . . . . . . . . . .

IEEE S_float REAL (KIND=4) or REAL*4 Representation . .

VAX F_float REAL (KIND=4) or REAL*4 Representation . . .

IEEE T_float REAL (KIND=8) or REAL*8 Representation . .

VAX G_float REAL (KIND=8) or REAL*8 Representation . . .

VAX D_float REAL (KIND=8) or REAL*8 Representation . . .

X_float REAL (KIND=16) Floating-Point Data

Representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

IEEE S_float COMPLEX (KIND=4) or COMPLEX*8

Representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

VAX F_float COMPLEX (KIND=4) or COMPLEX*8

Representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

IEEE T_float COMPLEX (KIND=8) or COMPLEX*16

Representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

VAX G_float COMPLEX (KIND=8) or COMPLEX*16

Representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

VAX D_float COMPLEX (KIND=8) or COMPLEX*16

Representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

COMPLEX (KIND=16) or COMPLEX*32 Representation . . .

CHARACTER Data Representation . . . . . . . . . . . . . . . . . . . .

Little and Big Endian Storage of an INTEGER Value . . . . . .

Sample Unformatted File Conversion . . . . . . . . . . . . . . . . . .

Effects of Calls to LIB$SIGNAL or LIB$STOP . . . . . . . . . . .

VAX H_float REAL*16 Representation (VAX Systems) . . . . . .

8–16

8–17

8–18

8–23

9–3

9–10

14–8

B–27

5–26

6–12

6–14

8–6

8–7

8–9

8–11

8–12

8–13

8–14

8–15

8–16 xix

Tables

1–1

2–1

2–2

2–3

2–4

Tools for Program Development and Testing . . . . . . . . . . . . .

FORTRAN Command Qualifiers . . . . . . . . . . . . . . . . . . . . . .

FORTRAN Command Flags and Categories . . . . . . . . . . . . . .

Commands to Control Library Files . . . . . . . . . . . . . . . . . . . .

CDO Data Types and Corresponding HP Fortran Data

Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2–5

3–1

3–2

5–1

Compiler Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

LINK Command Qualifiers . . . . . . . . . . . . . . . . . . . . . . . . . .

/DEBUG and /TRACEBACK Qualifiers . . . . . . . . . . . . . . . . .

FORTRAN Qualifiers Related to Run-Time Performance . . . .

5–2

5–3

7–1

8–1

8–2

9–1

Qualifiers that Slow Run-Time Performance . . . . . . . . . . . . .

Output Argument Array Types . . . . . . . . . . . . . . . . . . . . . . .

5–4 Types of Optimization Performed at Different

/OPTIMIZE=LEVEL=n Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6–1

6–2

6–3

6–4

Summary of I/O Statements . . . . . . . . . . . . . . . . . . . . . . . . . .

Available I/O Statements and Record I/O Forms . . . . . . . . . .

Predefined System Logical Names . . . . . . . . . . . . . . . . . . . . .

Implicit Fortran Logical Units . . . . . . . . . . . . . . . . . . . . . . . .

6–5 Valid Combinations of File Organization and Record Access

Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Summary of Run-Time Errors . . . . . . . . . . . . . . . . . . . . . . . .

HP Fortran Intrinsic Data Types, Storage, and Numeric

Ranges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

IEEE Exceptional Floating-Point Numbers . . . . . . . . . . . . . .

10–1

10–2

10–3

10–4

Unformatted Numeric Formats, Keywords, and Supported

Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

C Property and Argument Passing . . . . . . . . . . . . . . . . . . . . .

OpenVMS Alpha Register Usage . . . . . . . . . . . . . . . . . . . . . .

OpenVMS Alpha Function Return Values . . . . . . . . . . . . . . .

Run-Time Library Facilities . . . . . . . . . . . . . . . . . . . . . . . . . .

10–5

10–6

10–7

10–8

System Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

HP Fortran Implementation of OpenVMS Data Types . . . . . .

Variable Data Type Requirements . . . . . . . . . . . . . . . . . . . . .

HP Fortran and C Data Types . . . . . . . . . . . . . . . . . . . . . . . .

11–1

13–1

RMS Fields Available with USEROPEN . . . . . . . . . . . . . . . .

PSECT Names and Attributes . . . . . . . . . . . . . . . . . . . . . . . .

1–11

2–19

2–25

2–95

2–99

2–102

3–3

3–14

5–4

5–6

5–33

5–41

6–4

6–7

6–16

6–18

6–31

7–9

8–2

8–21

9–5

10–17

10–22

10–23

10–25

10–26

10–32

10–39

10–54

11–25

13–2 xx

13–2

14–1

14–2

14–3

14–4

15–1

B–1

B–2

B–3

B–4

C–1

D–1

D–2

E–1

HP Fortran PSECT Attributes . . . . . . . . . . . . . . . . . . . . . . . .

Severity Codes for Exception Condition Values . . . . . . . . . . .

Contents of SIGARGS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Contents of MECHARGS on OpenVMS Alpha Systems . . . . .

Condition-Handler Function Return Values . . . . . . . . . . . . . .

CXML Routine Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Summary of Language Compatibility . . . . . . . . . . . . . . . . . .

HP Fortran Qualifiers Without Equivalents in Compaq

Fortran 77 for OpenVMS VAX Systems . . . . . . . . . . . . . . . . .

Compaq Fortran 77 for OpenVMS VAX Systems Options Not in HP Fortran . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Floating-Point Data Formats on OpenVMS VAX and

OpenVMS I64 and Alpha Systems . . . . . . . . . . . . . . . . . . . . .

Run-Time Error Messages and Explanations . . . . . . . . . . . . .

HP Fortran Compile-Time Logical Names . . . . . . . . . . . . . . .

HP Fortran Run-Time Logical Names . . . . . . . . . . . . . . . . . .

Contents of System Library FORSYSDEF . . . . . . . . . . . . . . .

13–3

14–10

14–14

14–16

14–18

15–3

B–2

B–20

B–23

B–25

C–6

D–2

D–3

E–2 xxi

Preface

This manual describes the HP Fortran compiler command, compiler, and runtime environment. This includes how to compile, link, execute, and debug HP

Fortran programs on systems with Itanium or Alpha processor architectures running the HP OpenVMS operating system. It also describes performance guidelines, I/O and error-handling support, calling other procedures, and compatibility.

Note

In this manual, the term OpenVMS refers to both OpenVMS I64 and

OpenVMS Alpha systems. If there are differences in the behavior of the

HP Fortran compiler on the two operating systems, those differences are noted in the text.

Intended Audience

This manual assumes that:

• You already have a basic understanding of the Fortran 90/95 language.

Tutorial Fortran 90/95 language information is widely available in commercially published books (see the online release notes or the Preface of the HP Fortran for OpenVMS Language Reference Manual).

• You are familiar with the operating system commands used during program development and a text editor. Such information is available in the OpenVMS documentation set.

• You have access to the HP Fortran for OpenVMS Language Reference

Manual, which describes the HP Fortran 90/95 language.

xxiii

Document Structure

This manual consists of the following chapters and appendixes:

• Chapter 1 introduces the programmer to the HP Fortran compiler, its components, and related commands.

• Chapter 2 describes the FORTRAN command qualifiers in detail.

• Chapter 3 describes how to link and run a HP Fortran program.

• Chapter 4 describes the OpenVMS Debugger and some special considerations involved in debugging Fortran programs. It also lists some relevant programming tools and commands.

• Chapter 5 describes ways to improve run-time performance, including general software environment recommendations, appropriate FORTRAN command qualifiers, data alignment, efficiently performing I/O and array operations, other efficient coding techniques, profiling, and optimization.

• Chapter 6 provides information on HP Fortran I/O, including statement forms, file organizations, I/O record formats, file specifications, logical names, access modes, logical unit numbers, and efficient use of I/O.

• Chapter 7 lists run-time messages and describes how to control certain types of I/O errors in your I/O statements.

• Chapter 8 describes the native Fortran OpenVMS data types, including their numeric ranges, representation, and floating-point exceptional values.

It also discusses the intrinsic data types used with numeric data.

• Chapter 9 describes how to access unformatted files containing numeric little endian and big endian data different than the format used in memory.

• Chapter 10 describes how to call routines and pass arguments to them.

• Chapter 11 describes how to utilize OpenVMS Record Management

Services (RMS) from an HP Fortran program.

• Chapter 12 describes how to access records using indexed sequential access.

• Chapter 13 gives an introduction on how to exchange and share data among both local and remote processes.

• Chapter 14 describes facilities that can be used to handle—in a structured and consistent fashion—special conditions (errors or program-generated status conditions) that occur in large programs with many program units.

xxiv

• Chapter 15 provides information on the Compaq Extended Math Library

(CXML) (Alpha only), a comprehensive set of mathematical library routines callable from Fortran and other languages.

• Appendix A describes the differences between HP Fortran on OpenVMS

I64 systems and on OpenVMS Alpha systems.

• Appendix B describes the compatibility between HP Fortran for OpenVMS systems and HP Fortran on other platforms, especially Compaq Fortran 77 for OpenVMS systems.

• Appendix C describes diagnostic messages issued by the HP Fortran compiler and lists and describes messages from the HP Fortran Run-Time

Library (RTL) system.

• Appendix D lists the HP Fortran logical names recognized at compile-time and run-time.

• Appendix E identifies the HP Fortran include files that define symbols for use in HP Fortran programs.

• Appendix F contains examples of the use of a variety of system services.

Note

If you are reading the printed version of this manual, be aware that the version at the HP Fortran Web site and the version on the Documentation CD-ROM from HP may contain updated and/or corrected information.

Reader’s Comments

HP welcomes your comments on this manual. You can send comments by email to: [email protected]

HP Fortran Web Page

The HP Fortran Web page is located at: http://www.hp.com/software/fortran

This Web site contains information about software patch kits, example programs, and additional product information. It also contains Web versions of this and other HP Fortran manuals.

Conventions

The following product names may appear in this manual:

• HP OpenVMS Industry Standard 64 for Integrity Servers

• OpenVMS I64

• I64

All three names—the longer form and the two abbreviated forms—refer to the version of the OpenVMS operating system that runs on the Intel® Itanium® architecture.

The following conventions might be used in this manual:

Ctrl/x

PF1 x

A sequence such as Ctrl/x indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button.

A sequence such as PF1 x indicates that you must first press and release the key labeled PF1 and then press and release another key or a pointing device button.

xxvii

xxviii

Return

. . .

( )

[ ]

{ } bold type

In examples, a key name enclosed in a box indicates that you press a key on the keyboard. (In text, a key name is not enclosed in a box.)

In the HTML version of this document, this convention appears as brackets, rather than a box.

A horizontal ellipsis in examples indicates one of the following possibilities:

• Additional optional arguments in a statement have been omitted.

• The preceding item or items can be repeated one or more times.

• Additional parameters, values, or other information can be entered.

A vertical ellipsis indicates the omission of items from a code example or command format; the items are omitted because they are not important to the topic being discussed.

In command format descriptions, parentheses indicate that you must enclose choices in parentheses if you specify more than one.

In command format descriptions, brackets indicate optional choices. You can choose one or more items or no items.

Do not type the brackets on the command line. However, you must include the brackets in the syntax for OpenVMS directory specifications and for a substring specification in an assignment statement.

In command format descriptions, vertical bars separate choices within brackets or braces. Within brackets, the choices are optional; within braces, at least one choice is required. Do not type the vertical bars on the command line.

In command format descriptions, braces indicate required choices; you must choose at least one of the items listed. Do not type the braces on the command line.

Bold type represents the introduction of a new term. It also represents the name of an argument, an attribute, or a reason.

italic type

UPPERCASE TYPE numbers real complex logical integer

Fortran

Fortran 90

Fortran 95

HP Fortran

Italic type indicates important information, complete titles of manuals, or variables. Variables include information that varies in system output (Internal error number), in command lines (/PRODUCER=name), and in command parameters in text (where dd represents the predefined code for the device type).

Uppercase type indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.

A hyphen at the end of a command format description, command line, or code line indicates that the command or statement continues on the following line.

All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes—binary, octal, or hexadecimal—are explicitly indicated.

This term refers to all floating-point intrinsic data types as a group.

This term refers to all complex floating-point intrinsic data types as a group.

This term refers to logical intrinsic data types as a group.

This term refers to integer intrinsic data types as a group.

This term refers to language information that is common to ANSI FORTRAN-77, ANSI/ISO Fortran 90, ANSI/ISO

Fortran 95, and HP Fortran 90.

This term refers to language information that is common to

ANSI/ISO Fortran 90 and HP Fortran. For example, a new language feature introduced in the Fortran 90 standard.

This term refers to language information that is common to ISO Fortran 95 and HP Fortran. For example, a new language feature introduced in the Fortran 95 standard.

Unless otherwise specified, this term (formerly Compaq

Fortran) refers to language information that is common to the Fortran 90 and 95 standards, and any HP Fortran extensions, running on the OpenVMS operating system.

Since the Fortran 90 standard is a superset of the

FORTRAN-77 standard, HP Fortran also supports the

FORTRAN-77 standard. HP Fortran supports all of the deleted features of the Fortran 95 standard.

xxix

Getting Started

This chapter describes:

• Section 1.1, Fortran Standards Overview

• Section 1.2, HP Fortran Programming Environment

• Section 1.3, Commands to Create and Run an Executable Program

• Section 1.4, Creating and Running a Program Using a Module and

Separate Function

• Section 1.5, Program Development Stages and Tools

1.1 Fortran Standards Overview

HP Fortran for OpenVMS (formerly Compaq Fortran for OpenVMS) conforms to the:

• American National Standard Fortran 90 (ANSI X3.198-1992), which is the same as the International Standards Organization standard (ISO/IEC

1539:1991 (E))

• Fortran 95 standard (ISO/IEC 1539:1998 (E))

HP Fortran supports all of the deleted features of the Fortran 95 standard.

HP Fortran also includes support for programs that conform to the previous

Fortran standards (ANSI X3.9-1978 and ANSI X3.0-1966), the International

Standards Organization standard ISO 1539-1980 ( E ), the Federal Information

Processing Institute standard FIPS 69-1, and the Military Standard 1753

Language Specification.

The ANSI committee X3J3 is currently answering questions of interpretation of Fortran 90 ands 95 language features. Any answers given by the ANSI committee that are related to features implemented in HP Fortran may result in changes in future releases of the HP Fortran compiler, even if the changes produce incompatibilities with earlier releases of HP Fortran.

Getting Started 1–1

HP Fortran provides a number of extensions to the Fortran 90 and 95 standards. HP Fortran extensions to the latest Fortran standard are generally provided for compatibility with Compaq Fortran 77 extensions to the ANSI

FORTRAN-77 standard.

When creating new programs that need to be standards-conforming for portability reasons, you should avoid or minimize the use of extensions to the latest Fortran standard. Extensions to the appropriate Fortran standard are identified visually in the HP Fortran for OpenVMS Language Reference

Manual, which defines the HP Fortran language.

1.2 HP Fortran Programming Environment

The following aspects of Fortran 90/95 are relevant to the compilation environment and should be considered before extensive coding begins:

• To install HP Fortran on your system, see the HP Fortran Installation

Guide for OpenVMS I64 Systems or the HP Fortran Installation Guide for

OpenVMS Alpha Systems.

• Once HP Fortran is installed, you can:

Use the FORTRAN command to compile source files. Use the LINK command to link object files into executable programs.

Use the online HELP FORTRAN command and this manual to provide information about the FORTRAN command.

• Make sure you have adequate process memory space, especially if your programs use large arrays as data. Your system manager (or designated privileged user) may be able to overcome this problem by checking and possibly increasing the following:

Your process memory (working set)

Your system manager can use the Authorize Utility to adjust your process working set quotas, page file quota, and limits.

System-wide virtual memory limits

Your system manager can use SYSGEN to change parameters (such as

WSMAX and VIRTUALPAGECNT), which take effect after the system is rebooted.

Page file space on your system

Your system manager can use SYSGEN or AUTOGEN to increase page file sizes or create new page files. Your system manager needs to INSTALL any new page files available to the system by modifying system startup command procedures and rebooting the system.

1–2 Getting Started

System hardware resources, such as physical memory and disk space

You can check the current memory limits using the SHOW WORKING_

SET command. To view peak memory use after compiling or running a program, use the SHOW PROCESS/ACCOUNTING command. Your system manager can use these commands (or SHOW PROCESS/CONTINUOUS) for a currently running process and the system-side MONITOR command.

For example, the following DCL (shell) commands check the current limits and show the current use of some of these limits:

$ SHOW WORKING_SET

...

$ SHOW PROCESS/ACCOUNTING

...

• Make sure you have an adequate process open file limit, especially if your programs use a large number of module files.

During compilation, your application may attempt to use more module files than your open file limit allows. In this case, the HP Fortran compiler will close a previously opened module file before it opens another to stay within your open file limit. This results in slower compilation time. Increasing the open file limit may improve compilation time in such cases.

You can view the per-process limit on the number of open files (Open file quota or FILLM) by using the SHOW PROCESS/QUOTA command:

$ SHOW PROCESS/QUOTA

...

Your system manager needs to determine the maximum per-process limit for your system by checking the value of the CHANNELCNT SYSGEN parameter and (if necessary) increasing its value.

• You can define logical names to specify libraries and directories.

You can define the FORT$LIBRARY logical name to specify a user-defined text library that contains source text library modules referenced by

INCLUDE statements. The compiler searches first for libraries specified on the command line and also in the system-supplied default library (see

Section 2.4).

For more information on using FORT$LIBRARY, see Section 2.2.4.

You can define the FORT$INCLUDE logical name to specify a directory to be searched for the following files:

Module files specified by a USE statement (module name is used as a file name)

Getting Started 1–3

Source files specified by an INCLUDE statement, where a file name is specified without a directory name

Text library files specified by an INCLUDE statement, where a file name is specified without a library name

For more information on the FORT$INCLUDE logical name, see

Section 2.2.3 and Section 2.2.4.

If you need to set logical names frequently, consider setting them in your

LOGIN.COM file, or ask your system manager to set them as system-wide logical names in a system startup command procedure.

Several other logical names can similarly be used during program execution

(see Appendix D).

• Your HP Fortran source files can be in free or fixed form. You can indicate the source form used in your source files by using certain file types or a command-line qualifier:

For files using fixed form, specify a file type of FOR or F.

For files using free form, specify a file type of F90.

You can also specify the /SOURCE_FORM qualifier on the FORTRAN command line to specify the source form for all files on that command line.

For example, if you specify a file as PROJ_BL1.F90 on a FORTRAN command line (and omit the /SOURCE_FORM=FIXED qualifier), the

FORTRAN command assumes the file PROJ_BL1.F90 contains free-form source code.

A special type of fixed source form is tab form (an HP extension described in the HP Fortran for OpenVMS Language Reference Manual).

• Each source file to be compiled must contain at least one program unit

(main program, subroutine, function, module, block data). Consider the following aspects of program development:

Modularity and efficiency

For a large application, using a set of relatively small source files promotes incremental application development.

When application run-time performance is important, compile related source files together (or the entire application). When compiling multiple source files, separate file names with plus signs ( + ) to concatenate source files and create a single object file. This allows certain interprocedure optimizations to minimize run-time execution time (unless you specify certain qualifiers).

1–4 Getting Started

Code reuse

Modules, external subprograms, and included files allow reuse of common code. Code used in multiple places in a program should be placed in a module, external subprogram (function or subroutine), or included file.

When using modules and external subprograms, there is one copy of the code for a program. When using INCLUDE statements, the code in the specified source file is repeated once for each INCLUDE statement.

In most cases, using modules or external subprograms makes programs easier to maintain and minimizes program size.

For More Information:

• On modules, see Section 2.2.3.

• On include files, see Section 2.2.4.

• On HP Fortran source forms, see the HP Fortran for OpenVMS Language

Reference Manual.

• On recognized file types, see Section 2.2.1.

• On the types of subprograms and using an explicit interface to a subprogram, see Chapter 10.

• On performance considerations, including compiling source programs for optimal run-time performance, see Chapter 5.

• On logical names, see the OpenVMS User’s Manual.

1.3 Commands to Create and Run an Executable Program

Example 1–1 shows a short Fortran 90/95 main program using free-form source.

Example 1–1 Sample Main Program

! File hello.f90

PROGRAM HELLO_TEST

PRINT *, ’hello world’

PRINT *, ’ ’

END PROGRAM HELLO_TEST

Getting Started 1–5

To create and revise your source files, use a text editor, such as the Extensible

Versatile Editor (EVE). For instance, to use EVE to edit the file HELLO.F90, enter:

$ EDIT HELLO.F90

The following FORTRAN command compiles the program named HELLO.F90.

The LINK command links the compiled object file into an executable program file named HELLO.EXE:

$ FORTRAN HELLO.F90

$ LINK HELLO

In this example, because all external routines used by this program reside in standard OpenVMS libraries searched by the LINK command, additional libraries or object files are not specified on the LINK command line.

To run the program, enter the RUN command and the program name:

$ RUN HELLO

If the executable program is not in your current default directory, specify the directory before the file name. Similarly, if the executable program resides on a different device than your current default device, specify the device name and directory name before the file name.

For More Information:

• On the OpenVMS programming environment, see the operating system documents listed in the Preface of this manual.

• On specifying files on an OpenVMS system, see the OpenVMS User’s

Manual.

1.4 Creating and Running a Program Using a Module and

Separate Function

Example 1–2 shows a sample HP Fortran main program using free-form source that uses a module and an external subprogram.

The function CALC_AVERAGE is contained in a separately created file and depends on the module ARRAY_CALCULATOR for its interface block.

1–6 Getting Started

Example 1–2 Sample Main Program That Uses a Module and Separate

Function

! File: main.f90

! This program calculates the average of five numbers

PROGRAM MAIN

USE ARRAY_CALCULATOR

REAL, DIMENSION(5) :: A = 0

REAL :: AVERAGE

PRINT *, ’Type five numbers: ’

READ (*,’(BN,F10.3)’) A

AVERAGE = CALC_AVERAGE(A) "

PRINT *, ’Average of the five numbers is: ’, AVERAGE

END PROGRAM MAIN

The USE statement accesses the module ARRAY_CALCULATOR. This module contains the function declaration for CALC_AVERAGE (use association).

" The 5-element array is passed to the function CALC_AVERAGE, which returns the value to the variable AVERAGE for printing.

Example 1–3 shows the module referenced by the main program. This example program shows more Fortran 90 features, including an interface block and an assumed-shape array.

Example 1–3 Sample Module

! File: array_calc.f90.

! Module containing various calculations on arrays.

MODULE ARRAY_CALCULATOR

INTERFACE

FUNCTION CALC_AVERAGE(D)

REAL :: CALC_AVERAGE

REAL, INTENT(IN) :: D(:)

END FUNCTION CALC_AVERAGE

END INTERFACE

! Other subprogram interfaces...

END MODULE ARRAY_CALCULATOR

Getting Started 1–7

Example 1–4 shows the function declaration CALC_AVERAGE referenced by the main program.

Example 1–4 Sample Separate Function Declaration

! File: calc_aver.f90.

! External function returning average of array.

FUNCTION CALC_AVERAGE(D)

REAL :: CALC_AVERAGE

REAL, INTENT(IN) :: D(:)

CALC_AVERAGE = SUM(D) / UBOUND(D, DIM = 1)

END FUNCTION CALC_AVERAGE

1.4.1 Commands to Create the Executable Program

During the early stages of program development, the three files might be compiled separately and then linked together, using the following commands:

$ FORTRAN ARRAY_CALC.F90

$ FORTRAN CALC_AVER.F90

$ FORTRAN MAIN.F90

$ LINK/EXECUTABLE=CALC.EXE MAIN, ARRAY_CALC, CALC_AVER

In this sequence of FORTRAN commands:

• Each of the FORTRAN commands creates one object file (OBJ file type).

• The first FORTRAN command creates the object file ARRAY_CALC.OBJ

and the module file ARRAY_CALCULATOR.F90$MOD. The name in the

MODULE statement (ARRAY_CALCULATOR) in Example 1–3 determines the file name of the module file. The FORTRAN command creates module files in the process default device and directory with a F90$MOD file type.

• The second FORTRAN command creates the file CALC_AVER.OBJ

(Example 1–4).

• The third FORTRAN command creates the file MAIN.OBJ (Example 1–2) and uses the module file ARRAY_CALCULATOR.F90$MOD.

• The LINK command links all object files (OBJ file type) into the executable program named CALC.EXE.

To allow more optimizations to occur (such as the inline expansion of called subprograms), compile the entire set of three source files together using a single FORTRAN command:

$ FORTRAN/OBJECT=CALC.OBJ ARRAY_CALC.F90 + CALC_AVER.F90 + MAIN.F90

1–8 Getting Started

The order in which the file names are specified is significant. This FORTRAN command:

• Compiles the file ARRAY_CALC.F90, which contains the module definition

(shown in Example 1–3), and creates its object file and the file ARRAY_

CALCULATOR.F90$MOD in the process default device and directory.

• Compiles the file CALC_AVER.F90, which contains the external function

CALC_AVERAGE (shown in Example 1–4).

• Compiles the file MAIN.F90 (shown in Example 1–2). The USE statement references the module file ARRAY_CALCULATOR.F90$MOD.

• Creates a single object file named CALC.OBJ.

When you omit the file type on the FORTRAN command line, the FORTRAN command searches for a file with the F90 file type before a file with the FOR or F file type, so you can enter the previous command (without file types) as follows:

$ FORTRAN/OBJECT=CALC.OBJ ARRAY_CALC + CALC_AVER + MAIN

Use a LINK command to link the single object file into an executable program:

$ LINK CALC

When you omit the file type on the LINK command line, the Linker searches for a file with a file type of OBJ. Unless you will specify a library on the LINK command line, you can omit the OBJ file type.

1.4.2 Running the Sample Program

If the current default directory contains the file named CALC you can run the program by entering the RUN command followed by its name:

$ RUN CALC

When you omit the file type on the RUN command line, the image activator searches for a file with a file type of EXE (you can omit the EXE file type).

When running the sample program, the PRINT and READ statements in the main program result in the following dialogue between user and program:

Type five numbers:

55.5

4.5

3.9

9.0

5.6

Average of the five numbers is: 15.70000

Getting Started 1–9

1.4.3 Debugging the Sample Program

To debug a program using the OpenVMS Debugger, compile and link with the

/DEBUG qualifier to request additional symbol table information for source line debugging in the object and executable program files. The following FORTRAN command names the object file CALC_DEBUG.OBJ. The LINK command then creates the program file CALC_DEBUG.EXE with full debugging information:

$ FORTRAN/DEBUG/OBJECT=CALC_DEBUG.OBJ/NOOPTIMIZE ARRAY_CALC + CALC_AVER + MAIN

$ LINK/DEBUG CALC_DEBUG

The OpenVMS debugger has a character-cell interface and a windowing interface (available with the DECwindows Motif product). To debug an executable program named CALC_DEBUG.EXE, enter the following command:

$ RUN CALC_DEBUG

For more information on running the program within the debugger and the windowing interface, see Chapter 4.

1.5 Program Development Stages and Tools

This manual primarily addresses the program development activities associated with implementation and testing phases. For information about topics usually considered during application design, specification, and maintenance, see your operating system documentation or appropriate commercially published documentation.

HP Fortran provides the standard features of a compiler and the OpenVMS operating system provides a linker.

Use a LINK command to link the object file into an executable program.

Table 1–1 describes some of the software tools you can use when developing

(implementing) and testing a program:

1–10 Getting Started

Table 1–1 Tools for Program Development and Testing

Task or Activity Tool and Description

Manage source files

Create and modify source files

Analyze source code

Build program (compile and link)

Use the Code Management System (CMS).

Use a text editor, such as the EDIT command to use the

EVE editor. You can also use the optional Language-

Sensitive Editor (LSE). For more information using

OpenVMS text editors, see the OpenVMS User’s Manual.

Use DCL commands such as SEARCH and DIFFERENCES.

You can use the FORTRAN and LINK commands to create small programs, perhaps using command procedures, or use the Module Management System (MMS) to build your application in an automated fashion.

For more information on the FORTRAN and LINK commands, see Chapter 2 and Chapter 3 respectively.

Debug and Test program Use the OpenVMS Debugger to debug your program or run it for general testing. For more information on the

OpenVMS Debugger, see Chapter 4 in this manual.

Analyze performance To perform program timings and profiling of code, use the

LIB$xxxx_TIMER routines, a command procedure, or the

Performance Coverage Analyzer (PCA).

For more information on timing and profiling HP Fortran code, see Chapter 5.

To perform other program development functions at various stages of program development, use the following DCL commands:

• Use the LIBRARIAN command to create an object or text library, add or delete library modules in a library, list the library modules in a library, and perform other functions. For more information, enter HELP LIBRARIAN or see the VMS Librarian Utility Manual.

• Use the LINK/NODEBUG command to remove symbolic and other debugging information to minimize image size. For more information, see

Chapter 3.

• The LINK/MAP command creates a link map, which shows information about the program sections, symbols, image section, and other information.

• The ANALYZE/OBJECT command shows which compiler compiled the object file and the version number used. It also does a partial error analysis and shows other information.

Getting Started 1–11

• The ANALYZE/IMAGE command checks information about an executable program file. It also shows the date it was linked and the version of the operating system used to link it.

For More Information:

• On the OpenVMS programming environment, see the Preface of this manual.

• On DCL commands, use DCL HELP or see the HP OpenVMS DCL

Dictionary.

1–12 Getting Started

Compiling HP Fortran Programs

This chapter describes:

• Section 2.1, Functions of the Compiler

• Section 2.2, FORTRAN Command Syntax, Use, and Examples

• Section 2.3, FORTRAN Command Qualifiers

• Section 2.4, Creating and Maintaining Text Libraries

• Section 2.5, Using CDD/Repository

• Section 2.6, Compiler Limits, Diagnostic Messages, and Error Conditions

• Section 2.7, Compiler Output Listing Format

2.1 Functions of the Compiler

The primary functions of the HP Fortran compiler are to:

• Verify the HP Fortran source statements and to issue messages if the source statements contain any errors

• Venerate machine language instructions from the source statements of the

HP Fortran program

• Group these instructions into an object module for the OpenVMS Linker

When the compiler creates an object file, it provides the linker with the following information:

• The program unit name. The program unit name is the name specified in the PROGRAM, MODULE, SUBROUTINE, FUNCTION, or BLOCK DATA statement in the source program. If a program unit does not contain any of these statements, the source file name is used with $MAIN (or $DATA, for block data subprograms) appended.

Compiling HP Fortran Programs 2–1

• A list of all entry points and common block names that are declared in the program unit. The linker uses this information when it binds two or more program units together and must resolve references to the same names in the program units.

• Traceback information, used by the system default condition handler when an error occurs that is not handled by the program itself. The traceback information permits the default handler to display a list of the active program units in the order of activation, which aids program debugging.

• A symbol table, if specifically requested (/DEBUG qualifier). A symbol table lists the names of all external and internal variables within a object module, with definitions of their locations. The table is of primary use in program debugging.

For More Information:

On the OpenVMS Linker, see Chapter 3.

2.2 FORTRAN Command Syntax, Use, and Examples

The FORTRAN command initiates compilation of a source program.

The command has the following form:

FORTRAN [/qualifiers] file-spec-list[/qualifiers]

/qualifiers

Indicates either special actions to be performed by the compiler or special properties of input or output files.

file-spec-list

Specifies the source files containing the program units to be compiled. You can specify more than one source file:

• If source file specifications are separated by commas ( , ), the programs are compiled separately.

• If source file specifications are separated by plus signs ( + ), the files are concatenated and compiled as one program.

When compiling source files with the default optimization (or additional optimizations), concatenating source files allows full interprocedure optimizations to occur.

2–2 Compiling HP Fortran Programs

In interactive mode, you can also enter the file specification on a separate line by entering the command FORTRAN, followed by a carriage return. The system responds with the following prompt:

_File:

Enter the file specification immediately after the prompt and then press

Return.

2.2.1 Specifying Input Files and Source Form

If you omit the file type on the FORTRAN command line, the compiler searches first for a file with a file type of F90. If a file with a file type of F90 is not found, it then searches for file with a file type of FOR and then F.

For example, the following FORTRAN command line shows how file type searching occurs:

$ FORTRAN PROJ_ABC

This FORTRAN command searches for the following files:

It searches first for PROJ_ABC.F90.

If PROJ_ABC.F90 does not exist, it then searches for PROJ_ABC.FOR.

If PROJ_ABC.F90 and PROJ_ABC.FOR do not exist, it then searches for

PROJ_ABC.F.

Indicate the Fortran 90 source form used in your source files by using certain file types or a command-line qualifier:

• For files using fixed form, use a file type of FOR or F.

• For files using free form, use a file type of F90.

• You can also specify the /SOURCE_FORM qualifier on the FORTRAN command line to specify the source form (FIXED or FREE) for:

All files on that command line (when used as a command qualifier)

Individual source files in a comma-separated list of files (when used as a positional qualifier)

For example, if you specify a file as PROJ_BL1.F90 on an FORTRAN command line (and omit the /SOURCE_FORM=FIXED qualifier), the FORTRAN command assumes the file PROJ_BL1.F90 contains free-form source code.

Compiling HP Fortran Programs 2–3

2.2.2 Specifying Multiple Input Files

When you specify a list of input files on the FORTRAN command line, you can use abbreviated file specifications for those files that share common device names, directory names, or file names.

The system applies temporary file specification defaults to those files with incomplete specifications. The defaults applied to an incomplete file specification are based on the previous device name, directory name, or file name encountered in the list.

The following FORTRAN command line shows how temporary defaults are applied to a list of file specifications:

$ FORTRAN USR1:[ADAMS]T1,T2,[JACKSON]SUMMARY,USR3:[FINAL]

The preceding FORTRAN command compiles the following files:

USR1:[ADAMS]T1.F90 (or .FOR or .F)

USR1:[ADAMS]T2.F90 (or .FOR

or .F)

USR1:[JACKSON]SUMMARY.F90 (or .FOR or .F)

USR3:[FINAL]SUMMARY.F90 (or .FOR or .F)

To override a temporary default with your current default directory, specify the directory as a null value. For example:

$ FORTRAN [OMEGA]T1, []T2

The empty brackets indicate that the compiler is to use your current default directory to locate T2.

FORTRAN qualifiers typically apply to the entire FORTRAN command line. One exception is the /LIBRARY qualifier, which specifies that the file specification it follows is a text library (positional qualifier). The /LIBRARY qualifier is discussed in Section 2.3.27.

You can specify multiple files on the FORTRAN command line. You can separate the multiple source file specifications with:

• Plus signs ( + )

All files separated by plus signs are concatenated and compiled as one program into a single object file.

A positional qualifier after one of the file specifications applies to all files concatenated by plus signs ( + ). One exception is the /LIBRARY qualifier

(used only as a positional qualifier).

Concatenating source files allows full interprocedure optimizations to occur across the multiple source files (unless you specify certain command qualifiers, such as /NOOPTIMIZE and /SEPARATE_COMPILATION).

2–4 Compiling HP Fortran Programs

• Commas ( , )

When separated by commas, the files are compiled separately into multiple object files.

A positional qualifier applies only to the file specification it immediately follows.

Separate compilation by using comma-separated files (or by using multiple

FORTRAN commands) prevents certain interprocedure optimizations.

If you use multiple FORTRAN commands to compile multiple HP Fortran source files that are linked together into the same program, you must be consistent when specifying any qualifiers that affect run-time results. For example, suppose you do the following:

Specify /FLOAT=IEEE_FLOAT on one command line

Specify /FLOAT=G_FLOAT on another command line

Link the resulting object files together into a program

When you run the program, the values returned for floating-point numbers in a COMMON block will be unpredictable. For qualifiers related only to compile-time behavior (such as /LIST and /SHOW), this restriction does not apply.

2.2.3 Creating and Using Module Files

HP Fortran creates module files for each module declaration and automatically searches for a module file referenced by a USE statement

(introduced in Fortran 90). A module file contains the equivalent of the module source declaration in a post-compiled, binary form.

2.2.3.1 Creating Module Files

When you compile an HP Fortran source file that contains module declarations,

HP Fortran creates a separate file for each module declaration in the current process default device and directory. The name declared in a MODULE statement becomes the base prefix of the file name and is followed by the

F90$MOD file type.

For example, consider a file that contains the following statement:

MODULE MOD1

The compiler creates a post-compiled module file MOD1.F90$MOD in the current directory. An object file is also created for the module.

Compiling HP Fortran Programs 2–5

Compiling a source file that contains multiple module declarations will create multiple module files, but only a single object file. If you need a separate object file for each module, place only one module declaration in each file.

If a source file does not contain the main program and you need to create module files only, specify the /NOOBJECT qualifier to prevent object file creation.

To specify a directory other than the current directory for the module file(s) to be placed, use the /MODULE qualifier (see Section 2.3.31).

Note that an object file is not needed if there are only INTERFACE or constant

(PARAMETER) declarations; however, it is needed for all other types of declarations including variables.

2.2.3.2 Using Module Files

Once you create a module file, you can copy module files into an appropriate shared or private directory. You reference a module file by specifying the module name in a USE statement (use association). For example:

USE MOD1

By default, the compiler searches for a module file named MOD1.F90$MOD in the current directory.

When selecting a directory location for a set of module files, consider how your application gets built, including:

• Whether the module files need to be available privately, such as for testing purposes (not shared).

• Whether you want the module files to be available to other users on your project or available system-wide (shared).

• Whether test builds and final production builds will use the same or a different directory for module files.

HP Fortran allows you to use multiple methods to specify which directories are searched for module files:

• You can specify one or more additional directories for the compiler to search by using the /INCLUDE=directory qualifier.

• You can specify one or more additional directories for the compiler to search by defining the logical name FORT$INCLUDE. To search multiple additional directories with FORT$INCLUDE, define it as a search list.

Like other logical names, FORT$INCLUDE can be for a system-wide location (such as a group or system logical name) or a private or project location (such as a process, job, or group logical name).

2–6 Compiling HP Fortran Programs

• You can prevent the compiler from searching in the directory specified by the FORT$INCLUDE logical name by using the /NOINCLUDE qualifier.

To locate modules referenced by USE statements, the compiler searches directories in the following order:

The current process device and directory

Each directory specified by the /INCLUDE qualifier

The directory specified by the logical name FORT$INCLUDE (unless

/NOINCLUDE was specified).

You cannot specify a module (.F90$MOD) file directly on the FORTRAN command line.

Suppose you need to compile a main program PROJ_M.F90 that contains one or more USE statements. To request that the compiler look for module files in the additional directories DISKA:[PROJ_MODULE.F90] and then

DISKB:[COMMON.FORT] (after looking in the current directory), enter the following command line:

$ FORTRAN PROJ_M.F90 /INCLUDE=(DISKA:[PROJ_MODULE.F90],DISKB:[COMMON.FORT])

If you specify multiple directories with the /INCLUDE qualifier, the order of the directories in the /INCLUDE qualifier determines the directory search order.

Module nesting depth is unlimited. If you will use many modules in a program, check the process and system file limits (see Section 1.2).

For More Information:

• On the FORTRAN /INCLUDE qualifier, see Section 2.3.25.

• On an example program that uses a module, see Section 1.4.

2.2.4 Using Include Files and Include Text Library Modules

You can create include files with a text editor. The include files can be placed in a text library. If needed, you can copy include files or include text library to a shared or private directory.

When selecting a directory location for a set of include files or text libraries, consider how your application is to be built, including:

• Whether the include files or text library needs to be available privately, such as for testing purposes (not shared).

• Whether you want the files to be available to other users on your project or available system-wide (shared).

Compiling HP Fortran Programs 2–7

• Whether test builds and final production builds will use the same or a different directory.

• Instead of placing include files in a directory, consider placing them in a text library. The text library can contain multiple include files in a single library file and is maintained by using the OpenVMS LIBRARY command.

2.2.4.1 Using Include Files and INCLUDE Statement Forms

Include files have a file type like other HP Fortran source files (F90, FOR, or

F). Use an INCLUDE statement to request that the specified file containing source lines be included in place of the INCLUDE statement.

To include a file, the INCLUDE statement has the following form:

INCLUDE ’name’

INCLUDE ’name.typ’

You can specify /LIST or /NOLIST after the file name. You can also specify the /SHOW=INCLUDE or /SHOW=NOINCLUDE qualifier to control whether source lines from included files or library modules appear in the listing file (see

Section 2.3.43).

You can also include a file with a directory (and optionally the device name) specified with the following form:

INCLUDE ’[directory]name’

INCLUDE ’[directory]name.typ’

If a directory is specified, only the specified directory is searched. The remainder of this section addresses an INCLUDE statement where the directory has not been specified.

HP Fortran allows you to use multiple methods to specify which directories are searched for include files:

• You can request that the HP Fortran compiler search either in the current process default directory or in the directory where the source file resides that references the include file. To do this, specify the

/ASSUME=NOSOURCE_INCLUDE (process default directory) or

/ASSUME=SOURCE_INCLUDE qualifier (source file directory). The default is /ASSUME=NOSOURCE_INCLUDE.

• You can specify one or more additional directories for the compiler to search by using the /INCLUDE=directory qualifier.

2–8 Compiling HP Fortran Programs

Like other logical names, FORT$INCLUDE can be for:

A system-wide location (such as a group or system logical name)

A private or project location (such as a process, job, or group logical name)

• You can prevent the compiler from searching in the directory specified by the FORT$INCLUDE logical name by using the /NOINCLUDE qualifier.

To locate include files specified in INCLUDE statements (without a device or directory name), the HP Fortran compiler searches directories in the following order:

The current process default directory or the directory that the source file resides in (depending on whether /ASSUME=SOURCE_INCLUDE was specified)

Each directory specified by the /INCLUDE qualifier

The directory specified by the logical name FORT$INCLUDE (unless

/NOINCLUDE was specified).

2.2.4.2 INCLUDE Statement Forms for Including Text Library Modules

HP Fortran provides certain include library modules in the text library

FORSYSDEF.TLB. Users can create a text library and populate it with include library modules (see Section 2.4). Within a library, text library modules are identified by a library module name (no file type).

To include a text library module, the INCLUDE statement specifies the name of the library module within parentheses, as follows:

INCLUDE ’(name)’

You can specify the library name before the library module name in the

INCLUDE statement. For example:

INCLUDE ’MYLIB(PROJINC)’

Use one of the following methods to access a source library module in a text library:

• Specify only the name of the library module in an INCLUDE statement in your HP Fortran source program. You use FORTRAN command qualifiers and logical names to control the directory search for the library.

Compiling HP Fortran Programs 2–9

• Specify the name of both the library and library module in an INCLUDE statement in your HP Fortran source program.

• When the INCLUDE statement does not specify the library name, you can define a default library by using the logical name FORT$LIBRARY.

• When the INCLUDE statement does not specify the library name, you can specify the name of the library using the /LIBRARY qualifier on the

FORTRAN command line that you use to compile the source program.

2.2.4.3 Using Include Text Library Modules for a Specified Library Name

When the library is named in the INCLUDE statement, the FORTRAN command searches various directories for the named library, similar to the search for an include file.

HP Fortran allows you to use multiple methods to specify which directories are searched for named text libraries:

• You can request that the HP Fortran compiler search either in the current process default directory or in the directory where the source file resides that references the text library. To do this, specify the

/ASSUME=NOSOURCE_INCLUDE (process default directory) or

/ASSUME=SOURCE_INCLUDE qualifier (source file directory).

• You can specify one or more additional directories for the compiler to search by using the /INCLUDE=directory qualifier.

• You can specify one or more additional directories for the compile to search by defining the logical name FORT$INCLUDE. To search multiple additional directories with FORT$INCLUDE, define it as a search list.

Like other logical names, FORT$INCLUDE can be for:

A system-wide location (such as a group or system logical name)

A private or project location (such as a process, job, or group logical name)

• You can prevent the compiler from searching in the directory specified by the FORT$INCLUDE logical name by using the /NOINCLUDE qualifier.

The HP Fortran compiler searches directories in the following order:

The current process default directory or the directory that the source file resides in (depending on whether /ASSUME=SOURCE_INCLUDE was specified)

Each directory specified by the /INCLUDE qualifier

2–10 Compiling HP Fortran Programs

The directory specified by the logical name FORT$INCLUDE (unless

/NOINCLUDE was specified).

You can specify /LIST or /NOLIST after the library module name. For example:

INCLUDE ’PROJLIB(MYINC)/LIST’

You can also specify the /SHOW=INCLUDE or /SHOW=NOINCLUDE qualifier to control whether source lines from included files or library modules appear in the listing file (see Section 2.3.43).

For More Information:

• On the /ASSUME=[NO]SOURCE_INCLUDE qualifier, see Section 2.3.7.

• On the /INCLUDE qualifier, see Section 2.3.25.

• On creating and using text libraries, see Section 2.4.

2.2.4.4 Using Include Text Library Modules for an Unspecified Library Name

When the INCLUDE statement does not specify the library, you can specify additional text libraries to be searched on the FORTRAN command line or by defining a logical name. The order in which the compiler searches for a library file follows:

• Specify the library name on the FORTRAN command line, appended with the /LIBRARY positional qualifier. The /LIBRARY qualifier identifies a file specification as a text library.

Concatenate the name of the text library to the name of the source file and append the /LIBRARY qualifier to the text library name (use the plus sign

( + )) separator. For example:

$ FORTRAN APPLIC+DATAB/LIBRARY

Whenever an INCLUDE statement occurs in APPLIC.FOR, the compiler searches the library DATAB.TLB for the source text module identified in the INCLUDE statement and incorporates it into the compilation.

When more than one library is specified on a FORTRAN command line, the HP Fortran compiler searches the libraries each time it processes an

INCLUDE statement that specifies a text module name. The compiler searches the libraries in the order specified on the command line. For example:

$ FORTRAN APPLIC+DATAB/LIBRARY+NAMES/LIBRARY+GLOBALSYMS/LIBRARY

Compiling HP Fortran Programs 2–11

When the HP Fortran compiler processes an INCLUDE statement in the source file APPLIC.FOR, it searches the libraries DATAB.TLB,

NAMES.TLB, and GLOBALSYMS.TLB, in that order, for source text modules identified in the INCLUDE statement.

When the FORTRAN command requests multiple compilations, a library must be specified for each compilation in which it is needed. For example:

$ FORTRAN METRIC+DATAB/LIBRARY, APPLIC+DATAB/LIBRARY

In this example, HP Fortran compiles METRIC.FOR and APPLIC.FOR

separately and uses the library DATAB.TLB for each compilation.

If the text library is not in the current process default directory, specify the device and/or directory. For example:

$ FORTRAN PROJ_MAIN+$DISK2:[PROJ.LIBS]COMMON_LIB/LIBRARY

Instead of specifying the device and directory name, you can use the /ASSUME=SOURCE_INCLUDE and /INCLUDE qualifiers and

FORT$INCLUDE logical name to control the directory search.

• After the compiler has searched all libraries specified on the command line, it searches the default user library (if any) specified by the logical name FORT$LIBRARY. When you want to define one of your private text libraries as a default library for the HP Fortran compiler to search, consider using the FORT$LIBRARY logical name.

For example, define a default library using the logical name

FORT$LIBRARY before compilation, as in the following example of the

DCL command DEFINE:

$ DEFINE FORT$LIBRARY $DISK2:[LIB]DATAB

$ FORTRAN PROJ_MAIN

While this assignment is in effect, the compiler automatically searches the library $DISK2:[LIB]DATAB.TLB for any include library modules that it cannot locate in libraries explicitly specified, if any, on the FORTRAN command line.

You can define the logical name FORT$LIBRARY in any logical name table defined in the logical name table search list LMN$FILE_DEV. For example:

$ DEFINE /GROUP FORT$LIBRARY $DISK2:[PROJ.LIBS]APPLIB.TLB

$ FORTRAN PROJ_MAIN

2–12 Compiling HP Fortran Programs

If the name is defined in more than one table, the HP Fortran compiler uses the equivalence for the first match it finds in the normal order of search—first the process table, then intermediate tables (job, group, and so on), and finally the system table. If the same logical name is defined in both the process and system logical name tables, the process logical name table assignment overrides the system logical name table assignment.

If FORT$LIBRARY is defined as a search list, the compiler opens the first text library specified in the list. If the include library module is not found in that text library, the search is terminated and an error message is issued.

The logical name FORT$LIBRARY is recognized by both Compaq Fortran

77 and HP Fortran.

• When the HP Fortran compiler cannot find the include library modules in libraries specified on the FORTRAN command line or in the default library defined by FORT$LIBRARY, it then searches the standard text library supplied by HP Fortran. This library resides in SYS$LIBRARY with a file name of FORSYSDEF.TLB and simplifies calling OpenVMS system services.

SYS$LIBRARY identifies the device and directory containing system libraries and is normally defined by the system manager. FORSYSDEF.TLB

is a library of include library modules supplied by HP Fortran. It contains local symbol definitions and structures required for use with system services and return status values from system services.

For more information on the contents of FORSYSDEF, see Appendix E.

You can specify /LIST or /NOLIST after the library module name. For example:

INCLUDE ’(MYINC)/NOLIST’

You can also specify the /SHOW=INCLUDE or /SHOW=NOINCLUDE qualifier to control whether source lines from included files or library modules appear in the listing file (see Section 2.3.43).

For More Information:

• On the /ASSUME=[NO]SOURCE_INCLUDE qualifier, see Section 2.3.7.

• On the /INCLUDE qualifier, see Section 2.3.25.

• On creating and using text libraries, see Section 2.4.

Compiling HP Fortran Programs 2–13

2.2.5 Specifying Output Files

The output produced by the compiler includes the object and listing files. You can control the production of these files by using the appropriate qualifiers on the FORTRAN command line.

The production of listing files depends on whether you are operating in interactive mode or batch mode:

• In interactive mode, the compiler does not generate listing files by default; you must use the /LIST qualifier to generate the listing file.

• In batch mode, the compiler generates a listing file by default. To suppress it, you must use the /NOLIST qualifier.

For command procedures that compile the application in either batch or interactive mode, consider explicitly specifying /NOLIST (or /LIST).

The compiler generates an object file by default. During the early stages of program development, you may find it helpful to use the /SYNTAX_ONLY or /NOOBJECT qualifiers to prevent the creation of object files until your source program compiles without errors. If you omit /NOOBJECT, the compiler generates object files as follows:

• If you specify one source file, one object file is generated.

• If you specify multiple source files separated by commas, each source file is compiled separately, and an object file is generated for each source file.

• If you specify multiple source files separated by plus signs, the source files are concatenated and compiled, and one object file is generated.

You can use both commas and plus signs in the same command line to produce different combinations of concatenated and separate object files (see the examples of the FORTRAN command at the end of this section).

To name an object file, use the /OBJECT qualifier in the form /OBJECT=file-

spec. Otherwise, the object file has the file name of its corresponding source file and a file type of OBJ. By default, the object file produced from concatenated source files has the name of the first source file. All other file specification fields (node, device, directory, and version) assume the default values.

When creating object files that will be placed in an object library, consider using the /SEPARATE_COMPILATION qualifier, which places individual compilation units in a source file as separate components in the object file.

This minimizes the size of the routines included by the linker as it creates the executable image. However, to allow more interprocedure optimizations, use the default /NOSEPARATE_COMPILATION.

2–14 Compiling HP Fortran Programs

For More Information:

• On creating and naming object files, see Section 2.2.6.1 and Section 2.3.33.

• On the /SEPARATE_COMPILATION qualifier, see Section 2.3.41.

• On using object libraries, see Chapter 3.

2.2.6 Examples of the FORTRAN Command

The following examples show the use of the FORTRAN command.

2.2.6.1 Naming the Object File

The following FORTRAN command compiles the HP Fortran free-form source file (CIRCLE.F90) into an object file:

$ FORTRAN /OBJECT=[BUILD]SQUARE /NOLIST

Return

_File: CIRCLE

The source file CIRCLE.F90 is compiled, producing an object file named

SQUARE.OBJ in the [BUILD] directory, but no listing file.

2.2.6.2 Compiler Source Checking Only (No Object File)

The following FORTRAN command examines HP Fortran fixed-form source file

(ABC.FOR) without creating an object file:

$ FORTRAN /NOOBJECT ABC.FOR

The source file ABC.FOR is compiled, syntax checking occurs, but no object file is produced. The /NOOBJECT qualifier performs full compilation checking without creating an object file.

2.2.6.3 Requesting a Listing File and Contents

The following FORTRAN command compiles HP Fortran free-form source file

(XYZ.F90) and requests a listing file:

$ FORTRAN /LIST /SHOW=INCLUDE /MACHINE_CODE XYZ.F90

The source file XYZ.F90 is compiled, and the listing file XYZ.LIS and object file

XYZ.OBJ are created. The listing file contains the optional included source files

(/SHOW=INCLUDE) and machine code representation (/MACHINE_CODE).

The default is /NOLIST for interactive use and /LIST for batch use, so consider explicitly specifying either /LIST or /NOLIST.

Compiling HP Fortran Programs 2–15

2.2.6.4 Compiling Multiple Files

The following FORTRAN command compiles the HP Fortran free-form source files (AAA.F90, BBB.F90, and CCC.F90) into separate object files:

$ FORTRAN/LIST AAA.F90, BBB.F90, CCC.F90

Source files AAA.F90, BBB.F90, and CCC.F90 are compiled as separate files, producing:

• Object files named AAA.OBJ, BBB.OBJ, and CCC.OBJ

• Listing files named AAA.LIS, BBB.LIS, and CCC.LIS

The default level of optimization is used (/OPTIMIZE=LEVEL=4), but interprocedure optimizations are less effective because the source files are compiled separately.

The following FORTRAN command compiles the HP Fortran fixed-form source files XXX.FOR, YYY.FOR, and ZZZ.FOR into a single object file named

XXX.OBJ:

$ FORTRAN XXX.FOR+YYY.FOR+ZZZ.FOR

Source files XXX.FOR, YYY.FOR, and ZZZ.FOR are concatenated and compiled as one file, producing an object file named XXX.OBJ. The default level of optimization is used, allowing interprocedure optimizations since the files are compiled together (see Section 5.1.2). In interactive mode, no listing file is created; in batch mode, a listing file named XXX.LIS would be created.

The following FORTRAN command compiles the HP Fortran free-form source files AAA.F90, BBB.F90, and CCC.F90 into two object files:

$ FORTRAN AAA+BBB,CCC/LIST

Two object files are produced: AAA.OBJ (comprising AAA.F90 and BBB.F90) and CCC.OBJ (comprising CCC.F90). One listing file is produced: CCC.LIS

(comprising CCC.F90), since the positional /LIST qualifier follows a specific file name (and not the FORTRAN command). Because the default level of optimization is used, interprocedure optimizations for both AAA.F90 and

BBB.F90 occur. Only interprocedure optimizations within CCC.F90 occur.

The following FORTRAN command compiles the HP Fortran free-form source files ABC.F90, CIRC.F90, and XYZ.F90, but no object file is produced:

$ FORTRAN ABC+CIRC/NOOBJECT+XYZ

The /NOOBJECT qualifier applies to all files in the concatenated file list and suppresses object file creation. Source files ABC.F90, CIRC.F90, and XYZ.F90

are concatenated and compiled, but no object file is produced.

2–16 Compiling HP Fortran Programs

2.2.6.5 Requesting Additional Compile-Time and Run-Time Checking

The following FORTRAN command compiles the HP Fortran free-form source file TEST.F90, requesting all possible compile-time diagnostic messages

(/WARN=ALL) and run-time checking (/CHECK=ALL):

$ FORTRAN /WARNINGS=ALL /CHECK=ALL TEST.F90

This command creates the object file TEST.OBJ and can result in more informational or warning compilation messages than the default level of warning messages. Additional run-time messages can also occur.

2.2.6.6 Checking Fortran 90 or 95 Standard Conformance

The following FORTRAN command compiles the HP Fortran free-form source file PROJ_STAND.F90, requesting compile-time diagnostic messages when extensions to the Fortran 90 language are detected without creating an object file:

$ FORTRAN /STANDARD=F90 /NOOBJECT PROJ_STAND.F90

This command does not create an object file but issues additional compilation messages about the use of any nonstandard extensions to the Fortran 90 standard it detects.

To check for Fortran 95 standard conformance, specify /STANDARD=F95 instead of /STANDARD=F90.

2.2.6.7 Requesting Additional Optimizations

The following FORTRAN command compiles the HP Fortran free-form source files (M_APP.F90 and SUB.F90) as a single concatenated file into one object file:

$ FORTRAN /OPTIMIZE=(LEVEL=5,UNROLL=3) M_APP.F90+SUB.F90/NOLIST

The source files are compiled together, producing an object file named M_

APP.OBJ. The software pipelining optimization (/OPTIMIZE=LEVEL=4) is requested. Loops within the program are unrolled three times (UNROLL=3).

Loop unrolling occurs at optimization level three (LEVEL=3) or above.

For More Information:

• On linking object modules into an executable image (program) and running the program, see Chapter 3.

• On requesting debugger symbol table information, see Section 4.2.1.

• On requesting additional directories to be searched for module files or included source files, see Section 2.3.25 and Section 2.4.

• On the FORTRAN command qualifiers, see Section 2.3.

Compiling HP Fortran Programs 2–17

2.3 FORTRAN Command Qualifiers

FORTRAN command qualifiers influence the way in which the compiler processes a file. In some cases, the simple FORTRAN command is sufficient.

Use optional qualifiers when needed.

You can override some qualifiers specified on the command line by using the

OPTIONS statement. The qualifiers specified by the OPTIONS statement affect only the program unit where the statement occurs. For more information about the OPTIONS statement, see the HP Fortran for OpenVMS Language

Reference Manual.

2.3.1 FORTRAN Command Qualifier Syntax

Normal DCL parsing rules apply to the FORTRAN command, allowing you to abbreviate qualifier names and keywords as long as they are unique.

For example, the following use of the FORTRAN command to specify the

/ALIGNMENT qualifier as NATURAL and the /LIST qualifier is valid:

$ FORTRAN /ALIG=NAT /LIS EXTRAPOLATE.FOR

When creating command procedures, avoid using abbreviations for qualifiers and their keywords. HP Fortran might add new qualifiers and keywords for a subsequent release that makes an abbreviated qualifier and keyword nonunique in a subsequent release.

If you specify multiple keywords for a qualifier, enclose the keywords in parentheses:

$ FORTRAN /WARN=(ALIGN, DECLARATION) EXTRAPOLATE.FOR

To concatenate source files, separate file names with a plus sign ( + ) instead of a comma ( , ). (See Section 2.2.2.)

2.3.2 Summary of FORTRAN Command Qualifiers

Table 2–1 lists the FORTRAN Command qualifiers, including their default values.

Sections 2.3.3 through 2.3.51 describe each qualifier in detail.

2–18 Compiling HP Fortran Programs

Table 2–1 FORTRAN Command Qualifiers

Qualifier

/ALIGNMENT=

> rule

class = rule

(class = rule [, ...])

[NO]SEQUENCE

ALL (or NATURAL)

NONE (or PACKED)

> where:

class =

COMMONS

RECORDS

STRUCTURES and

rule =

NATURAL

PACKED

STANDARD

[NO]MULTILANGUAGE

;

Default

/ALIGNMENT=(COMMONS=(PACKED

NOMULTILANGUAGE), NOSEQUENCE

RECORDS=NATURAL)

/ANALYSIS_DATA[=filename] or /NOANALYSIS_DATA

/ANNOTATIONS=

: n

CODE

DETAIL

INLINING

LOOP_TRANSFORMS

LOOP_UNROLLING

PREFETCHING

SHRINKWRAPPING

SOFTWARE_PIPELINING

TAIL_CALLS

TAIL_RECURSION o

ALL

NONE

[, ...]

/NOANALYSIS_DATA

/NOANNOTATIONS

The default changes if you specify /FAST.

STANDARD and MULTILANGUAGE are valid for class=COMMON (not class=RECORDS).

(continued on next page)

Compiling HP Fortran Programs 2–19

Table 2–1 (Cont.) FORTRAN Command Qualifiers

Qualifier

/ARCHITECTURE=

GENERIC

HOST

EV4

EV5

EV56

PCA56

EV6

EV67

;

/ASSUME=

> n

[NO]ACCURACY_SENSITIVE

[NO]ALTPARAM

[NO]BUFFERED_IO

[NO]BYTERECL

[NO]DUMMY_ALIASES

[NO]FP_CONSTANT

[NO]INT_CONSTANT

[NO]MINUS0

[NO]PROTECT_CONSTANTS

[NO]SOURCE_INCLUDE o

ALL

NONE

[, ...]

/AUTOMATIC or /NOAUTOMATIC

/BY_REF_CALL=(routine-list)

/CCDEFAULT or

(

/CCDEFAULT=

FORTRAN

LIST

NONE

DEFAULT

) 3

The default changes if you specify /FAST.

Default

/ARCHITECTURE=GENERIC 1

/ASSUME=(ACCURACY_SENSITIVE

ALTPARAM, NOBUFFERED_

IO, NOBYTERECL, NODUMMY_

ALIASES, NOFP_CONSTANT,

NOINT_CONSTANT, NOMINUS0,

PROTECT_CONSTANTS, NOSOURCE_

INCLUDE)

/NOAUTOMATIC

No default

/CCDEFAULT=DEFAULT

(continued on next page)

2–20 Compiling HP Fortran Programs

Table 2–1 (Cont.) FORTRAN Command Qualifiers

Qualifier

/CHECK=

: n

[NO]ARG_INFO (I64 only)

[NO]ARG_TEMP_CREATED

[NO]BOUNDS

[NO]FORMAT

[NO]FP_EXCEPTIONS

[NO]FP_MODE (I64 only)

[NO]OUTPUT_CONVERSION

[NO]OVERFLOW

[NO]POWER

[NO]UNDERFLOW o

ALL

NONE

;

[, ...]

/CONVERT=

BIG_ENDIAN

CRAY

FDX

FGX

IBM

LITTLE_ENDIAN

NATIVE

VAXD

VAXG

/D_LINES or /NOD_LINES n

/DEBUG=

4 n

[NO]SYMBOLS

[NO]TRACEBACK o

ALL

NONE o

[, ...]

/DIAGNOSTICS[=filename] or /NODIAGNOSTICS

/DML

/DOUBLE_SIZE= n

128 o

/ERROR_LIMIT=n or /NOERROR_LIMIT

The default changes if you specify /NOVMS.

Default

/CHECK=(NOARG_TEMP_CREATED,

NOBOUNDS, FORMAT

, NOFP_

EXCEPTIONS, OUTPUT_CONVERSION

NOOVERFLOW, POWER, NOUNDER-

FLOW)

/CONVERT=NATIVE

/NOD_LINES

/DEBUG=(NOSYMBOLS,

TRACEBACK)

/NODIAGNOSTICS

Omitted

/DOUBLE_SIZE=64

/ERROR_LIMIT=30

(continued on next page)

Compiling HP Fortran Programs 2–21

Table 2–1 (Cont.) FORTRAN Command Qualifiers

Qualifier

/EXTEND_SOURCE or /NOEXTEND_SOURCE

/F77 or /NOF77

/FAST

/FLOAT=

D_FLOAT

G_FLOAT

IEEE_FLOAT

/GRANULARITY=

BYTE

LONGWORD

QUADWORD

Default

/NOEXTEND_SOURCE

/F77

No default

/FLOAT=IEEE (I64)

/FLOAT=G_FLOAT (Alpha)

/GRANULARITY=QUADWORD

/IEEE_MODE=

FAST

UNDERFLOW_TO_ZERO

DENORM_RESULTS

/INCLUDE=directory [, ...] or /NOINCLUDE

/INTEGER_SIZE=

/LIBRARY

/LIST[=file-spec] or /NOLIST

/IEEE_MODE=DENORM_RESULTS

(I64)

/IEEE_MODE=FAST (Alpha)

/NOINCLUDE

/INTEGER_SIZE=32

/MACHINE_CODE or /NOMACHINE_CODE n

/MATH_LIBRARY=

ACCURATE o

FAST

(Alpha only)

/MODULE=directory or /NOMODULE

/NAMES=

UPPERCASE

LOWERCASE

AS_IS

/OBJECT[=file-spec] or /NOOBJECT

/OLD_F77 (Alpha only)

No default

/NOLIST (interactive)

/LIST (batch)

/NOMACHINE_CODE

/MATH_LIBRARY=ACCURATE

/NOMODULE

/NAMES=UPPERCASE

/OBJECT

Omitted

The default changes if you specify /FAST.

Use the /FLOAT qualifier instead of the /[NO]G_FLOAT qualifier; use the /INTEGER_SIZE qualifier instead of the /[NO]I4 qualifier.

(continued on next page)

2–22 Compiling HP Fortran Programs

Table 2–1 (Cont.) FORTRAN Command Qualifiers

Qualifier

/OPTIMIZE=

LEVEL=n

INLINE=

NOINLINE

LOOPS

TUNE=

NONE

MANUAL

SIZE

SPEED

ALL

GENERIC

HOST

EV4

EV5

EV56

PCA56

EV6

EV67

UNROLL=n

[, ...]

/PAD_SOURCE or /NOPAD_SOURCE

/REAL_SIZE=

128

/RECURSIVE or /NORECURSIVE

/NOREENTRANCY or /REENTRANCY=

ASYNC

NONE

THREADED

/ROUNDING_MODE=

NEAREST

CHOPPED

DYNAMIC

MINUS_INFINITY

;

/SEPARATE_COMPILATION or /NOSEPARATE_COMPILATION

/SEVERITY=WARNINGS=

WARNING

ERROR

STDERROR

Default

/OPTIMIZE (same as /OPTIMIZE=

(LEVEL=4, INLINE=SPEED,

NOLOOPS, NOPIPELINE,

TUNE=GENERIC

, UNROLL=0))

/NOPAD_SOURCE

/REAL_SIZE=32

/NORECURSIVE

/REENTRANCY=NONE

/ROUNDING_MODE=NEAREST

/NOSEPARATE_COMPILATION

/SEVERITY=WARNINGS=(WARNING)

The default changes if you specify /FAST.

(continued on next page)

Compiling HP Fortran Programs 2–23

Table 2–1 (Cont.) FORTRAN Command Qualifiers

Qualifier

/SHOW=

: n

[NO]DICTIONARY

[NO]INCLUDE

[NO]MAP

[NO]PREPROCESSOR o

ALL

NONE

;

[, ...]

/SOURCE_FORM= n

FREE

FIXED

/STANDARD= n

F90

F95 o o or /NOSTANDARD

/SYNCHRONOUS_EXCEPTIONS or

/NOSYNCHRONOUS_EXCEPTIONS (Alpha only)

/SYNTAX_ONLY or /NOSYNTAX_ONLY

/TIE or /NOTIE

/VERSION

/VMS or /NOVMS

/WARNINGS or /NOWARNINGS or

/WARNINGS=

[NO]ALIGNMENT

[NO]ARGUMENT_CHECKING

[NO]DECLARATIONS

[NO]GENERAL

[NO]GRANULARITY

[NO]IGNORE_LOC

[NO]TRUNCATED_SOURCE

[NO]UNCALLED

[NO]UNINITIALIZED

[NO]UNUSED

[NO]USAGE n o

ALL

NONE

[, ...]

Default

/SHOW=(NODICTIONARY, NOINCLUDE,

MAP, NOPREPROCESSOR )

Depends on file type (F90 for free form and FOR or F for fixed form)

/NOSTANDARD

/NOSYNCHRONOUS_EXCEPTIONS

/NOSYNTAX_ONLY

/NOTIE

Omitted

/VMS

/WARNINGS=(ALIGNMENT,

NOARGUMENT_CHECKING,

NODECLARATIONS, GENERAL,

GRANULARITY, NOIGNORE_

LOC, NOTRUNCATED_SOURCE,

UNCALLED, UNINITIALIZED,

NOUNUSED, USAGE )

Table 2–2 shows the functional groupings of the FORTRAN command qualifiers and the section in which they are described in more detail.

2–24 Compiling HP Fortran Programs

Table 2–2 FORTRAN Command Flags and Categories

Category Flag Name and Section in this Manual

Carriage control for terminal or printer displays

Code generation for specific

Alpha chip

Convert Nonnative Data Files

/CCDEFAULT (see Section 2.3.10)

/ARCHITECTURE (Alpha only) (see Section 2.3.6)

Data Size

Data Storage and Recursion

Debugging and Symbol Table

Floating-Point Exceptions and

Accuracy

Floating-Point Format in

Memory

/CONVERT (see Section 2.3.12)

/ASSUME=BYTERECL (see Section 2.3.7)

Also see Chapter 9.

/DOUBLE_SIZE (see Section 2.3.17)

/INTEGER_SIZE (see Section 2.3.26)

/REAL_SIZE (see Section 2.3.37)

Also see Chapter 8.

/AUTOMATIC (see Section 2.3.8)

/RECURSIVE (see Section 2.3.38)

/D_LINES (see Section 2.3.13)

/DEBUG (see Section 2.3.14)

Also see Chapter 4.

/ASSUME=([NO]ACCURACY_SENSITIVE, [NO]FP_

CONSTANT, [NO]MINUS0,) (see Section 2.3.7)

/CHECK=([NO]FP_EXCEPTIONS, [NO]POWER, [NO]UN-

DERFLOW) (see Section 2.3.11)

/DOUBLE_SIZE (see Section 2.3.17)

/FAST (see Section 2.3.21)

/FLOAT (see Section 2.3.22)

/IEEE_MODE (see Section 2.3.24)

/MATH_LIBRARY (Alpha only) (see Section 2.3.30)

/REAL_SIZE (see Section 2.3.37)

/ROUNDING_MODE (see Section 2.3.40)

/SYNCHRONOUS_EXCEPTIONS (Alpha only) (see

Section 2.3.46)

/FLOAT (see Section 2.3.22)

(continued on next page)

Compiling HP Fortran Programs 2–25

Table 2–2 (Cont.) FORTRAN Command Flags and Categories

Category Flag Name and Section in this Manual

Language Compatibility

Language-Sensitive Editor Use

Listing File and Contents

Module File Searching and

Placement; Include File

Searching

Multithreaded Applications

Object File Creation, Contents,

Naming, and External Names

Performance Optimizations and

Alignment

/DML (see Section 2.3.16)

/F77 (see Section 2.3.20)

/ALIGNMENT=COMMONS=STANDARD (see Section 2.3.3)

/ASSUME=( [NO]ALTPARAM, [NO]DUMMY_ALIASES,

[NO]INT_CONSTANT, /[NO]PROTECT_CONSTANTS ) (see

Section 2.3.7)

/BY_REF_CALL (see Section 2.3.9)

/OLD_F77 (Alpha only) (see Section 2.3.34)

/PAD_SOURCE (see Section 2.3.44)

/SEVERITY (see Section 2.3.42)

/STANDARD (see Section 2.3.45)

/VMS (see Section 2.3.50)

/DIAGNOSTICS (see Section 2.3.15)

/ANNOTATIONS (see Section 2.3.5)

/LIST (see Section 2.3.28)

/MACHINE_CODE (see Section 2.3.29)

/SHOW (see Section 2.3.43)

Also see Section 2.7.

/INCLUDE (see Section 2.3.25)

/ASSUME=[NO]SOURCE_INCLUDE (see Section 2.3.7)

/LIBRARY (see Section 2.3.27)

/MODULE (see Section 2.3.31)

Also see Section 2.2.3 (modules), Section 2.2.4 (include files), and Section 2.4 (text libraries).

/REENTRANCY (see Section 2.3.39)

/OBJECT (see Section 2.3.33)

/NAMES (see Section 2.3.32)

/SEPARATE_COMPILATION (see Section 2.3.41)

/SYNTAX_ONLY (see Section 2.3.47)

/TIE (see Section 2.3.49)

/ALIGNMENT (see Section 2.3.3)

/ASSUME=(NOACCURACY_SENSITIVE, NODUMMY_

ALIASES) (see Section 2.3.7)

/ARCHITECTURE (Alpha only) (see Section 2.3.6)

/FAST (see Section 2.3.21)

/MATH_LIBRARY (Alpha only) (see Section 2.3.30)

/OPTIMIZE (see Section 2.3.35)

Also see Chapter 5.

(continued on next page)

2–26 Compiling HP Fortran Programs

Table 2–2 (Cont.) FORTRAN Command Flags and Categories

Category Flag Name and Section in this Manual

Recursion and Shared Access to

Data

Source Code Analyzer Use

Source Form and Column Use

Warning Messages and Run-

Time Checking

/GRANULARITY (see Section 2.3.23)

/RECURSIVE (see Section 2.3.38)

/REENTRANCY (see Section 2.3.39)

/WARNINGS=GRANULARITY (see Section 2.3.51)

/ANALYSIS_DATA (see Section 2.3.4)

/D_LINES (see Section 2.3.13)

/EXTEND_SOURCE (see Section 2.3.19)

/PAD_SOURCE (see Section 2.3.36)

/SOURCE_FORM (see Section 2.3.44)

/WARNINGS=TRUNCATED_SOURCE (see Section 2.3.51)

/CHECK (see Section 2.3.11)

/ERROR_LIMIT (see Section 2.3.18)

/IEEE_MODE (see Section 2.3.24)

/SEVERITY (see Section 2.3.42)

/WARNINGS (see Section 2.3.51)

Also see the qualifiers related to ‘‘Floating-Point Exceptions and Accuracy’’ in this table.

2.3.3 /ALIGNMENT — Data Alignment

The /ALIGNMENT qualifier controls the data alignment of numeric fields in common blocks and structures.

If you omit the /ALIGNMENT and /FAST qualifiers:

• Individual data items (not part of a common block or other structure) are naturally aligned.

• Fields in derived-type (user-defined) structures (where the SEQUENCE statement is omitted) are naturally aligned.

• Fields in Compaq Fortran 77 record structures are naturally aligned.

• Data items in common blocks are not naturally aligned, unless data declaration order has been planned and checked to ensure that all data items are naturally aligned.

Although HP Fortran always aligns local data items on natural boundaries, certain data declaration statements and unaligned arguments can force unaligned data.

Use the /ALIGNMENT qualifier to control the alignment of fields associated with common blocks, derived-type structures, and record structures.

Compiling HP Fortran Programs 2–27

The compiler issues messages when it detects unaligned data by default

(/WARNINGS=ALIGNMENT). For information about the causes of unaligned data and detection at run time, see Section 5.3.

Note

Unaligned data significantly increases the time it takes to execute a program, depending on the number of unaligned fields encountered.

Specifying /ALIGNMENT=ALL (same as /ALIGNMENT=NATURAL) minimizes unaligned data.

The qualifier has the following form:

< rule

class = rule

(class = rule [, ...])

/ALIGNMENT=

[NO]SEQUENCE

ALL (or NATURAL)

NONE (or PACKED)

> where: class =

(

COMMONS

RECORDS

STRUCTURES

) and rule =

NATURAL

PACKED

STANDARD

[NO]MULTILANGUAGE

STANDARD and MULTILANGUAGE are valid for class=COMMON (not

class=RECORDS).

The /ALIGNMENT qualifier keywords specify whether the HP Fortran compiler should naturally align or arbitrarily pack the following: class

Specifies the type of data blocks:

• COMMONS=rule applies to common blocks (COMMON statement); rule can be PACKED, STANDARD, NATURAL, or MULTILANGUAGE.

• RECORDS=rule applies to derived-type and record structures; rule can be

PACKED or NATURAL. However, if a derived-type data definition specifies the SEQUENCE statement, the FORTRAN /ALIGNMENT qualifier has no effect on unaligned data, so data declaration order must be carefully planned to naturally align data.

2–28 Compiling HP Fortran Programs

• STRUCTURES=rule applies to derived-type and record structures; rule can be PACKED or NATURAL. For the HP Fortran language, STRUCTURES and RECORDS are the same (they may have a different meaning in other

OpenVMS languages).

rule

Specifies the alignment for the specified class of data blocks:

• NATURAL requests that fields in derived-type and record structures and data items in common blocks be naturally aligned on up to 8-byte boundaries, including INTEGER (KIND=8) and REAL (KIND=8) data.

Specifying /ALIGNMENT=NATURAL is equivalent to any of the following:

/ALIGNMENT

/ALIGNMENT=ALL

/ALIGNMENT=(COMMONS=(NATURAL,NOMULTILANGUAGE),RECORDS=NATURAL,SEQUENCE)

• PACKED requests that fields in derived-type and record structures and data items in common blocks be packed on arbitrary byte boundaries and not naturally aligned.

Specifying /ALIGNMENT=PACKED is equivalent to any of the following:

/ALIGNMENT=NONE

/NOALIGNMENT

/ALIGNMENT=(COMMONS=(PACKED,NOMULTILANGUAGE),RECORDS=PACKED,NOSEQUENCE)

• STANDARD specifies that data items in common blocks will be naturally aligned on up to 4-byte boundaries (consistent with the FORTRAN-77,

Fortran 90, and Fortran 95 standards).

The compiler will not naturally align INTEGER (KIND=8) and REAL

(KIND=8) data declarations. Such data declarations should be planned so they fall on natural boundaries. Specifying /ALIGNMENT=COMMONS=-

STANDARD alone is the same as /ALIGNMENT=(COMMONS=

(STANDARD,NOMULTILANGUAGE),RECORDS=NATURAL).

You cannot specify /ALIGNMENT=RECORDS=STANDARD or

/ALIGNMENT=STANDARD.

• MULTILANGUAGE specifies that the compiler pad the size of common block program sections to ensure compatibility when the common block program section is shared by code created by other OpenVMS compilers.

Compiling HP Fortran Programs 2–29

When a program section generated by a Fortran common block is overlaid with a program section consisting of a C structure, linker error messages can result. This is because the sizes of the program sections are inconsistent; the C structure is padded and the Fortran common block is not.

Specifying /ALIGNMENT=COMMONS=MULTILANGUAGE ensures that

HP Fortran follows a consistent program section size allocation scheme that works with HP C program sections that are shared across multiple images.

Program sections shared in a single image do not have a problem. The equivalent HP C qualifier is /PSECT_MODEL=[NO]MULTILANGUAGE.

The default is /ALIGNMENT=COMMONS=NOMULTILANGUAGE, which also is the default behavior of Compaq Fortran 77 and is sufficient for most applications.

The [NO]MULTILANGUAGE keyword only applies to common blocks. You can specify /ALIGNMENT=COMMONS=[NO]MULTILANGUAGE, but you cannot specify /ALIGNMENT=[NO]MULTILANGUAGE.

[NO]SEQUENCE

Specifying /ALIGNMENT=SEQUENCE means that components of derived types with the SEQUENCE attribute will obey whatever alignment rules are currently in use. The default alignment rules align components on natural boundaries.

The default value of /ALIGNMENT=NOSEQUENCE means that components of derived types with the SEQUENCE attribute will be packed, regardless of whatever alignment rules are currently in use.

Specifying /FAST sets /ALIGNMENT=SEQUENCE so that components of derived types with the SEQUENCE attribute will be naturally aligned for improved performance. Specifying /ALIGNMENT=ALL also sets

/ALIGNMENT=SEQUENCE.

ALL

Specifying /ALIGNMENT=ALL is equivalent to /ALIGNMENT,

/ALIGNMENT=NATURAL), or /ALIGNMENT=(COMMONS=

(NATURAL,NOMULTILANGUAGE),RECORDS=NATURAL,SEQUENCE).

NONE

Specifying /ALIGNMENT=NONE is equivalent to /NOALIGNMENT, /ALIGN-

MENT=PACKED, or /ALIGNMENT=(COMMONS=(PACKED,

NOMULTILANGUAGE), RECORDS=PACKED,NOSEQUENCE).

2–30 Compiling HP Fortran Programs

Defaults depend on whether you specify or omit the /ALIGNMENT and /FAST qualifiers, as follows:

Command Line Default

Omit /ALIGNMENT and omit

/FAST

Omit /ALIGNMENT and specify /FAST

/ALIGNMENT=(COMMONS=(PACKED,NOMULTI-

LANGUAGE),NOSEQUENCE,RECORDS=-

NATURAL)

/ALIGNMENT=(COMMONS=NATURAL,

RECORDS=NATURAL,SEQUENCE)

/ALIGNMENT=COMMONS=rule Use whatever the /ALIGNMENT qualifier specifies for COMMONS, but use the default of

RECORDS=NATURAL

/ALIGNMENT=RECORDS=rule Use whatever the /ALIGNMENT qualifier specifies for RECORDS, but use the default for COMMONS

(depends on whether /FAST was specified or omitted)

You can override the alignment specified on the command line by using a cDEC$ OPTIONS directive, as described in the HP Fortran for OpenVMS

Language Reference Manual.

The /ALIGNMENT and /WARNINGS=ALIGNMENT qualifiers can be used together in the same command line.

For More Information:

• On run-time performance guidelines, see Chapter 5.

• On data alignment, see Section 5.3.

• On checking for alignment traps with a condition handler, see Section 14.12.

• On intrinsic data sizes, see Chapter 8.

• On the /FAST qualifier, see Section 2.3.21.

2.3.4 /ANALYSIS_DATA—Create Analysis Data File

The /ANALYSIS_DATA qualifier produces an analysis data file that contains cross-reference and static-analysis information about the source code being compiled.

Analysis data files are reserved for use by products such as, but not limited to, the Source Code Analyzer (SCA).

The qualifier has the following form:

/ANALYSIS_DATA[=filename.type]

Compiling HP Fortran Programs 2–31

If you omit the file specification, the analysis file name has the name of the primary source file and a file type of ANA (filename.ANA).

The compiler produces one analysis file for each source file that it compiles. If you are compiling multiple files and you specify a particular name as the name of the analysis file, each analysis file is given that name (with an incremental version number).

If you do not specify the /ANALYSIS_DATA qualifier, the default is

/NOANALYSIS_DATA.

2.3.5 /ANNOTATIONS — Code Descriptions

The /ANNOTATIONS qualifier controls whether an annotated listing showing optimizations is included with the listing file.

The qualifier has the following form:

/ANNOTATIONS=

> n

CODE

DETAIL

INLINING

LOOP_TRANSFORMS

LOOP_UNROLLING

PREFETCHING

SHRINKWRAPPING

SOFTWARE_PIPELINING

TAIL_CALLS

TAIL_RECURSION

ALL o

NONE

[, ...]

CODE

Annotates the machine code listing with descriptions of special instructions used for prefetching, alignment, and so on.

DETAIL

Provides additional level of annotation detail, where available.

INLINING

Indicates where code for a called procedure was expanded inline.

LOOP_TRANSFORMS

Indicates where advanced loop nest optimizations have been applied to improve cache performance.

2–32 Compiling HP Fortran Programs

LOOP_UNROLLING

Indicates where a loop was unrolled (contents expanded multiple times).

PREFETCHING

Indicates where special instructions were used to reduce memory latency.

SHRINKWRAPPING

Indicates removal of code establishing routine context when it is not needed.

SOFTWARE_PIPELINING

Indicates where instructions have been rearranged to make optimal use of the processor’s functional units.

TAIL_CALLS

Indicates an optimization where a call can be replaced with a jump.

TAIL_RECURSION

Indicates an optimization that eliminates unnecessary routine context for a recursive call.

ALL

All annotations, including DETAIL, are selected. This is the default if no keyword is specified.

NONE

No annotations are selected. This is the same as /NOANNOTATIONS.

2.3.6 /ARCHITECTURE — Architecture Code Instructions (Alpha only)

The /ARCHITECTURE qualifier specifies the type of Alpha architecture code instructions generated for a particular program unit being compiled; it uses the same options (keywords) as used by the /OPTIMIZE=TUNE (Alpha only) qualifier (for instruction scheduling purposes).

OpenVMS Version 7.1 and subsequent releases provide an operating system kernel that includes an instruction emulator. This emulator allows new instructions, not implemented on the host processor chip, to execute and produce correct results. Applications using emulated instructions will run correctly but may incur significant software emulation overhead at runtime.

All Alpha processors implement a core set of instructions. Certain Alpha processor versions include additional instruction extensions.

Compiling HP Fortran Programs 2–33

The qualifier has the following form:

/ARCHITECTURE=

GENERIC

HOST

EV4

EV5

EV56

PCA6

EV6

;

EV67

GENERIC

Generates code that is appropriate for all Alpha processor generations. This is the default.

Programs compiled with the GENERIC option run on all implementations of the Alpha architecture without any instruction emulation overhead.

HOST

Generates code for the processor generation in use on the system being used for compilation.

Programs compiled with this option may encounter instruction emulation overhead if run on other implementations of the Alpha architecture.

EV4

Generates code for the 21064, 21064A, 21066, and 21068 implementations of the Alpha architecture. Programs compiled with the EV4 option run on all

Alpha processors without instruction emulation overhead.

EV5

Generates code for some 21164 chip implementations of the Alpha architecture that use only the base set of Alpha instructions (no extensions). Programs compiled with the EV5 option run on all Alpha processors without instruction emulation overhead.

EV56

Generates code for some 21164 chip implementations that use the BWX

(Byte/Word manipulation) instruction extensions of the Alpha architecture.

Programs compiled with the EV56 option may incur emulation overhead on

EV4 and EV5 processors but still run correctly on OpenVMS Version 7.1 (or later) systems.

2–34 Compiling HP Fortran Programs

PCA56

Generates code for the 21164PC chip implementation that uses the BWX

(Byte/Word manipulation) and MAX (Multimedia) instruction extensions of the

Alpha architecture.

Programs compiled with the PCA56 option may incur emulation overhead on EV4, EV5, and EV56 processors but will still run correctly on OpenVMS

Version 7.1 (or later) systems.

EV6

Generates code for the 21264 chip implementation that uses the following extensions to the base Alpha instruction set: BWX (Byte/Word manipulation) and MAX (Multimedia) instructions, square root and floating-point convert instructions, and count instructions.

Programs compiled with the EV6 option may incur emulation overhead on EV4,

EV5, EV56, and PCA56 processors but will still run correctly on OpenVMS

Version 7.1 (or later) systems.

EV67

Generates code for chip implementations that use advanced instruction extensions of the Alpha architecture. This option permits the compiler to generate any EV67 instruction, including the following extensions to the base

Alpha instruction set: BWX (Byte/Word manipulation), MVI (Multimedia) instructions, square root and floating-point convert extensions (FIX), and count extensions (CIX).

Programs compiled with the EV67 keyword might incur emulation overhead on EV4, EV5, EV56, PCA56, and EV6 processors but still run correctly on

OpenVMS Alpha systems.

2.3.7 /ASSUME — Compiler Assumptions

The /ASSUME qualifier specifies a variety of assumptions:

• Whether the compiler should use certain code transformations that affect floating-point operations. These changes may affect the accuracy of the program’s results.

• What the compiler can assume about program behavior without affecting correct results when it optimizes code.

• Whether a single-precision constant assigned to a double-precision variable should be evaluated in single or double precision.

Compiling HP Fortran Programs 2–35

• Changes the directory where the compiler searches for files specified by an

INCLUDE statement to the directory where the source files reside, not the current default directory.

The qualifier has the following form:

/ASSUME=

> n

[NO]ACCURACY_SENSITIVE

[NO]ALTPARAM

[NO]BUFFERED_IO

[NO]BYTERECL

[NO]DUMMY_ALIASES

[NO]FP_CONSTANT

[NO]INT_CONSTANT

[NO]MINUS0

[NO]PROTECT_CONSTANTS

[NO]SOURCE_INCLUDE

ALL o

NONE

[, ...]

[NO]ACCURACY_SENSITIVE

If you use ACCURACY_SENSITIVE (the default unless you specified /FAST), the compiler uses a limited number of rules for calculations, which might prevent some optimizations.

Specifying NOACCURACY_SENSITIVE allows the compiler to reorder code based on algebraic identities (inverses, associativity, and distribution) to improve performance. The numeric results can be slightly different from the default (ACCURACY_SENSITIVE) because of the way intermediate results are rounded. Specifying the /FAST qualifier (described in Section 2.3.21) changes the default to NOACCURACY_SENSITIVE.

Numeric results with NOACCURACY_SENSITIVE are not categorically less accurate. They can produce more accurate results for certain floating-point calculations, such as dot product summations.

For example, the following expressions are mathematically equivalent but may not compute the same value using finite precision arithmetic.

X = (A + B) - C

X = A + (B - C)

Optimizations that result in calls to a special reciprocal square root routine for expressions of the form 1.0/SQRT(x) or A/SQRT(B) are enabled only if

/ASSUME=NOACCURACY_SENSITIVE is in effect.

2–36 Compiling HP Fortran Programs

[NO]ALTPARAM

Specifying the /ASSUME=ALTPARAM qualifier allows the alternate syntax for PARAMETER statements. The alternate form has no parentheses surrounding the list, and the form of the constant, rather than implicit or explicit typing, determines the data type of the variable. The default is

/ASSUME=ALTPARAM.

[NO]BUFFERED_IO

The /ASSUME=[NO]BUFFERED_IO qualifier is provided for compatibility with other platforms. On OpenVMS systems, the SET RMS command controls the number of output buffers.

Specifying /ASSUME=BUFFERED_IO requests that buffered I/O be used for all Fortran logical units opened for sequential writing (the default is

NOBUFFERED_IO). On OpenVMS systems, this qualifier has an effect only if the system or process RMS default buffers are set to 1.

[NO]BYTERECL

Specifying the /ASSUME=BYTERECL qualifier:

• Indicates that the OPEN statement RECL value for unformatted files is in byte units. If you omit /ASSUME=BYTERECL, HP Fortran expects the OPEN statement RECL value for unformatted files to be in longword

(4-byte) units.

• Returns the record length value for an INQUIRE by output item list

(unformatted files) in byte units. If you omit /ASSUME=BYTERECL, HP

Fortran returns the record length for an INQUIRE by output item list in longword (4-byte) units.

• Returns the record length value for an INQUIRE by unit or file name

(unformatted files) in byte units if all of the following occur:

You had specified /ASSUME=BYTERECL for the code being executed

The file was opened with an OPEN statement and a RECL specifier

The file is still open (connected) when the INQUIRE occurs.

If any one of the preceding conditions are not met, HP Fortran returns the

RECL value for an INQUIRE in longword (4-byte) units.

To specify /ASSUME=BYTERECL your application must be running on a system that has the associated Fortran Run-Time Library support. This support is provided by installing one of the following on the system where the application will be run:

• HP Fortran Version 7.0 or later

Compiling HP Fortran Programs 2–37

• OpenVMS Version 7.0 or later

If you specify /ASSUME=BYTERECL and your application is running on a system without the proper Run-Time Library support, it will fail with an

INVARGFOR, Invalid argument to Fortran Run-Time Library error.

[NO]DUMMY_ALIASES

Specifies whether dummy (formal) arguments are permitted to share memory locations with COMMON block variables or other dummy arguments.

If you specify DUMMY_ALIASES, the compiler must assume that dummy

(formal) arguments to procedures share memory locations with other dummy arguments or with variables shared through use association, host association, or common block use.

These program semantics do not strictly obey the Fortran 90 and Fortran 95

Standards and slow performance.

If you use NODUMMY_ALIASES, the default, the compiler does not need to make these assumptions, which results in better run-time performance.

However, omitting /ASSUME=DUMMY_ALIASES can cause some programs that depend on such aliases to fail or produce wrong answers.

You only need to compile the called subprogram with DUMMY_ALIASES.

If you compile a program that uses dummy aliasing with NODUMMY_

ALIASES in effect, the run-time behavior of the program will be unpredictable.

In such programs, the results will depend on the exact optimizations that are performed. In some cases, normal results will occur; however, in other cases, results will differ because the values used in computations involving the offending aliases will differ.

[NO]FP_CONSTANT

Specifies whether a single-precision constant assigned to a double-precision variable will be evaluated in double precision.

If you use NOFP_CONSTANT, the default, a single-precision constant assigned to a double-precision variable is evaluated in single precision. The Fortran 90 and 95 standards require that the constant be evaluated in single precision.

If you specify FP_CONSTANT, a single-precision constant assigned to a double-precision variable is evaluated in double precision.

Certain programs created for FORTRAN-77 compilers (including Compaq

Fortran 77) may show different results with FP_CONSTANT than when you use NOFP_CONSTANT, because they rely on single-precision constants assigned to a double-precision variable to be evaluated in double precision.

2–38 Compiling HP Fortran Programs

In the following example, if you specify FP_CONSTANT, identical values are assigned to D1 and D2. If you use NOFP_CONSTANT, HP Fortran will follow the standard and assign a less precise value to D1:

REAL (KIND=8) D1,D2

DATA D1 /2.71828182846182/ ! REAL (KIND=4) value expanded to double

DATA D2 /2.71828182846182D0/ ! Double value assigned to double

[NO]INT_CONSTANT

Specifies whether Compaq Fortran 77 or Fortran 90/95 semantics are used to determine the type for integer constants.

If you specify /ASSUME=INT_CONSTANT, integer constants take their type from the value, as interpreted by Compaq Fortran 77.

If you specify /ASSUME=NOINT_CONSTANT, integer constants have Fortran

90/95 ‘‘default integer’’ type. This is the default.

[NO]MINUS0

Controls whether the compiler uses Fortran 95 standard semantics for the

IEEE floating-point value of -0.0 (minus zero) in the SIGN intrinsic, if the processor is capable of distinguishing the difference between -0.0 and +0.0.

The default is /ASSUME=NOMINUS0, which uses Fortran 90 and FORTRAN

77 semantics where the value -0.0 or +0.0 in the SIGN function is treated as an 0.0.

To request Fortran 95 semantics, specify /ASSUME=MINUS0 to allow use of the IEEE value -0.0 in the SIGN intrinsic and printing -0.0. This option applies only to programs compiled with the /FLOAT=IEEE_FLOAT qualifier.

[NO]PROTECT_CONSTANTS

Specifies whether constant actual arguments can be changed. By default, actual arguments that are constants are read-only (/ASSUME=PROTECT_

CONSTANTS): any attempt to modify them in the called routine results in an error. /ASSUME=NOPROTECT_CONSTANTS specifies that a copy of a constant actual argument is to be passed, so it can be modified by the called routine, even though the Fortran standard prohibits such modification. The constant is not modified in the calling routine.

If NOPROTECT_CONSTANTS is specified, a writeable copy of the constant is passed as the actual argument.

[NO]SOURCE_INCLUDE

Controls whether the directory where the compiler searches for source files or text libraries specified by an INCLUDE statement is either:

Compiling HP Fortran Programs 2–39

• The current default directory (NOSOURCE_INCLUDE)

• The directory where the source file reside (SOURCE_INCLUDE)

The default, NOSOURCE_INCLUDE, indicates that the compiler should search in the current default directory.

Specifying SOURCE_INCLUDE causes the compiler to search the directory of the source file specified on the FORTRAN command line, instead of the current default directory.

You can specify additional directories for the compiler to search for module files, include files, or include libraries by using the /INCLUDE qualifier.

For More Information:

• On the effect of /ASSUME=NOACCURACY_SENSITIVE on optimizations, see Section 5.8.8.

• On converting and using nonnative unformatted data files, see Chapter 9.

• On the INQUIRE statement, see Chapter 6.

• On the effect and an example of /ASSUME=DUMMY_ALIASES, see

Section 5.8.9.

• On the /INCLUDE qualifier, see Section 2.3.25.

2.3.8 /AUTOMATIC — Data Storage

The /AUTOMATIC and /NOAUTOMATIC qualifiers are synonyms of

/RECURSIVE or /NORECURSIVE (see Section 2.3.38). This qualifier is provided for Compaq Fortran 77 compatibility.

2.3.9 /BY_REF_CALL — Character Literal Argument Passing

Specifying /BY_REF_CALL=routine-list indicates that character constants used as actual arguments in calls to the specified routines be passed by reference and not by character descriptor. This helps applications that pass quoted character constants to numeric dummy parameters, such as applications ported from OpenVMS VAX systems that rely on the OpenVMS VAX Linker to change the argument passing mechanism for character constant actual arguments.

By default, HP Fortran passes character constants used as actual arguments by the usual OpenVMS character descriptor mechanism.

2–40 Compiling HP Fortran Programs

You can specify a list of routines or use wildcard characters (such as an asterisk ( * )) to indicate all routines, for example:

$ FORTRAN/BY_REF_CALL=(PROJA_ROUT,PROJB_ROUT) TEST.FOR

$ FORTRAN/BY_REF_CALL=(*) APPLIC.FOR

The first FORTRAN command requests special character constant actual argument handling for two specific routines. The second requests this for all routines. You can select routines whose names match certain characters and a wildcard, such as all routines that start with MY:

$ FORTRAN/BY_REF_CALL=(MY*) X.FOR

2.3.10 /CCDEFAULT — Carriage Control for Terminals

The /CCDEFAULT qualifiers specify default carriage control when a terminal or printer displays a file.

The qualifier has the following form:

2 3

/CCDEFAULT=

FORTRAN

LIST

NONE

= 7

DEFAULT

FORTRAN

Specifying /CCDEFAULT=FORTRAN results in normal Fortran interpretation of the first character, such as the character ‘‘0’’ resulting in a blank line before output.

LIST

Specifying /CCDEFAULT=LIST results in one linefeed between records.

NONE

Specifying /CCDEFAULT=NONE results in no carriage control processing.

DEFAULT

Specifying /CCDEFAULT=DEFAULT results in the possibility of other qualifiers, such as /VMS, affecting this default setting: if /NOVMS is specified, the default is LIST; otherwise, the default is FORTRAN.

Compiling HP Fortran Programs 2–41

2.3.11 /CHECK — Generate Code for Run-Time Checking

The /CHECK qualifier requests certain error checking during program execution (run time). The compiler produces extra code that performs the checks.

The qualifier has the following form:

/CHECK=

> n

[NO]ARG_INFO (I64 only)

[NO]ARG_TEMP_CREATED

[NO]BOUNDS

[NO]FORMAT

[NO]FP_EXCEPTIONS

[NO]FP_MODE (I64 only)

[NO]OUTPUT_CONVERSION

[NO]OVERFLOW

[NO]POWER

[NO]UNDERFLOW

ALL o

NONE

;

[, ...]

[NO]ARG_INFO (I64 only)

Controls whether run-time checking of the actual argument list occurs. For actual arguments that correspond to declared formal parameters, the check compares the run-time argument type information for arguments passed in registers with the type that is expected. An informational message is issued at run time for each miscompare. Extra actual arguments or too few actual arguments are not reported.

With the default, NOARG_INFO, no check is made.

ARG_TEMP_CREATED

Controls whether a run-time warning message is displayed (execution continues) if a temporary is created for an array actual argument passed to a called routine.

[NO]BOUNDS

Controls whether run-time checking occurs for each dimension of an array reference or substring reference to determine whether it is within the range of the dimension specified by the array or character variable declaration.

Specify BOUNDS to request array bounds and substring checking. With the default, NOBOUNDS, array bounds and substring checking does not occur.

2–42 Compiling HP Fortran Programs

[NO]FORMAT

Controls whether the run-time message number 61 (FORVARMIS) is displayed and halts program execution when the data type for an item being formatted for output does not match the format descriptor being used (such as a REAL data item with an I format).

The default, FORMAT, causes FORVARMIS to be a fatal error and halts program execution.

Specifying NOFORMAT ignores the format mismatch, which suppresses the

FORVARMIS error and allows program continuation.

If you omit /NOVMS and omit /CHECK=NOFORMAT, the default is

/CHECK=FORMAT.

If you specify /NOVMS, the default is NOFORMAT (unless you also specify

/CHECK=FORMAT).

[NO]FP_EXCEPTIONS

Controls whether run-time checking counts calculations that result in exceptional values. With the default, NOFP_EXCEPTIONS, no run-time messages are reported.

Specifying FP_EXCEPTIONS requests reporting of the first two occurrences of each type of exceptional value and a summary run-time message at program completion that displays the number of times exceptional values occurred.

Consider using FP_EXCEPTIONS when the /IEEE_MODE qualifier allows generation of exceptional values.

To limit reporting to only denormalized numbers (and not other exceptional numbers), specify UNDERFLOW instead of FP_EXCEPTIONS.

Using FP_EXCEPTIONS applies to all types of native floating-point data.

[NO]FP_MODE (I64 only)

Controls whether run-time checking of the current state of the processor’s floating-point status register (FPSR) occurs. For every call of every function or subroutine, the check will compare the current state of the FPSR register against the expected state. That state is based on the /FLOAT, /IEEE_MODE and /ROUND qualifier values specified by the FORTRAN command. An informational message is issued at run time for miscompares.

With the default, NOFP_MODE, no check is made.

Compiling HP Fortran Programs 2–43

[NO]OUTPUT_CONVERSION

Controls whether run-time message number 63 (OUTCONERR) is displayed when format truncation occurs. Specifying /CHECK=NOOUTPUT_

CONVERSION disables the run-time message (number 63) associated with format truncation. The data item is printed with asterisks. When OUTPUT_

CONVERSION is in effect and a number could not be output in the specified format field length without loss of significant digits (format truncation), the

OUTCONERR (number 63) error occurs.

If you omit /NOVMS and omit /CHECK=NOOUTPUT_CONVERSION, the default is OUTPUT_CONVERSION.

If you specify /NOVMS, the default is NOOUTPUT_CONVERSION (unless you also specify /CHECK=OUTPUT_CONVERSION).

[NO]OVERFLOW

Controls whether run-time checking occurs for arithmetic overflow of all integer calculations (INTEGER, INTEGER with a kind parameter, or INTEGER with a length specifier). Specify OVERFLOW to request integer overflow checking.

Real and complex calculations are always checked for overflow and are not affected by /NOCHECK. Integer exponentiation is performed by a routine in the mathematical library. The routine in the mathematical library always checks for overflow, even if NOOVERFLOW is specified.

With the default, NOOVERFLOW, overflow checking does not occur.

[NO]POWER

Specifying the /CHECK=NOPOWER qualifier allows certain arithmetic expressions containing floating-point numbers and exponentiation to be evaluated and return a result rather than cause the compiler to display a run-time message and stop the program. The specific arithmetic expressions include:

• 0.0 ** 0.0

• negative-value ** integer-value-of-type-real

For example, if you specify /CHECK=NOPOWER the calculation of the expression 0.0 ** 0.0 results in 1. The expression (–3.0) ** 3.0 results in –27.0.

If you omit /CHECK=NOPOWER for such expressions, an exception occurs, error message number 65 is displayed, and the program stops (default is

/CHECK=POWER).

2–44 Compiling HP Fortran Programs

[NO]UNDERFLOW

Controls whether run-time messages are displayed for floating underflow (denormalized numbers) in floating-point calculations. Specifying UNDERFLOW might be used in combination with the /IEEE_MODE=DENORM_RESULTS qualifier. Specify UNDERFLOW to request reporting of the first two occurrences of denormalized numbers and a summary run-time message at program completion that displays the number of times denormalized numbers occurred.

The default, NOUNDERFLOW, means that floating underflow messages are not displayed. To check for all exceptional values (not just denormalized numbers), specify /CHECK=FP_EXCEPTIONS.

ALL

Requests that all run-time checks (BOUNDS, FORMAT, FP_EXCEPTIONS,

OUTPUT_CON2VERSION, OVERFLOW, and UNDERFLOW) be performed.

Specifying /CHECK and /CHECK=ALL are equivalent.

NONE

Requests no run-time checking. This is the default. Specifying /NOCHECK and /CHECK=NONE are equivalent.

For More Information:

• On exceptional floating-point values, see Section 8.4.8.

• On controlling IEEE arithmetic exception handling (/IEEE_MODE qualifier), see Section 2.3.24.

• On the ranges of the various data types (including denormalized ranges), see Chapter 8.

2.3.12 /CONVERT — Unformatted Numeric Data Conversion

The /CONVERT qualifier specifies the format of numeric unformatted data in a file, such as IEEE little endian, VAX G_float, VAX D_float floating-point format, or a nonnative big endian format.

By default, an unformatted file containing numeric data is expected to be in the same floating-point format used for memory representation or

/CONVERT=NATIVE. You set the floating-point format used for memory representation using the /FLOAT qualifier (see Section 2.3.22).

Instead of specifying the unformatted file format by using the /CONVERT qualifier, you can use one of the other methods (predefined logical names or the OPEN CONVERT keyword) described in Chapter 9, which allow the same program to use different floating-point formats, as shown in Figure 2–1.

Compiling HP Fortran Programs 2–45

The qualifier has the following form (specify one keyword):

BIG_ENDIAN

CRAY

FDX

FGX

/CONVERT= IBM

LITTLE_ENDIAN

NATIVE

VAXD

VAXG

BIG_ENDIAN

Specifies that unformatted files containing numeric data are in IEEE big endian (nonnative) format.

If you specify BIG_ENDIAN, the resulting program will read and write unformatted files containing numeric data assuming:

• Big endian integer format (INTEGER declarations of the appropriate size)

• Big endian IEEE floating-point formats (REAL and COMPLEX declarations of the appropriate size).

CRAY

Specifies that unformatted files containing numeric data are in CRAY

(nonnative) big endian format.

If you specify CRAY, the resulting program will read and write unformatted files containing numeric data assuming:

• Big endian integer format (INTEGER declarations of the appropriate size)

• Big endian CRAY proprietary floating-point formats (REAL and COMPLEX declarations of the appropriate size)

FDX

Specifies that unformatted files containing numeric data are in I64/Alphacompatible D_float-centered little endian format, as follows:

• REAL (KIND=4) and COMPLEX (KIND=4) (same as REAL*4 and

COMPLEX*8) single-precision data is in VAX little endian F_float format.

• REAL (KIND=8) and COMPLEX (KIND=8) (same as REAL*8 and

COMPLEX*16) double-precision data is in VAX little endian D_float format.

2–46 Compiling HP Fortran Programs

• REAL (KIND=16) (same as REAL*16) data is in IEEE-style little endian

X_float format.

FGX

Specifies that unformatted files containing numeric data are in I64/Alphacompatible G_float-centered little endian format, as follows:

• REAL (KIND=4) and COMPLEX (KIND=4) (same as REAL*4 and

COMPLEX*8) single-precision data is in VAX little endian F_float format.

• REAL (KIND=8) and COMPLEX (KIND=8) (same as REAL*8 and

COMPLEX*16) double-precision data is in VAX little endian G_float format.

• REAL (KIND=16) (same as REAL*16) data is in IEEE-style little endian

X_float format.

IBM

Specifies that unformatted files containing numeric data are in IBM®

(nonnative) big endian format (such as IBM System\ 370 and similar systems).

If you specify IBM, the resulting program will read and write unformatted files containing numeric data assuming:

• Big endian integer format (INTEGER declarations of the appropriate size)

• Big endian IBM proprietary floating-point formats (REAL and COMPLEX declarations of the appropriate size)

LITTLE_ENDIAN

Specifies that unformatted files containing numeric data are in native little endian integer format and IEEE little endian floating-point format, as follows:

• Integer data is in native little endian format.

• REAL (KIND=4) and COMPLEX (KIND=4) (same as REAL*4 and

COMPLEX*8) single-precision data is in IEEE little endian S_float format.

• REAL (KIND=8) and COMPLEX (KIND=8) (same as DOUBLE

PRECISION and DOUBLE COMPLEX) double-precision data is in IEEE little endian T_float format.

• REAL (KIND=16) data is in IEEE-style little endian X_float format.

NATIVE

Specifies that the format for unformatted files containing numeric data is not converted. When using NATIVE (the default), the numeric format in the unformatted files must match the floating-point format representation in memory, which is specified using the /FLOAT qualifier.

Compiling HP Fortran Programs 2–47

This is the default.

VAXD

Specifies that unformatted files containing numeric data are in VAX-compatible

D_float-centered little endian format, as follows:

• Integer data is in native little endian format.

• REAL (KIND=4) and COMPLEX (KIND=4) (same as REAL*4 and

COMPLEX*8) single-precision data is in VAX F_float floating-point format.

• REAL (KIND=8) and COMPLEX (KIND=8) (same as REAL*8 and

COMPLEX*16) double-precision data is in VAX D_float little endian format.

• REAL (KIND=16) (same as REAL*16) data is in VAX H_float little endian format.

VAXG

Specifies that unformatted files containing numeric data are in VAX-compatible

G_float-centered little endian format, as follows:

• Integer data is in native little endian format.

• REAL (KIND=4) and COMPLEX (KIND=4) (same as REAL*4 and

COMPLEX*8) single-precision data is in VAX F_float floating-point format.

• REAL (KIND=8) and COMPLEX (KIND=8) (same as REAL*8 and

COMPLEX*16) double-precision data is in VAX G_float little endian format.

• REAL (KIND=16) (same as REAL*16) data is in VAX H_float little endian format.

For More Information:

• On limitations of data conversion, see Section 9.4.

• On converting unformatted data files, including using the OPEN statement

CONVERT specifier and using FOR$CONVERTnnn logical names, see

Section 9.5.

• On the ranges and formats of the various native intrinsic floating-point data types, see Section 8.4.

• On porting Compaq Fortran 77 data from OpenVMS VAX systems, see

Section B.7.

• On the ranges of the nonnative VAX H_float data type, see Section B.8.

2–48 Compiling HP Fortran Programs

2.3.13 /D_LINES — Debugging Statement Indicator, Column 1

Specify /D_LINES to request that the compiler should treat lines in fixed-form source files that contain a D in column 1 as source code rather than comment lines. Such lines might print the values of variables or otherwise provide useful debugging information. This qualifier is ignored for free-form source files.

The default is /NOD_LINES, which means that lines with a D in column 1 are treated as comments.

2.3.14 /DEBUG — Object File Traceback and Symbol Table

The /DEBUG qualifier requests that the object module contain information for use by the OpenVMS Debugger and the run-time error traceback mechanism.

The qualifier has the following form:

/DEBUG=

6 n

[NO]SYMBOLS

[NO]TRACEBACK o

[, ...]

NONE

ALL

[NO]SYMBOLS

Controls whether the compiler provides the debugger with local symbol definitions for user-defined variables, arrays (including dimension information), structures, parameter constants, and labels of executable statements.

[NO]TRACEBACK

Controls whether the compiler provides an address correlation table so that the debugger and the run-time error traceback mechanism can translate virtual addresses into source program routine names and compiler-generated line numbers.

ALL

Requests that the compiler provide both local symbol definitions and an address correlation table. If you specify /DEBUG without any keywords, it is the same as /DEBUG=ALL or /DEBUG=(TRACEBACK,SYMBOLS). When you specify /DEBUG, also specify /NOOPTIMIZE to prevent optimizations that complicate debugging.

Compiling HP Fortran Programs 2–49

NONE

Requests that the compiler provide no debugging information. The

/NODEBUG, /DEBUG=NONE, and /DEBUG=(NOTRACEBACK, NOSYMBOLS) qualifiers are equivalent.

If you omit /DEBUG, the default is /DEBUG=(TRACEBACK, NOSYMBOLS).

Note

The use of /NOOPTIMIZE is strongly recommended when the /DEBUG qualifier is used. Optimizations performed by the compiler can cause several different kinds of unexpected behavior when using the OpenVMS Debugger.

For More Information:

• On using the OpenVMS Debugger, see Chapter 4.

• On debugging qualifiers for the FORTRAN and LINK commands, see

Section 4.2.1.

• On LINK command qualifiers related to traceback and debugging, see

Section 3.2.2 and Table 3–2.

2.3.15 /DIAGNOSTICS — Create Diagnostics File

The /DIAGNOSTICS qualifier creates a file containing compiler messages and diagnostic information.

The qualifier has the following form:

/DIAGNOSTICS[=file-spec]

The default is /NODIAGNOSTICS.

If you omit the file specification, the diagnostics file has the name of your source file and a file type of DIA.

The diagnostics file is reserved for use with third-party layered products such as, but not limited to, the Language Sensitive Editor (LSE).

For More Information:

On using LSE, see the Guide to Source Code Analyzer for VMS Systems or online LSE HELP.

2–50 Compiling HP Fortran Programs

2.3.16 /DML — Invoke Fortran DML Preprocessor

The /DML qualifier invokes the Fortran Data Manipulation Language (DML) preprocessor before the compiler. The preprocessor produces an intermediate file of HP Fortran source code in which Fortran DML commands are expanded into HP Fortran statements. The compiler is then automatically invoked to compile this intermediate file.

The qualifier has the following form:

/DML

The default is not to invoke the Fortran DML preprocessor.

Use the /SHOW=PREPROCESSOR qualifier in conjunction with the /DML qualifier to cause the preprocessor-generated source code to be included in the listing file.

Any switches preceding the /DML qualifier in the command line are ignored.

Note

Unless you specify the /DEBUG qualifier, the intermediate file is deleted by the Fortran DML preprocessor immediately after compilation is complete, and the Language Sensitive Editor and the Source Code Analyzer cannot access the source program when you use the /DML qualifier. The results with the /DEBUG qualifier reflect the intermediate source.

For More Information:

On the DML preprocessor, see the Oracle CODASYL DBMS Programming

Reference Manual.

2.3.17 /DOUBLE_SIZE — DOUBLE PRECISION Data Size

The /DOUBLE_SIZE qualifier allows you to specify the data size for floatingpoint DOUBLE PRECISION data declarations. The qualifier has the following form: n o

/DOUBLE_SIZE=

128

To request that all DOUBLE PRECISION declarations, constants, functions, and intrinsics use the REAL (KIND=16) extended-precision data rather than

REAL (KIND=8) double-precision data, specify /DOUBLE_SIZE=128. REAL

(KIND=16) data is stored in memory using X_float format.

Compiling HP Fortran Programs 2–51

If you omit /DOUBLE_SIZE=128, the size of DOUBLE PRECISION declarations is REAL (KIND=8) or 64-bit double-precision data (default is

/DOUBLE_SIZE=64). To select the floating-point format used in memory for

64-bit REAL (KIND=8) data, use the /FLOAT qualifier.

For More Information:

On the /FLOAT qualifier, see Section 2.3.22.

2.3.18 /ERROR_LIMIT — Limit Compiler Messages

The /ERROR_LIMIT qualifier specifies the maximum number of error-level or fatal-level compiler errors allowed for a given compilation unit (one or more files specified on the FORTRAN command line that create a single object file).

The qualifier has the following form:

/ERROR_LIMIT[=nn] or /NOERROR_LIMIT

If you specify /ERROR_LIMIT=n, the compilation can have up to n - 1 errors without terminating the compilation. When the error limit is reached, compilation is terminated.

If you specify /NOERROR_LIMIT, there is no limit on the number of errors that are allowed.

By default, execution of the compiler is terminated when 30 error (E-level) and fatal (F-level) messages are detected (default is /ERROR_LIMIT=30).

When the error limit is surpassed, only compilation of the current commalist element is terminated; the compiler will proceed to compile any other comma-list element. For example, consider the following:

$ FORTRAN A,B,C

If comma-list element A has more than 30 E- or F-level errors, its compilation is terminated, but the compiler proceeds to compile elements B and C.

A list of files separated by plus signs ( + ) form a single compilation unit. In the following example, compilation of the plus-sign separated files A, B, or C stops when the total of E- or F-level errors for all three files exceeds 30:

$ FORTRAN A+B+C

Specifying /ERROR_LIMIT=0 is equivalent to specifying /ERROR_LIMIT=1

(compilation terminates when the first error-level or fatal-level error occurs).

For More Information:

On compiler diagnostic messages, see Section 2.6.

2–52 Compiling HP Fortran Programs

2.3.19 /EXTEND_SOURCE — Line Length for Fixed-Form Source

Specify /EXTEND_SOURCE to request that the compiler increase the length of

HP Fortran statement fields to column 132 for fixed-form source files, instead of column 72 (the default). It is ignored for free-form source files.

You can also specify this qualifier by using the OPTIONS statement. The default in either case is /NOEXTEND_SOURCE.

To request warning messages for truncated fixed-form source lines, specify

/WARNINGS=TRUNCATED_SOURCE.

For More Information:

• On recognized file name suffix characters and their relationship to fixed and free source formats, see Section 2.2.1.

• On column positions and more complete information on the fixed and free source formats, see the HP Fortran for OpenVMS Language Reference

Manual.

• On /WARNINGS=TRUNCATED_SOURCE, see Section 2.3.51.

2.3.20 /F77 — FORTRAN IV or FORTRAN-77 Compatibility

The /F77 qualifier requests that the compiler use FORTRAN-77 (and thus

Fortran 90/95) interpretation rules for those statements that have different meanings in older versions of the Fortran standards. The default is /F77.

If you specify /NOF77, the compiler uses the FORTRAN 66 (FORTRAN IV) interpretation. This means, among other things, that:

• DO loops are always executed at least once FORTRAN-66 EXTERNAL statement syntax and semantics are allowed.

• If the OPEN statement STATUS specifier is omitted, the default changes to

STATUS=’NEW’ instead of STATUS=’UNKNOWN’.

• If the OPEN statement BLANK specifier is omitted, the default changes to

BLANK=’ZERO’ instead of BLANK=’NULL’.

2.3.21 /FAST — Request Fast Run-Time Performance

Specifying /FAST changes the defaults for certain qualifiers, usually improving run-time performance. The new defaults are:

• /ALIGNMENT=(COMMONS=NATURAL,RECORDS=NATURAL,SEQUENCE)

(same as /ALIGNMENT=NATURAL) (see Section 2.3.3)

• /ARCHITECTURE=HOST (see Section 2.3.6)

• /ASSUME=NOACCURACY_SENSITIVE (see Section 2.3.7)

Compiling HP Fortran Programs 2–53

• /MATH_LIBRARY=FAST (Alpha only) (see Section 2.3.30)

• /OPTIMIZE=TUNE=HOST (Alpha only) (see Section 2.3.35)

2.3.22 /FLOAT — Specify Floating-Point Format in Memory

The /FLOAT qualifier specifies the floating-point data format to be used in memory for REAL or COMPLEX data. For performance reasons, consider specifying the same floating-point memory format as the floating-point format used by unformatted files the program will access if the data falls within the acceptable range.

Figure 2–1 shows the FORTRAN command qualifiers used to specify the floating-point format used in memory and in an unformatted file. Because

REAL (KIND=16) (same as REAL*16) data is always in X_float format on

OpenVMS I64 and Alpha systems, the /FLOAT keyword specifies the format for REAL (KIND=4), COMPLEX (KIND=4), REAL (KIND=8), and COMPLEX

(KIND=8) data (or equivalent declarations).

Figure 2–1 Specifying the Format of Numeric Data for Unformatted Files

Memory

/FLOAT = specifies format in memory

/CONVERT qualifier, OPTIONS statement, logical name, or OPEN CONVERT keyword specifies format in unformatted file

Unformatted File

ZK−5297A−GE

To specify the floating-point format (such as big endian) for all unformatted

files opened by the program, use the /CONVERT qualifier. To allow the same program to use different floating-point formats, you must use the predefined logical names or the OPEN CONVERT keyword to specify the format for specific unit numbers, as described in Chapter 9.

2–54 Compiling HP Fortran Programs

The qualifier has the following form:

(

D_FLOAT

)

/FLOAT= G_FLOAT

IEEE_FLOAT

Note

The OpenVMS Alpha instruction set does not support D_float computations, and the OpenVMS I64 instruction set does not support

D_float, F_float or G_float computations. As a result, any data stored in those formats is converted to a native format for arithmetic computations and then converted back to its original format. On

Alpha systems, the native format used for D_float is G_float. On I64 systems, S_float is used for F_float data, and T_float is used for D_float and G_float data.

This means that for programs that perform many floating-point computations, using D_float data on Alpha systems is slower than using G_float or T_float data. Similarly, using D_float, F_float, or

G_float data on I64 systems is slower than using S_float or T_float data. Additionally, due to the conversions involved, the results might differ from native VAX D_float, F_float, and G_float computations and results.

You should not mix floating data type formats in routines that pass singleprecision or double-precision quantities among themselves.

D_FLOAT

Specifies that the memory format for REAL (KIND=4) and COMPLEX

(KIND=4) data is VAX F_float and that the memory format for REAL (KIND=8) and COMPLEX (KIND=8) data is VAX D_float. Same as the obsolete qualifier

/NOG_FLOATING.

Due to the considerations noted above, we do not recommend use of the

/FLOAT=D_FLOAT qualifier unless a program must use unformatted data files in D_float format. If range and accuracy constraints permit the use of the other REAL (KIND=8) data types, consider converting existing unformatted files that contain D_float data to another format, such as G_float on Alpha systems, or T_float on Alpha or I64 systems (see Chapter 9).

Compiling HP Fortran Programs 2–55

G_FLOAT

Specifies that the memory format for single precision REAL (KIND=4) and

COMPLEX (KIND=4) data is VAX F_float and that the memory format for double precision REAL (KIND=8) and COMPLEX (KIND=8) data is VAX G_ float. Same as the obsolete qualifier /G_FLOATING.

The default on Alpha systems is /FLOAT=G_FLOAT.

Due to the considerations noted above, on I64 systems we do not recommend use of the /FLOAT=G_FLOAT qualifier unless a program must use unformatted data files in G_float format. If range and accuracy constraints permit it, consider converting existing unformatted files that contain G_float data to

T_float (see Chapter 9).

IEEE_FLOAT

Specifies that the memory format for single precision REAL (KIND=4) and

COMPLEX (KIND=4) data is IEEE S_float and the memory format for double precision REAL (KIND=8) and COMPLEX (KIND=8) is IEEE T_float.

The default on I64 systems is /FLOAT=IEEE_FLOAT. If possible, this default should be used, because it provides the greatest performance and accuracy on

I64.

Specifying /FLOAT=IEEE_FLOAT allows the use of certain IEEE exceptional values. When you specify /FLOAT=IEEE_FLOAT, you should be aware of the /CHECK=FP_EXCEPTIONS, /CHECK=FP_MODE, /IEEE_MODE, and

/ROUNDING_MODE qualifiers.

Because REAL (KIND=16) (same as REAL*16) and COMPLEX (KIND=16)

(same as COMPLEX*32) data is always in X_float format on I64 and Alpha systems, operations that use REAL (KIND=16) and COMPLEX (KIND=16) data may encounter certain exceptional values even when /FLOAT=IEEE_

FLOAT is not used.

For More Information:

• On intrinsic floating-point data types, see Chapter 8.

• On converting unformatted files, see Section 2.3.12.

• On qualifiers of interest when you specify /FLOAT=IEEE_FLOAT, see:

Section 2.3.11 (/CHECK=FP_EXCEPTIONS)

Section 2.3.11 (/CHECK=FP_MODE) (I64 only)

Section 2.3.24 (/IEEE_MODE)

Section 2.3.40 (/ROUNDING_MODE)

2–56 Compiling HP Fortran Programs

2.3.23 /GRANULARITY — Control Shared Memory Access to Data

The /GRANULARITY qualifier controls the size of data that can be safely accessed from different threads. You do not need to specify this option for local data access by a single process, unless asynchronous write access from outside the user process might occur. The default is /GRANULARITY=QUADWORD.

The qualifier has the following form:

(

BYTE

)

/GRANULARITY= LONGWORD

QUADWORD

Data that can be written from multiple threads must be declared as VOLATILE

(so it is not held in registers). To ensure alignment in common blocks, derived types, and record structures, use the /ALIGNMENT qualifier.

BYTE

Requests that all data (one byte or greater) can be accessed from different threads sharing data in memory. This option will slow run-time performance.

LONGWORD

Ensures that naturally aligned data of four bytes or greater can be accessed safely from different threads sharing access to that data in memory. Accessing data items of three bytes or less and unaligned data may result in data items written from multiple threads being inconsistently updated.

QUADWORD

Ensures that naturally aligned data of eight bytes can be accessed safely from different threads sharing data in memory. Accessing data items of seven bytes or less and unaligned data may result in data items written from multiple threads being inconsistently updated. This is the default.

For More Information:

• On the Itanium architecture, see the Intel Itanium Architecture Software

Developer’s Manual, Volume 1: Application Architecture.

• On the Alpha architecture, see the Alpha Architecture Reference Manual.

• On intrinsic data types, see Chapter 8.

Compiling HP Fortran Programs 2–57

2.3.24 /IEEE_MODE — Control IEEE Arithmetic Exception Handling

The /IEEE_MODE qualifier specifies the arithmetic exception handling used for floating-point calculations, such as for exceptional values. On Alpha systems, it also controls the precision of exception reporting (like /SYNCHRONOUS_

EXCEPTIONS (Alpha only)).

Exceptional values are associated with IEEE arithmetic and include Infinity

(+ and -) values, Not-A-Number (NaN) values, invalid data values, and denormalized numbers (see Section 8.4.8).

Use the /IEEE_MODE qualifier to control:

• Whether exceptional values cause program termination or continuation

• Whether exception reporting is precise

• Whether underflow (denormalized) values are set to zero

This qualifier only applies to arithmetic calculations when:

• You omit the /MATH_LIBRARY=FAST (Alpha only) qualifier (or /FAST) qualifier. On Alpha systems, using /MATH_LIBRARY=FAST provides limited handling of exceptional values of arguments to and results from HP

Fortran intrinsic functions.

• You specify the /FLOAT=IEEE_FLOAT qualifier to request IEEE S_float

(KIND=4) and T_float (KIND=8) data.

If you specify /FLOAT=G_FLOAT (the default) or /FLOAT=D_FLOAT,

/IEEE_MODE must not also be specified.

The qualifier has the following form:

(

FAST

/IEEE_MODE= UNDERFLOW_TO_ZERO

DENORM_RESULTS

)

The default on I64 systems is /IEEE_MODE=DENORM_RESULTS.

The default on Alpha systems is /IEEE_MODE=FAST.

Note

You should choose the value for the /IEEE_MODE qualifier based on the floating-point semantics your application requires, not on possible performance benefits.

2–58 Compiling HP Fortran Programs

FAST

Specifies that the program should stop if any exceptional values are detected.

This is the default.

When the program encounters or calculates any exceptional values (infinity (+ or –), NaN, or invalid data) in a calculation, the program stops and displays a message.

Denormalized values calculated in an arithmetic expression are set to zero.

Denormalized values encountered as variables in an arithmetic expression

(including constant values) are treated as invalid data (an exceptional value), which stops the program.

On Alpha systems, exceptions are not reported until one or more instructions after the instruction that caused the exception. To have exceptions reported at the instruction that caused the exception when using /IEEE_MODE=FAST, also specify /SYNCHRONOUS_EXCEPTIONS (Alpha only).

UNDERFLOW_TO_ZERO

Specifies that the program should continue if any exceptional values are detected and set calculated denormalized (underflow) values to zero.

When the program encounters an exceptional value (infinity (+ or –), NaN, invalid data) in an arithmetic expression, the program continues. It also continues when the result of a calculation is an exceptional value.

Calculated denormalized values are set to zero ( 0 ). This prevents the denormalized number from being used in a subsequent calculation

(propagated).

Exceptions are reported at the instruction that caused the exception (same as

/SYNCHRONOUS_EXCEPTIONS (Alpha only)). This allows precise run-time reporting of exceptions for those programs that generate exceptional values, but this slows program run-time performance.

Using UNDERFLOW_TO_ZERO allows programs to handle exceptional values, but does not propagate numbers in the denormalized range.

To request run-time messages for arithmetic exceptions, specify the

/CHECK=FP_EXCEPTIONS qualifier.

DENORM_RESULTS

Specifies that the program should continue if any exceptional values are detected and leave calculated denormalized values as is (allows underflow).

Compiling HP Fortran Programs 2–59

Calculated denormalized values are left as denormalized values. When a denormalized number is used in a subsequent arithmetic expression, it requires extra software-assisted handling and slows performance. A program that generates denormalized numbers will be slower than the same program compiled using /IEEE_MODE=UNDERFLOW_TO_ZERO.

Exceptions are reported at the instruction that caused the exception (same as

/SYNCHRONOUS_EXCEPTIONS (Alpha only)). This allows precise run-time reporting of exceptions for those programs that generate exceptional values, but this slows program run-time performance.

Using DENORM_RESULTS allows programs to handle exceptional values, including allowing underflow of denormalized numbers.

To request run-time messages for arithmetic exceptions, specify the

/CHECK=FP_EXCEPTIONS qualifier. To request run-time messages for only those arithmetic exceptions related to denormalized numbers, specify the

/CHECK=UNDERFLOW qualifier.

For More Information:

• On exceptional floating-point values, see Section 8.4.8.

• On controlling run-time arithmetic exception messages (/CHECK=(FP_

EXCEPTIONS,UNDERFLOW) qualifier), see Section 2.3.11.

• On the ranges of the various data types (including denormalized ranges), see Chapter 8.

• On IEEE floating-point exception handling, see the IEEE Standard for

Binary Floating-Point Arithmetic (ANSI/IEEE Standard 754-1985).

• On the Itanium architecture, see the Intel Itanium Architecture Software

Developer’s Manual, Volume 1: Application Architecture.

2.3.25 /INCLUDE — Add Directory for INCLUDE and Module File Search

The /INCLUDE qualifier specifies one or more additional directories for the HP

Fortran compiler to search for:

• Module files (specified by a USE statement)

Module files have a file type of F90$MOD and are created by the HP

Fortran compiler. For more information on module files, see Section 2.2.3.

• Include files (specified by an INCLUDE statement)

Include files have a file type like other HP Fortran source files (F90, FOR, or F) and are usually created by the user with a text editor.

2–60 Compiling HP Fortran Programs

HP Fortran also provides certain include library modules in the text library

FORSYSDEF.TLB. Users can create a text library and then populate and maintain include library modules in the library. For more information on include files and include text library modules, see Section 2.2.4.

If the INCLUDE statement specifies an explicit device and/or directory, only that directory is searched.

If you omit /INCLUDE, the compiler searches in the current directory for module files and either the current directory or the directory containing the source file specified on the FORTRAN command line for include files or text libraries:

• If you omit /ASSUME=SOURCE_INCLUDE, only the current default directory is searched.

• If you specify /ASSUME=SOURCE_INCLUDE, the directory where the source file resides is searched instead of the current directory.

The order of directory searching follows:

The current directory (omit /ASSUME=SOURCE_INCLUDE) or the directory where the source file resides (specify /ASSUME=SOURCE_

INCLUDE).

One or more directories specified by the /INCLUDE qualifier.

The location defined by the logical name FORT$INCLUDE (if defined). To prevent searching in this directory, specify /NOINCLUDE.

If you do not specify /INCLUDE or /NOINCLUDE, the compiler searches first in the current directory (or directory where the source file resides) and then the directory specified by FORT$INCLUDE (if defined).

To request that the compiler only search in the current directory (or directory where the source file resides), specify /NOINCLUDE. This prevents the compiler from searching the FORT$INCLUDE directory. If you use

/NOINCLUDE, you cannot specify /INCLUDE.

To request that the compiler only search in the directory specified by

FORT$INCLUDE, specify /INCLUDE=FORT$INCLUDE.

To control the searching for text libraries (not included files or modules), you can also use the logical name FORT$LIBRARY.

Like other OpenVMS logical names, it can specify the location for your process only or for multiple processes (including system-wide).

Compiling HP Fortran Programs 2–61

To specify the additional directories DISKA:[PROJ_MODULE.F90] and

DISKB:[F_COMMON.F90] with the /INCLUDE qualifier, use a single

/INCLUDE qualifier, as follows:

$ FORTRAN PROJ_M.F90 /INCLUDE=(DISKA:[PROJ_MODULE.F90],DISKB:[F_COMMON.F90])

If you specify multiple directories, the order of the directories (and their devices) in the /INCLUDE qualifier determines the directory search order.

For More Information:

• On the /ASSUME=SOURCE_INCLUDE qualifier, see Section 2.3.7.

• On using library modules in a text library, see Section 2.2.4 and

Section 2.3.27.

• On OpenVMS logical names, see the OpenVMS User’s Manual.

2.3.26 /INTEGER_SIZE — Integer and Logical Data Size

The /INTEGER_SIZE qualifier controls how the compiler interprets INTEGER or LOGICAL declarations that do not have a specified length. The default is

INTEGER_SIZE=32.

The qualifier has the following form:

(

)

/INTEGER_SIZE= 32

Indicates that INTEGER declarations are interpreted as INTEGER (KIND=2) and LOGICAL declarations as LOGICAL (KIND=2). Same as the obsolete

/NOI4 qualifier.

Indicates that INTEGER declarations are interpreted as INTEGER (KIND=4) and LOGICAL declarations as LOGICAL (KIND=4). Same as the obsolete /I4 qualifier.

Indicates that INTEGER declarations are interpreted as INTEGER (KIND=8) and LOGICAL declarations as LOGICAL (KIND=8)

For performance reasons, use INTEGER (KIND=4) data instead of INTEGER

(KIND=2) or INTEGER (KIND=1) and whenever possible. You must explicitly declare INTEGER (KIND=1) data.

2–62 Compiling HP Fortran Programs

Note

To improve performance, use /INTEGER_SIZE=32 rather than

/INTEGER_SIZE=16 and declare variables as INTEGER (KIND=4) (or

INTEGER (KIND=8)) rather than INTEGER (KIND=2) or INTEGER

(KIND=1). For logical data, avoid using /INTEGER_SIZE=16 and declare logical variables as LOGICAL (KIND=4) rather than LOGICAL

(KIND=2) or LOGICAL (KIND=1).

For More Information:

• On intrinsic data types and their ranges, see Chapter 8.

• On run-time integer overflow checking (/CHECK=OVERFLOW), see

Section 2.3.11.

2.3.27 /LIBRARY — Specify File as Text Library

The /LIBRARY qualifier specifies that a file is a text library file.

The qualifier has the following form:

text-library-file/LIBRARY

The /LIBRARY qualifier can be specified on one or more text library files in a list of files concatenated by plus signs ( + ). At least one of the files in the list must be a nonlibrary file. The default file type is TLB.

For More Information:

• On the use of text libraries, see Section 2.4.

• On the OpenVMS Librarian, see the OpenVMS Librarian Utility Manual or enter HELP LIBRARY.

2.3.28 /LIST — Request Listing File

The /LIST qualifier requests a source listing file. You can request additional listing information using the /MACHINE_CODE and /SHOW qualifiers.

The qualifier has the following form:

/LIST[=file-spec]

You can include a file specification for the listing file. If you omit the file specification, the listing file has the name of the first source file and a file type of LIS.

Compiling HP Fortran Programs 2–63

The default depth of a page in a listing file is 66 lines. To modify the default, assign the new number to the logical name SYS$LP_LINES, using the DCL command DEFINE. For example, the following DCL command sets the page depth at 88 lines:

$ DEFINE SYS$LP_LINES 88

The valid number of lines per page ranges from 30 to a maximum of 255.

The definition can be applied to the entire system by using the command

DEFINE/SYSTEM.

In interactive mode, the compiler does not produce a listing file unless you include the /LIST qualifier. In batch mode, the compiler produces a listing file by default. In either case, the listing file is not automatically printed; you must use the PRINT command to obtain a line printer copy of the listing file.

If a source line of length 1 contains a form-feed character, the source code listing begins a new page with the following line; the line containing the form-feed does not appear.

If a source line of length greater than 1 contains a form-feed character, that line is printed but the form-feed character is ignored (does not generate a new page).

Any other nonprinting ASCII characters encountered in HP Fortran source files are replaced by a space character, and a warning message appears.

You can request additional information in the listing file using the /MACHINE_

CODE and /SHOW qualifiers.

The listing file includes the HP Fortran version number.

The /ANNOTATIONS qualifier controls whether an annotated listing showing optimizations is included with the listing file.

For More Information:

• On the format of listing files, see Section 2.7.1.

• On the /MACHINE_CODE qualifier, see Section 2.3.29.

• On the /SHOW qualifier, see Section 2.3.43.

• On the /ANNOTATIONS qualifier, see Section 2.3.5

2–64 Compiling HP Fortran Programs

2.3.29 /MACHINE_CODE — Request Machine Code in Listing File

Specifying /MACHINE_CODE requests that the listing file include a symbolic representation of the OpenVMS object code generated by the compiler.

Generated code and data are represented in a form similar to an assembly code listing. The code produced by the /MACHINE_CODE qualifier is for informational purposes only. It is not intended to be assembled and is not supported by the MACRO assembler.

If a listing file is not being generated, the /MACHINE_CODE qualifier is ignored.

The default is /NOMACHINE_CODE.

For More Information:

• On the format of a machine code listing, see Section 2.7.2.

• On the /LIST qualifier, see Section 2.3.28.

2.3.30 /MATH_LIBRARY — Fast or Accurate Math Library Routines

(Alpha only)

If you omit /MATH_LIBRARY=FAST (and /FAST), the compiler uses the standard, very accurate math library routines for each HP Fortran intrinsic function, such as SQRT (default is /MATH_LIBRARY=ACCURATE).

Specify /MATH_LIBRARY=FAST to use a special version of certain math library routines that produce faster results, but with a slight loss of precision and less exception checking.

This qualifier applies only to IEEE data types (when you specify

/FLOAT=IEEE_FLOAT). The qualifier has the following form:

/MATH_LIBRARY= n

ACCURATE

FAST o

ACCURATE

On Alpha systems, using /MATH_LIBRARY=ACCURATE (the default if you omit /FAST) produces the very accurate results and error checking expected of quality compiler products. It uses the standard set of math library routines for the applicable intrinsics.

The standard math library routines are designed to obtain very accurate ‘‘near correctly rounded’’ results and provide the robustness needed to check for IEEE exceptional argument values, rather than achieve the fastest possible run-time execution speed. Using /MATH_LIBRARY=ACCURATE allows user control of arithmetic exception handling with the /IEEE_MODE qualifier.

Compiling HP Fortran Programs 2–65

FAST

Specifying /MATH_LIBRARY=FAST (the default if you specify /FAST) use versions of certain math library routines that perform faster computations than the standard, more accurate math library routines, but with slightly less fractional accuracy and less reliable arithmetic exception handling.

Using /MATH_LIBRARY=FAST allows certain math library functions to get significant performance improvements when the applicable intrinsic function is used.

If you specify /MATH_LIBRARY=FAST, the math library routines do not necessarily check for IEEE exceptional values and the /IEEE_MODE qualifier is ignored.

When you use MATH_LIBRARY=FAST, you should carefully check the calculated output from your program. Check the program’s calculated output to verify that it is not relying on the full fractional accuracy of the floating-point data type (see Section 8.4) to produce correct results or producing unexpected exceptional values (exception handling is indeterminate).

Programs that do not produce acceptable results with /MATH_LIBRARY=FAST and single-precision data might produce acceptable results with /MATH_

LIBRARY=FAST if they are modified (or compiled) to use double-precision data.

The specific intrinsic routines that have special fast math routines depend on the version of the OpenVMS operating system in use. Allowed error bounds vary with each routine.

For More Information:

• On controlling arithmetic exception handling, including using the /IEEE_

MODE qualifier, see Section 2.3.24.

• On the /FAST qualifier, see Section 2.3.21.

• On requesting double-precision data during compilation for REAL data declarations (/REAL_SIZE=64 qualifier, see Section 2.3.37.

• On native floating-point formats, see Section 8.4.

• On the specific intrinsic routines that have special fast math routines, see the online release notes.

2–66 Compiling HP Fortran Programs

2.3.31 /MODULE — Placement of Module Files

The /MODULE qualifier controls where module files (.F90$MOD) are placed. If you omit this qualifier or specify /NOMODULE, the .F90$MOD files are placed in your current default directory.

The qualifier has the following form

/MODULE=directory

If you specify this qualifier, .F90$MOD files are placed in the specified directory location.

2.3.32 /NAMES — Control Case of External Names

The /NAMES qualifier specifies how the HP Fortran compiler represents external (global) names to the linker.

The qualifier has the following form:

(

UPPERCASE

)

/NAMES= LOWERCASE

AS_IS

UPPERCASE

Causes the compiler to ignore case differences in identifiers and to convert external names to uppercase. This is the default.

LOWERCASE

Causes the compiler to ignore case differences in identifiers and to convert external names to lowercase.

AS_IS

Causes the compiler to distinguish case differences in identifiers and to preserve the case of external names.

The default, /NAMES=UPPERCASE, means that HP Fortran converts external names to uppercase.

For More Information:

• On the EXTERNAL statement, see the HP Fortran for OpenVMS Language

Reference Manual.

• On specifying case names with the C property, see Section 10.4.2.1.

• On specifying names with the ALIAS property, see Section 10.4.2.2.

Compiling HP Fortran Programs 2–67

2.3.33 /OBJECT — Specify Name or Prevent Object File Creation

The /OBJECT qualifier specifies the name of the object file or prevents object file creation.

The qualifier has the following form:

/OBJECT[=file-spec]

The default is /OBJECT. If you omit the file specification, the object file has the name of the first source file and a file type of OBJ.

Use /NOOBJECT to suppress object code (for example, when you want to test only for compilation errors in the source program).

For More Information:

On using the /OBJECT qualifier, see Section 2.2.5.

2.3.34 /OLD_F77 — Use Old FORTRAN 77 Compiler (Alpha only)

To use the Compaq Fortran 77 compiler, specify /OLD_F77 as the first qualifier on the FORTRAN command line. The default is to use the HP Fortran (90/95 language) compiler. The default HP Fortran compiler supports the FORTRAN

77 language as well as the Fortran 90 and Fortran 95 standards.

If you specify the /OLD_F77 qualifier, certain FORTRAN command qualifiers will be ignored, including qualifiers associated with Fortran 90 and Fortran

95 features, Fortran 90 and 95 standards checking, and certain optimization keywords.

2.3.35 /OPTIMIZE — Specify Compiler Optimizations

The /OPTIMIZE qualifier requests that the compiler produce optimized code.

The qualifier has the following form:

2–68 Compiling HP Fortran Programs

/OPTIMIZE=

LEVEL=n

INLINE=

> NONE

MANUAL

SIZE

SPEED

ALL

NOINLINE

LOOPS

PIPELINE

TUNE=

GENERIC

HOST

EV4

EV5

EV56

PCA6

EV6

EV67

UNROLL=n

;

[, ...]

The default is /OPTIMIZE, which is equivalent to /OPTIMIZE=LEVEL=4. Use

/NOOPTIMIZE or /OPTIMIZE=LEVEL=0 for a debugging session to ensure that the debugger has sufficient information to locate errors in the source program.

In most cases, using /OPTIMIZE will make the program execute faster. As a side effect of getting the fastest execution speeds, using /OPTIMIZE can produce larger object modules and longer compile times than /NOOPTIMIZE.

To allow full interprocedure optimization when compiling multiple source files, consider separating source file specifications with plus signs ( + ), so the files are concatenated and compiled as one program. Full interprocedure optimization can reduce overall program execution time (see Section 5.1.2).

Consider not concatenating source files when the size of the source files is excessively large and the amount of memory or disk space is limited.

The /OPTIMIZE keywords follow:

LEVEL

You can specify the optimization level with /OPTIMIZE=LEVEL=n, where n is from 0 to 5, as follows:

• LEVEL=0 disables nearly all optimizations. Specifying LEVEL=0 causes the /WARNINGS=UNUSED qualifier to be ignored.

This provides the same inlining as /OPTIMIZE=INLINE=NONE.

Compiling HP Fortran Programs 2–69

• LEVEL=1 enables local optimizations within the source program unit, recognition of common subexpressions, and integer multiplication and division expansion (using shifts).

• LEVEL=2 enables global optimizations and optimizations performed with

LEVEL=1. Global optimizations include data-flow analysis, code motion, strength reduction and test replacement, split-lifetime analysis, and instruction scheduling.

This provides the same inlining as /OPTIMIZE=INLINE=MANUAL.

• LEVEL=3 enables additional global optimizations that improve speed (at the cost of extra code size) and optimizations performed with LEVEL=2.

Additional global optimizations include:

Loop unrolling

Code replication to eliminate branches

• LEVEL=4 enables interprocedure analysis, automatic inlining of small procedures (with heuristics limiting the amount of extra code), the software pipelining optimization (also set by /OPTIMIZE=PIPELINE), and optimizations performed with LEVEL=3. LEVEL=4 is the default.

The software pipelining optimization applies instruction scheduling to certain innermost loops, allowing instructions within a loop to ‘‘wrap around’’ and execute in a different iteration of the loop. This can reduce the impact of long-latency operations, resulting in faster loop execution.

Software pipelining also enables the prefetching of data to reduce the impact of cache misses.

For more information on software pipelining, see the PIPELINE keyword in this section.

This provides the same inlining as /OPTIMIZE=INLINE=SPEED.

• LEVEL=5 activates the loop transformation optimizations (also set by

/OPTIMIZE=LOOPS).

• The loop transformation optimizations are a group of optimizations that apply to array references within loops. These optimizations can improve the performance of the memory system and can apply to multiple nested loops.

Loop transformation optimizations include loop blocking, loop distribution, loop fusion, loop interchange, loop scalar replacement, and outer loop unrolling.

2–70 Compiling HP Fortran Programs

To specify loop transformation optimizations without software pipelining, do one of the following:

Specify LEVEL=5 with NOPIPELINE (preferred method)

Specify LOOPS with LEVEL=4, LEVEL=3, or LEVEL=2. This optimization is not performed at optimization levels below

LEVEL=2.

For more information on the loop transformation optimizations, see the

LOOPS keyword in this section.

In addition to loop transformation, specifying LEVEL=5 activates certain optimizations that are not activated by LOOPS and PIPELINE, including byte-vectorization, and insertion of additional NOP (No Operation) instructions for alignment of multi-issue sequences.

To determine whether using LEVEL=5 benefits your particular program, you should time program execution for the same program compiled at

LEVEL=4 and LEVEL=5 (see Section 5.2).

For programs that contain loops that exhaust available registers, longer execution times may result with /OPTIMIZE=LEVEL=5, requiring use of

/OPTIMIZE=UNROLL=n to limit loop unrolling (see the UNROLL keyword in this section).

Specifying LEVEL=5 implies the optimizations performed at LEVEL=1,

LEVEL=2, LEVEL=3, and LEVEL=4.

This provides the same inlining as /OPTIMIZE=INLINE=SPEED.

INLINE

You can specify the level of inlining with /OPTIMIZE=INLINE=xxxxx, where

xxxx is one of the following keywords:

• NONE (same as /OPTIMIZE=NOINLINE) prevents any procedures from being inlined, except statement functions, which are always inlined. This type of inlining occurs if you specify /OPTIMIZE=LEVEL=0, LEVEL=1,

LEVEL=2, or LEVEL=3 and omit /OPTIMIZE=INLINE=keyword.

• MANUAL is the same as NONE for HP Fortran (but not necessarily for other OpenVMS languages). This type of inlining occurs if you specify

/OPTIMIZE=LEVEL=0, LEVEL=1, LEVEL=2, or LEVEL=3 and omit

/OPTIMIZE=INLINE=keyword.

• SIZE inlines procedures that will improve run-time performance without significantly increasing program size. This type of inlining is relevant at

/OPTIMIZE=LEVEL=1 or higher.

Compiling HP Fortran Programs 2–71

• SPEED inlines procedures that will improve run-time performance with a significant increase in program size. This type of inlining is relevant at

/OPTIMIZE=LEVEL=1 or higher. INLINE=SPEED occurs if you specify

/OPTIMIZE=LEVEL=4 or LEVEL=5 and omit /INLINE=keyword.

• ALL inlines every call that can possibly be inlined while generating correct code, including the following:

Statement functions (NONE or MANUAL)

Any procedures that HP Fortran thinks will improve run-time performance (SPEED)

Any other procedures that can possibly be inlined and generate correct code. Certain recursive routines are not inlined to prevent infinite loops.

This type of inlining is relevant at /OPTIMIZE=LEVEL=1 or higher.

NOINLINE

Same as INLINE=NONE.

LOOPS

Specifying /OPTIMIZE=LOOPS (or /OPTIMIZE=LEVEL=5) activates a group of loop transformation optimizations that apply to array references within loops. These optimizations can improve the performance of the memory system and usually apply to multiple nested loops. The loops chosen for loop transformation optimizations are always counted loops (which include DO or

IF loops, but not uncounted DO WHILE loops).

Conditions that typically prevent the loop transformation optimizations from occurring include subprogram references that are not inlined (such as an external function call), complicated exit conditions, and uncounted loops.

The types of optimizations associated with /OPTIMIZE=LOOPS include the following:

• Loop blocking

• Loop distribution

• Loop fusion

• Loop interchange

• Loop scalar replacement

• Outer loop unrolling

2–72 Compiling HP Fortran Programs

The loop transformation optimizations are a subset of optimizations activated by /OPTIMIZE=LEVEL=5. Instead of specifying both LOOPS and PIPELINE, you can specify /OPTIMIZE=LEVEL=5.

To specify loop transformation optimizations without software pipelining, do one of the following:

• Specify LEVEL=5 with NOPIPELINE (preferred method)

• Specify LOOPS with LEVEL=3 or LEVEL=2. This optimization is not performed at optimization levels below LEVEL=2.

To determine whether using /OPTIMIZE=LOOPS benefits your particular program, you should time program execution for the same program (or subprogram) compiled with and without loop transformation optimizations

(such as with /OPTIMIZE=LOOPS and /OPTIMIZE=NOLOOPS).

PIPELINE

Specifying /OPTIMIZE=PIPELINE (or /OPTIMIZE=LEVEL=4) activates the software pipelining optimization. The software pipelining optimization applies instruction scheduling to certain innermost loops, allowing instructions within a loop to "wrap around" and execute in a different iteration of the loop. This can reduce the impact of long-latency operations, resulting in faster loop execution.

For this version of HP Fortran, loops chosen for software pipelining are always innermost loops and do not contain branches, procedure calls, or COMPLEX floating-point data.

On Alpha systems, software pipelining can be more effective when you combine

/OPTIMIZE=PIPELINE with the appropriate /OPTIMIZE=TUNE=xxxx keyword for the target Alpha processor generation (see the TUNE keyword in this section).

Software pipelining also enables the prefetching of data to reduce the impact of cache misses.

Software pipelining is a subset of the optimizations activated by /OPTIMIZE=-

LEVEL=4.

To specify software pipelining without loop transformation optimizations, do one of the following:

• Specify LEVEL=4 with NOLOOPS (preferred method)

• Specify PIPELINE with LEVEL=3 or LEVEL=2. This optimization is not performed at optimization levels below LEVEL=2.

Compiling HP Fortran Programs 2–73

To determine whether using /OPTIMIZE=PIPELINE benefits your particular program, you should time program execution for the same program (or subprogram) compiled with and without software pipelining (such as with

/OPTIMIZE=PIPELINE and /OPTIMIZE=NOPIPELINE).

For programs that contain loops that exhaust available registers, longer execution times may result with /OPTIMIZE=LEVEL=5, requiring use of

/OPTIMIZE=UNROLL=n to limit loop unrolling (see the UNROLL keyword in this section).

TUNE (Alpha only)

You can specify the types of processor-specific instruction tuning for implementations of the Alpha architecture using the /OPTIMIZE=TUNE=xxxx keywords. Regardless of the setting of /OPTIMIZE=TUNE=xxxx you use, the generated code runs correctly on all implementations of the Alpha architecture.

Tuning for a specific implementation can improve run-time performance; it is also possible that code tuned for a specific target may run slower on another target.

The /OPTIMIZE=TUNE=xxxx keywords are as follows:

• GENERIC generates and schedules code that will execute well for all generations of Alpha processor chips. This provides generally efficient code for those cases where both processor generations are likely to be used. If /FAST is specified, the default is HOST; otherwise, the default is

GENERIC.

• HOST generates and schedules code optimized for the processor generation in use on the system being used for compilation.

• EV4 generates and schedules code optimized for the 21064, 21064A, 21066, and 21068 implementations of the Alpha chip.

• EV5 generates and schedules code optimized for the 21164 implementation of the Alpha chip. This processor generation is faster and more recent than the implementations of the Alpha chip associated with EV4 (21064,

21064A, 21066, and 21068).

• EV56 generates and schedules code optimized for some 21164 Alpha architecture implementations that use the BWX (Byte/Word manipulation) instruction extensions of the Alpha architecture.

• PCA56 generates and schedules code optimized for 21164PC Alpha architecture implementation that uses BWX (Byte/Word manipulation) and MAX (Multimedia) instructions extensions.

2–74 Compiling HP Fortran Programs

• EV6 generates and schedules code optimized for the 21264 chip implementation that uses the following extensions to the base Alpha instruction set: BWX (Byte/Word manipulation) and MAX (Multimedia) instructions, square root and floating-point convert instructions, and count instructions.

• EV67 generates and schedules code optimized for the EV67 Alpha architecture implementation that uses BWX (Byte/Word manipulation),

MVI (Multimedia) instructions, square root and floating-point convert extensions (FIX), and count extensions (CIX).

If /OPTIMIZE=TUNE=xxxx specifies a processor of less functionality than is specified by /ARCHITECTURE, code is optimized for the processor specified by

/ARCHITECTURE.

If you omit /OPTIMIZE=TUNE=xxxx, HOST is used if /FAST is specified; otherwise, GENERIC is used.

UNROLL

You can specify the number of times loops are unrolled with /OPTIMIZE=

UNROLL=n, where n is a number from 0 to 16. If you omit the UNROLL keyword or specify UNROLL=0 (the default), the optimizer determines how many times loops are unrolled. Usually loops are unrolled four times, but code analysis may result in certain loops being unrolled two times (twice).

HP Fortran unrolls loops at /OPTIMIZE=LEVEL=3 or higher. When timings using LEVEL=5 show that performance has not improved, consider specifying

UNROLL=1 with LEVEL=5, such as the following:

$ FORTRAN /OPTIMIZE=(LEVEL=5,UNROLL=1) M_APP.F90+SUB.F90/NOLIST

For More Information:

• On the effects of /OPTIMIZE=LEVEL=5, see Section 5.8.2.

• On limiting loop unrolling, see Section 5.7.4.1.

• On timing program execution, see Section 5.2.

• On the related /ASSUME=NOACCURACY_SENSITIVE qualifier, see

Section 2.3.7.

• On guidelines for improving performance, see Chapter 5.

• On the optimizations performed at each level, see Section 5.7.

Compiling HP Fortran Programs 2–75

2.3.36 /PAD_SOURCE — Pad Source Lines with Spaces

Controls how the compiler treats fixed-form file source lines that are shorter than the statement field width (72 characters, or 132 characters if /EXTEND_

SOURCE is in effect.) This determines how the compiler treats character and

Hollerith constants that are continued across two or more source lines. This qualifier does not apply to free-form source files.

Specifying /PAD_SOURCE causes the compiler to treat short source lines as if they were padded with blanks out to the statement field width. This may be useful when compiling programs developed for non-HP compilers that assume that short source lines are blank-padded.

The default, /NOPAD_SOURCE, is compatible with current and previous

HP Fortran compilers, which causes the compiler to not treat short source lines as padded with blanks so that the first character of a continuation line immediately follows the last character of the previous line.

If /NOPAD_SOURCE is in effect, the compiler issues an informational message if it detects a continued constant that might be affected by blank padding.

For More Information:

On /WARNINGS=USAGE qualifier, see Section 2.3.51.

2.3.37 /REAL_SIZE — Floating-Point Data Size

The /REAL_SIZE qualifier controls how the compiler interprets floating-point declarations that do not have a specified length.

The qualifier has the following form:

(

)

/REAL_SIZE= 64

128

Defines REAL declarations, constants, functions, and intrinsics as REAL

(KIND=4) (single precision) and COMPLEX declarations, constants, functions, and intrinsics as COMPLEX (KIND=4) (single complex).

Defines REAL and COMPLEX declarations, constants, functions, and intrinsics as REAL (KIND=8) (double precision) and COMPLEX declarations, constants, functions, and intrinsics as COMPLEX (KIND=8) (double complex).

2–76 Compiling HP Fortran Programs

This also causes intrinsic functions to produce a double precision REAL

(KIND=8) or COMPLEX (KIND=8) result instead of a single precision REAL

(KIND=4) or COMPLEX (KIND=4) result, except if the argument is explicitly typed.

For example, references to the CMPLX intrinsic produce DCMPLX results

(COMPLEX (KIND=8)), except if the argument to CMPLX is explicitly typed as REAL (KIND=4) or COMPLEX (KIND=4), in which case the resulting data type is COMPLEX (KIND=4). Other affected intrinsic functions include

CMPLX, FLOAT, REAL, SNGL, and AIMAG.

128

Specifying /REAL_SIZE=128 defines:

• REAL and DOUBLE PRECISION declarations, constants, functions, and intrinsics as REAL (KIND=16) (REAL*16)

• COMPLEX and DOUBLE COMPLEX declarations, constants, functions, and intrinsics as COMPLEX (KIND=16) (COMPLEX*32)

If you omit /REAL_SIZE=128, then:

• REAL declarations, constants, functions, and intrinsics are defined as

REAL (KIND=4).

• DOUBLE PRECISION declarations, constants, functions, and intrinsics are defined as REAL (KIND=8).

• COMPLEX declarations, constants, functions, and intrinsics are defined as

COMPLEX (KIND=4).

• DOUBLE COMPLEX declarations, constants, functions, and intrinsics are defined as COMPLEX (KIND=8).

Specifying /REAL_SIZE=128 causes REAL, DOUBLE PRECISION, COMPLEX, and DOUBLE COMPLEX intrinsic functions to produce REAL (KIND=16) or

COMPLEX (KIND=16) results unless their arguments are typed with an explicit KIND type parameter.

For example, a reference to the CMPLX intrinsic with /REAL_SIZE=128 produces a COMPLEX (KIND=16) result unless the argument is explicitly typed as REAL (KIND=4) or COMPLEX (KIND=4), in which case the result is

COMPLEX (KIND=4).

The default is /REAL_SIZE=32.

Compiling HP Fortran Programs 2–77

For More Information:

• On data types, see Chapter 8.

• On intrinsic functions, see the HP Fortran for OpenVMS Language

Reference Manual.

2.3.38 /RECURSIVE — Data Storage and Recursion

The /RECURSIVE qualifier requests that HP Fortran generate code and allocate data so that a subroutine or a function can be called recursively.

The /RECURSIVE qualifier:

• Changes the default allocation class for all local variables from STATIC to

AUTOMATIC, except for variables that are data-initialized, named in a

SAVE statement, or declared as STATIC.

• Permits references to a routine name from inside the routine.

Subprograms declared with the RECURSIVE keyword are always recursive

(whether you specify or omit the /RECURSIVE qualifier).

Variables declared with the AUTOMATIC statement or attribute always use stack-based storage for all local variables (whether you specify or omit the

/RECURSIVE or /AUTOMATIC qualifiers).

Specifying /RECURSIVE sets /AUTOMATIC.

For More Information:

On the RECURSIVE keyword, see the HP Fortran for OpenVMS Language

Reference Manual.

2.3.39 /REENTRANCY — Specify Threaded or Asynchronous

Reentrancy

The /REENTRANCY qualifier specifies whether code generated for the main program and any Fortran procedures it calls will be relying on threaded or asynchronous reentrancy. The default is /REENTRANCY=NONE.

The qualifier has the following form:

(

ASYNC

)

/REENTRANCY= NONE

THREADED

2–78 Compiling HP Fortran Programs

ASYNC

Informs the HP Fortran run-time library that the program may contain asynchronous handlers that could call the RTL. The run-time library will guard against asynchronous interrupts inside its own critical regions.

NONE

Informs the HP Fortran run-time library that the program will not be relying on threaded or asynchronous reentrancy. The run-time library need not guard against such interrupts inside its own critical regions. Same as

/NOREENTRANCY.

THREADED

Informs the HP Fortran run-time library that the program is multithreaded, such as programs using the POSIX threads library. The run-time library will use thread locking to guard its own critical regions.

To use the kernel threads libraries, also specify the /THREADS_ENABLE qualifier on the LINK command (see the Guide to the POSIX Threads Library).

Specifying NOREENTRANCY is equivalent to /REENTRANCY=NONE.

For More Information:

On writing multithreaded applications, see the Guide to the POSIX Threads

Library.

2.3.40 /ROUNDING_MODE — Specify IEEE Floating-Point Rounding

Mode

The /ROUNDING_MODE qualifier allows you to control how rounding occurs during calculations. This qualifier applies only to IEEE data types (when you specify /FLOAT=IEEE_FLOAT). Note that if you specify /FLOAT=G_FLOAT or

/FLOAT=D_FLOAT, /ROUNDING_MODE must not also be specified.

Note that the rounding mode applies to each program unit being compiled.

The qualifier has the following form:

/ROUNDING_MODE=

NEAREST

CHOPPED

MINUS_INFINITY

DYNAMIC

Compiling HP Fortran Programs 2–79

NEAREST

This is the normal rounding mode, where results are rounded to the nearest representable value. If you omit the /ROUNDING_MODE qualifier,

/ROUNDING_MODE=NEAREST is used.

CHOPPED

Results are rounded to the nearest representable value in the direction toward zero.

MINUS_INFINITY

Results are rounded toward the next smallest representative value.

DYNAMIC

Lets you set the rounding mode at run time.

On OpenVMS I64, you can call the SYS$IEEE_SET_ROUNDING_MODE routine to set the rounding mode and obtain the previous rounding mode.

When you call SYS$IEEE_SET_ROUNDING_MODE, you can set the rounding mode to one of the following settings:

• Round toward zero (same as /ROUNDING_MODE=CHOPPED)

• Round toward nearest (same as /ROUNDING_MODE=NEAREST)

• Round toward plus infinity

• Round toward minus infinity (same as /ROUNDING_MODE=CHOPPED)

If you compile with /ROUNDING_MODE=DYNAMIC, the initial rounding mode is set to NEAREST. It will remain NEAREST until you call SYS$IEEE_

SET_ROUNDING_MODE to change it.

On OpenVMS Alpha, there is no system routine to call to set the rounding mode dynamically. You have to write and call your own routines to set the rounding mode at run time. The mode is set by setting the rounding control bits in the floating-point control register (FPCR). You can do this in C using the asm feature from the system include file c_asm.h

, or in assembly language.

Note

For the fastest run-time performance, avoid using /ROUNDING_

MODE=DYNAMIC.

The rounding mode applies to each program unit being compiled.

2–80 Compiling HP Fortran Programs

For More Information:

• On IEEE floating-point rounding modes, see the IEEE Standard for Binary

Floating-Point Arithmetic (ANSI/IEEE Std 754-1985).

• On SYS$IEEE_SET_ROUNDING_MODE, see the HP OpenVMS System

Services Reference Manual.

• On the floating-point status register and Itanium architecture, see the Intel

Itanium Architecture Software Developer’s Manual, Volume 1: Application

Architecture.

• On the floating-point control register and Alpha architecture, see the Alpha

Architecture Reference Manual.

2.3.41 /SEPARATE_COMPILATION — Control Compilation Unit Use in

Object Files

Controls whether the HP Fortran compiler:

• Places individual compilation units in an HP Fortran source file as separate object modules in the object file (/SEPARATE_COMPILATION)

• Groups individual compilation units in an HP Fortran source file as a single object module in the object file (/NOSEPARATE_COMPILATION), which allows more interprocedure optimization

The default is /NOSEPARATE_COMPILATION.

When creating object modules for use in an object library, consider using

/SEPARATE_COMPILATION to minimize the size of the routines included by the linker as it creates the executable image. In most cases, to allow more interprocedure optimizations, use the default /NOSEPARATE_

COMPILATION.

For More Information:

• On compiling multiple files, see Section 2.2.2.

• On the optimizations that can be performed (such as inlining), see

Section 2.3.35.

Compiling HP Fortran Programs 2–81

2.3.42 /SEVERITY — Specify Compiler Diagnostic Severity

The /SEVERITY qualifier changes one or both of the following:

• Changes compiler diagnostic warning messages to have a severity of error

(instead of warning). The severity of informational compiler diagnostic messages remains informational severity.

To control the conditions checked during compilation that prevent or request messages, use the /WARNINGS qualifier keywords (see

Section 2.3.51.

• When used with the /STANDARD qualifier, /SEVERITY changes standards checking warning messages to have a severity of error (instead of warning).

The severity of informational standards checking diagnostic messages remains informational severity.

To control the type of standards checking performed, specify the

/STANDARDS qualifier with either the F90 keyword (default) or the

F95 keyword (see Section 2.3.45.

The qualifier has the following form:

(

WARNING

/SEVERITY=WARNINGS= ERROR

STDERROR

)

The default is that compiler diagnostic warning messages and standards checking messages have a severity of warning or

/SEVERITY=(WARNINGS=WARNING).

You can specify one of the following:

• ERROR

Specifies that all warning messages are to be issued with ERROR severity.

• STDERROR

Specifies that if /STANDARD is in effect and diagnostics indicating nonstandard features are issued, the diagnostics are issued with ERROR severity (the default is that these are informational). All other warning messages are issued with WARNING severity.

• WARNINGS

Specifies that all warning messages are to be issued with WARNING severity.

2–82 Compiling HP Fortran Programs

For example, the following command line requests that compiler diagnostic messages have a severity of warning (default) and standards checking messages have a severity of error (and requests Fortran 95 standards checking)::

$ FORTRAN/SEVERITY=WARNINGS=STDERROR/STANDARD=F95 file.F90

For More Information:

• On using the /WARNINGS qualifier to control the conditions checked during compilation, see Section 2.3.51.

• On using the /STANDARDS qualifier to control the type of standards checking performed, see Section 2.3.45.

2.3.43 /SHOW — Control Source Content in Listing File

The /SHOW qualifier controls whether optionally listed source lines and a symbol map appear in the source listing. (Optionally listed source lines are text-module source lines and preprocessor-generated source lines.)

For the /SHOW qualifier to take effect, you must specify the /LIST qualifier.

The qualifier has the following form:

/SHOW =

< n

[NO]DICTIONARY

[NO]INCLUDE

[NO]MAP

[NO]PREPROCESSOR

ALL o

NONE

[, ...]

ALL

Requests that all optionally listed source lines and a symbol map be included in the listing file. Specifying /SHOW is equivalent to /SHOW=ALL.

[NO]DICTIONARY

Controls whether HP Fortran source representations of any CDD/Repository records referenced by DICTIONARY statements are included in the listing file.

[NO]INCLUDE

Controls whether the source lines from any file or text module specified by

INCLUDE statements are included in the source listing.

[NO]MAP

Controls whether the symbol map is included in the listing file.

Compiling HP Fortran Programs 2–83

[NO]PREPROCESSOR

Controls whether preprocessor-generated source lines are included in the listing file.

NONE

Requests that no optionally listed source lines or a symbol map be included in the listing file. Specifying /NOSHOW is equivalent to /SHOW=NONE.

The /SHOW qualifier defaults are NOINCLUDE and MAP.

For More Information:

On the /LIST qualifier, see Section 2.3.28.

2.3.44 /SOURCE_FORM — Fortran 90/95 Source Form

The /SOURCE_FORM qualifier allows you to specify whether all HP Fortran source files on the FORTRAN command line are in fixed or free source form.

The qualifier has the following form:

/SOURCE_FORM= n

FIXED

FREE o

FIXED

Specifies that the input source files will be in fixed source form, regardless of the file type. Source files with a file type of FOR or F (or any file type other than F90) are assumed to contain fixed source form.

FREE

Specifies that the input source files will be free form, regardless of the file type.

Source files with a file type of F90 are assumed to contain free source form.

For More Information:

On column positions and source forms, see the HP Fortran for OpenVMS

Language Reference Manual.

2.3.45 /STANDARD — Perform Fortran 90/95 Standards Checking

The /STANDARD qualifier instructs the compiler to generate informational messages for language elements that are not standard in the Fortran 90 or

Fortran 95 language and that can be identified at compile-time. The default is /NOSTANDARD. If you specify /STANDARD with no value, the default is

Fortran 95.

2–84 Compiling HP Fortran Programs

The qualifier has the following form:

(

F90

)

/[NO]STANDARD= F95

NONE

The /STANDARD=F90 qualifier requests that the compiler issue informational messages for:

• Syntax extensions to the Fortran 90 standard. SYNTAX extensions include nonstandard statements and language constructs.

• Fortran 90 standard-conforming statements that become nonstandard due to the way in which they are used. Data type information and statement locations are considered when determining semantic extensions.

• For fixed-format source files, lines that use tab formatting.

The /STANDARD=F95 qualifier (or /STANDARD) requests that the compiler issue informational messages for:

• Syntax extensions to the Fortran 95 standard. SYNTAX extensions include nonstandard statements and language constructs.

• Fortran 95 standard-conforming statements that become nonstandard due to the way in which they are used. Data type information and statement locations are considered when determining semantic extensions.

• For fixed-format source files, lines that use tab formatting.

• Deleted Fortran language features.

Specifying /STANDARD=NONE is equivalent to /NOSTANDARD.

If you specify the /NOWARNINGS qualifier, the /STANDARD qualifier is ignored.

If you omit the /STANDARD qualifier, the default is /NOSTANDARD.

To change the severity of standards checking warning messages to error severity, specify /SEVERITY=WARNINGS=SDTERROR (see Section 2.3.42).

Source statements that do not conform to Fortran 90 or Fortran 95 language standards are detected by the HP Fortran compiler under the following circumstances:

• The statements contain ordinary syntax and semantic errors.

• A source program containing nonconforming statements is compiled with the /STANDARD or /CHECK qualifiers.

Compiling HP Fortran Programs 2–85

Given these circumstances, the compiler is able to detect most instances of nonconforming usage. It does not detect all instances because the /STANDARD qualifier does not produce checks for all nonconforming usage at compile time. In general, the unchecked cases of nonconforming usage arise from the following situations:

• The standard violation results from conditions that cannot be checked at compile time.

• The compile-time checking is prone to false alarms.

Most of the unchecked cases occur in the interface between calling and called subprograms. However, other cases are not checked, even within a single subprogram.

The following items are known to be unchecked:

• Use of a data item prior to defining it

• Use of the SAVE statement to ensure that data items or common blocks retain their values when reinvoked

• Association of character data items on the right and left sides of character assignment statements

• Mismatch in order, number, or type in passing actual arguments to subprograms with implicit interfaces

• Association of one or more actual arguments with a data item in a common block when calling a subprogram that assigns a new value to one or more of the arguments

For More Information:

On the HP Fortran language, see the HP Fortran for OpenVMS Language

Reference Manual.

2.3.46 /SYNCHRONOUS_EXCEPTIONS — Report Exceptions More

Precisely (Alpha only)

The /SYNCHRONOUS_EXCEPTIONS qualifier associates an exception with the instruction that causes it. Specifying /SYNCHRONOUS_EXCEPTIONS slows program execution, you should specify it only when debugging a specific problem, such as locating the source of an exception.

If you omit /SYNCHRONOUS_EXCEPTIONS, /NOSYNCHRONOUS_

EXCEPTIONS is used where exceptions can be reported imprecisely one or more instructions after the instruction that caused the exception.

2–86 Compiling HP Fortran Programs

Specifying /IEEE_MODE=FAST (default) provides imprecise exception reporting (same as /NOSYNCHRONOUS_EXCEPTIONS). Specifying other /IEEE_MODE keywords (when you also specify /FLOAT=IEEE_

FLOAT) provides precise exception reporting (same as /SYNCHRONOUS_

EXCEPTIONS on Alpha systems).

Note that floating-point exceptions are always synchronous on EV6 and later processors, regardless of whether /SYNCHRONOUS_EXCEPTIONS is used.

For More Information:

• On run-time arithmetic exception handling (/IEEE_MODE qualifier), see

Section 2.3.24.

• On controlling run-time arithmetic exception messages (/CHECK=FP_

EXCEPTIONS qualifier), see Section 2.3.11.

• On the Alpha architecture and instruction pipelining, see the Alpha

Architecture Reference Manual.

2.3.47 /SYNTAX_ONLY — Do Not Create Object File

The /SYNTAX_ONLY qualifier requests that source file be checked only for correct syntax. If you specify the /SYNTAX_ONLY qualifier, no code is generated, no object file is produced, and some error checking done by the optimizer is bypassed (for example, checking for uninitialized variables with

/WARNINGS=UNINITIALIZED). This qualifier allows you to do a quick syntax check of your source file, and is especially useful in conjunction with

/WARNINGS=ARGUMENT_CHECKING.

For More Information:

• On the related qualifier that prevents object file creation (/NOOBJECT), see Section 2.3.33.

• On the /WARNINGS qualifier, see Section 2.3.51.

2.3.48 /VERSION — Display the HP Fortran Version Number

The /VERSION qualifier can be used alone on the FORTRAN command line to display the HP Fortran version number. If you specify /VERSION, compilation does not occur.

For example:

$ FORTRAN /VERSION

HP Fortran V8.n-nnn-nnnn

Compiling HP Fortran Programs 2–87

2.3.49 /TIE — Enable Code for Shared Translated Images

The /TIE qualifier enables compiled code to be used with translated shared images, either because the code might call into a translated image or might be called from a translated image. Specifying /NOTIE, the default, indicates the compiled code will not be associated with a translated image.

If you specify /TIE, link the object module using the LINK command

/NONATIVE_ONLY qualifier, and follow the guidelines provided in

Section B.6.

For More Information:

On appropriate LINK command qualifiers, see Section 3.2.1 and Section B.6.

2.3.50 /VMS — Request Compaq Fortran 77 for OpenVMS VAX

Compatibility

The /VMS qualifier specifies that the run-time system behave like Compaq

Fortran 77 for OpenVMS VAX Systems (VAX FORTRAN) in certain ways. To prevent this behavior, specify /NOVMS.

This qualifier is the default.

The /VMS qualifier specifies the following aspects of the run-time system:

• Sets the defaults for the following qualifiers:

/CHECK=FORMAT

Specifying /NOVMS changes the default to /CHECK=NOFORMAT (see

Section 2.3.11).

/CHECK=OUTPUT_CONVERSION

Specifying /NOVMS changes the default to /CHECK=NOOUTPUT_

CONVERSION (see Section 2.3.11).

Note that the /VMS qualifier allows use of /LIST or /NOLIST in INCLUDE statement specifications. (Also see /ASSUME=SOURCE_INCLUDE to control included directory.)

To override the effects of the /VMS qualifier, specify /NOVMS.

For More Information:

On the OPEN statement, see the HP Fortran for OpenVMS Language Reference

Manual.

2–88 Compiling HP Fortran Programs

2.3.51 /WARNINGS — Warning Messages and Compiler Checking

The /WARNINGS qualifier instructs the compiler to generate informational (Ilevel) and warning (W-level) diagnostic messages in response to informational and warning-level errors.

The following /WARNINGS keywords prevent the display of warning messages:

NOALIGNMENT (default is ALIGNMENT)

NOGENERAL (default is GENERAL)

NOGRANULARITY (default is GRANULARITY)

NOUNCALLED (default is UNCALLED)

NOUNINITIALIZED (default is UNINITIALIZED)

NOUSAGE (default is USAGE)

The following /WARNINGS keywords can display additional warning messages

(request additional checking):

ARGUMENT_CHECKING (default is NOARGUMENT_CHECKING)

DECLARATIONS (default is NODECLARATIONS)

IGNORE_LOC (default is NOIGNORE_LOC)

TRUNCATED_SOURCE (default is NOTRUNCATED_SOURCE)

UNUSED (default is NOUNUSED)

If you omit /WARNINGS, the defaults are:

/WARNINGS=(ALIGNMENTS,NOARGUMENT_CHECKING,

NODECLARATIONS, NOERRORS,FILEOPTS,GENERAL,GRANULARITY,

NOIGNORE_LOC,NOSTDERRORS,NOTRUNCATED_SOURCE,UNCALLED,

UNINITIALIZED, NOUNUSED,USAGE)

The qualifier has the following form:

Compiling HP Fortran Programs 2–89

/WARNINGS =

6 >

[NO]ALIGNMENT

[NO]ARGUMENT_CHECKING

[NO]DECLARATIONS

[NO]GENERAL

> n

[NO]GRANULARITY

[NO]IGNORE_LOC

[NO]TRUNCATED_SOURCE

[NO]UNCALLED

[NO]UNINITIALIZED

[NO]UNUSED

[NO]USAGE o

ALL

NONE

[, ...]

[NO]ALIGNMENT

Controls whether the compiler issues diagnostic messages when variables or arrays (created in COMMON or EQUIVALENCE statements) are declared in such a way that they cross natural boundaries for their data size. For example, a diagnostic message is issued if /WARNINGS=ALIGNMENT is in effect and the virtual address of a REAL (KIND=8) variable is not a multiple of 8.

The default is ALIGNMENT. To suppress diagnostic messages about unaligned data, specify NOALIGNMENT.

To control the alignment of fields in common blocks, derived types, and record structures, use the /ALIGNMENT qualifier (see Section 2.3.3).

[NO]ARGUMENT_CHECKING

Controls whether the compiler issues diagnostic messages for argument mismatches between caller and callee (when compiled together). The default is

/WARNINGS=NOARGUMENT_CHECKING.

[NO]DECLARATIONS

Controls whether the compiler issues diagnostic messages for any untyped data item used in the program. DECLARATIONS acts as an external IMPLICIT

NONE declaration. See the description of the IMPLICIT statement in the HP

Fortran for OpenVMS Language Reference Manual for information about the effects of IMPLICIT NONE.

The default is NODECLARATIONS.

2–90 Compiling HP Fortran Programs

[NO]GENERAL

Controls whether the compiler issues I-level and W-level diagnostic messages.

An I-level message indicates that a correct HP Fortran statement may have unexpected results or contains nonstandard syntax or source form. A W-level message indicates that the compiler has detected acceptable, but nonstandard, syntax or has performed some corrective action; in either case, unexpected results may occur.

To suppress I-level and W-level diagnostic messages, specify the negative form of this qualifier (/WARNINGS=NOGENERAL).

The default is GENERAL.

[NO]GRANULARITY

Controls whether the compiler issues the compiler diagnostic message "Unable to generate code for requested granularity" to indicate when data access might not occur safely from different threads in a shared memory system (such as asynchronous write access from outside the user process). The default is

/WARNINGS=GRANULARITY.

For more information on data granularity and controlling the size of data that can be safely accessed from different threads, see Section 2.3.23.

[NO]IGNORE_LOC

Requests that the compiler issue warnings when %LOC is stripped from an argument due to specification of the IGNORE_LOC attribute. The default is

/WARNINGS=NOIGNORE_LOC (does not issue a warning for this condition).

[NO]TRUNCATED_SOURCE

Controls whether the compiler issues a warning diagnostic message

(EXCCHASRC) when it reads a fixed-form source line with a statement field that exceeds the maximum column width. The maximum column width is column 72 or 132, depending whether /EXTEND_SOURCE qualifier was specified (or its OPTIONS statement qualifier).

This option has no effect on truncation; lines that exceed the maximum column width are always truncated.

The default is /WARNINGS=NOTRUNCATED_SOURCE.

[NO]UNCALLED

Suppresses the compiler warning diagnostic message when a statement function is never called. The default is /WARNINGS=UNCALLED.

Compiling HP Fortran Programs 2–91

[NO]UNINITIALIZED

Controls whether warning messages are issued when a variable is referenced before a value was assigned to it. Specify NOUNINITIALIZED to suppress such warning messages.

The default, /WARNINGS=UNINITIALIZED, issues warning messages when a variable is referenced before a value was assigned to it.

[NO]UNUSED

Requests warning messages for a variable that is declared but never used. The default is /WARNINGS=NOUNUSED.

[NO]USAGE

Specifying /WARNINGS=NOUSAGE suppresses informational messages about questionable programming practices and the use of intrinsic functions that use only two digits to represent years (such as 2000). The compiler allows such programming practices, although they are often an artifact of programming errors. For example, a continued character or Hollerith literal whose first part ends before the statement field and appears to end with trailing spaces.

The default is USAGE.

ALL

Causes the compiler to print all I-level and W-level diagnostic messages, including warning messages for any unaligned data and untyped data items.

Specifying ALL is equivalent to /WARNINGS and has the effect of specifying

/WARNINGS=(ALIGNMENT, DECLARATIONS, GENERAL, UNCALLED,

UNINITIALIZED).

NONE

Suppresses all I-level and W-level messages. Specifying /NOWARNINGS is equivalent to /WARNINGS=NONE.

For More Information:

• On compiler diagnostic messages, see Section 2.6.

• On run-time checking for various conditions (/CHECK qualifier), see

Section 2.3.11.

• On changing the severity of compiler diagnostic warnings messages to error severity, see Section 2.3.42.

2–92 Compiling HP Fortran Programs

2.4 Creating and Maintaining Text Libraries

A text library contains library modules of source text. To include a library module from a text library in a program, use an INCLUDE statement.

Library modules within a text library are like ordinary text files, but they differ in the following ways:

• They contain a unique name, called the library module name, that is used to access them.

• Several library modules can be contained within the same library file.

Library modules in text libraries can contain any kind of text; this section only discusses their use when HP Fortran language source is used.

You should be aware of the difference between library modules that reside in text libraries and the HP Fortran post-compiled module files (.F90$MOD file type) that support use association (see Section 2.2.3).

Use the LIBRARY command (OpenVMS Librarian Utility) to create text libraries and insert, replace, delete, copy, or list library modules in text libraries. Text libraries have a default file type of TLB.

Figure 2–2 shows the creation of a text library and its use in compiling HP

Fortran programs.

Compiling HP Fortran Programs 2–93

Figure 2–2 Creating and Using a Text Library

COMMAND

$ LIBRARY/TEXT/CREATE FORFILES

$__FILE: APPLIC.SYM,DECLARE.F90

Create a library containing the modules APPLIC and DECLARE

INPUT/OUTPUT FILES

APPLIC.SYM

DECLARE.F90

FORFILES.TLB

$ FORT METRIC+FORFILES/LIBRARY

Process the input file

METRIC.F90, and locate the INCLUDE files in library

FORFILES.TLB

METRIC.F90

ZK−7478A−GE

For More Information:

• On using the logical name FORT$LIBRARY to define a default library, see

Section 2.2.4.

• On specifying the name of the library using the /LIBRARY qualifier on the

FORTRAN command line, see Section 2.3.27.

• On specifying the directory location of the library using the /INCLUDE qualifier, see Section 2.3.25.

• On specifying the directory location of the library using the

/ASSUME=SOURCE_INCLUDE qualifier, see Section 2.3.7.

• On using Fortran modules, see Section 2.2.3.

• On using INCLUDE or USE statements, see the HP Fortran for OpenVMS

Language Reference Manual.

2–94 Compiling HP Fortran Programs

2.4.1 Using the LIBRARY Commands

Table 2–3 summarizes the commands that create libraries and provide maintenance functions. For a complete list of the qualifiers for the LIBRARY command and a description of other DIGITAL Command Language (DCL) commands listed in Table 2–3, see the Guide to Using VMS Command

Procedures or enter HELP LIBRARY.

Table 2–3 Commands to Control Library Files

Function Command Syntax 1

Create a library.

Add one or more library modules to a library.

Replace one or more library modules in a library.

Specify the names of library modules to be added to a library.

Delete one or more library modules from a library.

Copy a library module from a library into another file.

List the library modules in a library.

LIBRARY/TEXT/CREATE library-name file-spec,...

LIBRARY/TEXT/INSERT library-name file-spec,...

LIBRARY/TEXT/REPLACE library-name file-spec,...

LIBRARY/TEXT/INSERT library-name file-spec/MODULE= module-name

LIBRARY/TEXT/DELETE=(module-name,...) library-name

LIBRARY/TEXT/EXTRACT=module-name/OUTPUT= file-spec library-name

LIBRARY/TEXT/LIST=file-spec library-name

The LIBRARY command qualifier /TEXT indicates a text module library. By default, the LIBRARY command assumes an object module library.

REPLACE is the default function of the LIBRARY command if no other action qualifiers are specified. If no library module exists with the given name, /REPLACE is equivalent to /INSERT.

2.4.2 Naming Text Library Modules

When the LIBRARY command adds a library module to a library, by default it uses the file name of the input file as the name of the library module. In the example in Figure 2–2, the LIBRARY command adds the contents of the files APPLIC.SYM and DECLARE.FOR to the library and names the library modules APPLIC and DECLARE.

Alternatively, you can name a module in a library with the /MODULE qualifier.

For example:

$ LIBRARY/TEXT/INSERT FORFILES DECLARE.FOR /MODULE=EXTERNAL_DECLARATIONS

Compiling HP Fortran Programs 2–95

The preceding command inserts the contents of the file DECLARE.FOR into the library FORFILES under the name EXTERNAL_DECLARATIONS. This library module can be included in an HP Fortran source file during compilation with the following statement:

INCLUDE ’FORFILES(EXTERNAL_DECLARATIONS)’

For More Information:

• On the INCLUDE statement, see the HP Fortran for OpenVMS Language

Reference Manual and Section 2.2.4.1.

• On controlling the directories and libraries searched with FORTRAN command qualifiers and the FORT$INCLUDE logical name, see

Section 2.2.4.1.

2.5 Using CDD/Repository

CDD/Repository is an optional software product available under a separate license. The CDD/Repository product allows you to maintain shareable data definitions (language-independent structure declarations) that are defined by a data or repository administrator.

Note

CDD/Repository supports both the Common Data Dictionary (Version

3) and CDD/Plus (Version 4) interfaces. Older dictionary versions need to be converted to repository (CDD/Repository) format using a supplied conversion utility. For detailed information about CDD/Repository, see the CDD/Repository documentation.

CDD/Repository data definitions are organized hierarchically in much the same way that files are organized in directories and subdirectories. For example, a repository for defining personnel data might have separate directories for each employee type.

Descriptions of data definitions are entered into the dictionary in a specialpurpose language called CDO (Common Dictionary Operator, which replaces the older interface called CDDL, Common Data Dictionary Language).

CDD/Repository converts the data descriptions to an internal form—making them independent of the language used to access them—and inserts them into the repository.

2–96 Compiling HP Fortran Programs

During the compilation of an HP Fortran program, CDD/Repository data definitions can be accessed by means of DICTIONARY statements. If the data attributes of the data definitions are consistent with HP Fortran requirements, the data definitions are included in the HP Fortran program.

CDD/Repository data definitions, in the form of HP Fortran source code, appear in source program listings if you specify the /SHOW=DICTIONARY qualifier on the FORTRAN command line or the /LIST qualifier in the DICTIONARY statement.

The advantage in using CDD/Repository instead of HP Fortran source for structure declarations is that CDD/Repository record declarations are language-independent and can be used with several supported OpenVMS languages.

The following examples demonstrate how data definitions are written for

CDD/Repository. The first example is a structure declaration written in

CDDL. The second example shows the same structure as it would appear in a

FORTRAN output listing.

CDO Representation: define field name datatype is text size is 30.

define field address datatype is text size is 40.

define field salesman-id datatype is longword unsigned size is 4.

define record payroll-record name.

address.

salesman-id.

end record.

HP Fortran Source Code Representation:

STRUCTURE /PAYROLL_RECORD/

STRUCTURE SALESMAN

CHARACTER*30 NAME

CHARACTER*40 ADDRESS

STRUCTURE SALESMAN_ID

BYTE %FILL(4)

END STRUCTURE

Compiling HP Fortran Programs 2–97

2.5.1 Accessing CDD/Repository from HP Fortran Programs

A repository or data administrator uses CDO to create repositories, define directory structures, and insert record and field definitions into the repository.

Many repositories can be linked together to form one logical repository. If the paths are set up correctly, users can access definitions as if they were in a single repository regardless of physical location.

CDO also creates the record paths. Once established, records can be extracted from the repository by means of DICTIONARY statements in HP Fortran programs. At compile time, the record definition and its attributes are extracted from the designated repository. Then the compiler converts the extracted record definition into an HP Fortran structure declaration and includes it in the object module.

The DICTIONARY statement incorporates CDD/Repository data definitions into the current HP Fortran source file during compilation. The DICTIONARY statement can occur anywhere in an HP Fortran source file that a specification statement (such as a STRUCTURE...END STRUCTURE block) is allowed.

The format of the DICTIONARY statement is described in the HP Fortran for

OpenVMS Language Reference Manual.

A DICTIONARY statement must appear as a statement by itself; it cannot be used within an HP Fortran structure declaration. For example, consider the following DICTIONARY statement:

INTEGER*4 PRICE

DICTIONARY ’ACCOUNTS’

This would result in a declaration of the following form:

INTEGER*4 PRICE

STRUCTURE /ACCOUNTS/

STRUCTURE NUMBER

CHARACTER*3 LEDGER

CHARACTER*5 SUBACCOUNT

END STRUCTURE

CHARACTER*12 DATE

END STRUCTURE

When you extract a record definition from the repository, you can choose to include this translated record in the program’s listing by using the /LIST qualifier in the DICTIONARY statement or the /SHOW=DICTIONARY qualifier in the FORTRAN command line.

2–98 Compiling HP Fortran Programs

CDD/Repository data definitions can contain explanatory text in the

DESCRIPTION IS clause. If you specify /SHOW=DICTIONARY on the

FORTRAN command (or /LIST in the DICTIONARY statement), this text is included in the HP Fortran output listing as comments.

Because the DICTIONARY statement generally contains only structure declaration blocks, you will usually also need to include one or more RECORD statements in your program to make use of these structures. (See the HP

Fortran for OpenVMS Language Reference Manual for information about structure declaration blocks or the RECORD statement.)

2.5.2 HP Fortran and CDD/Repository Data Types

The CDD/Repository supports some data types that are not native to HP

Fortran. If a data definition contains a field declared with an unsupported data type, HP Fortran replaces the field with one declared as an inner

STRUCTURE containing a single unnamed field (%FILL field) that is a BYTE array with an appropriate dimension. The HP Fortran compiler does not attempt to approximate a data type that it does not support.

For example, CDD/Repository’s data type UNSIGNED LONG is not supported by HP Fortran. As a result, if the field FIELD1 is declared to be UNSIGNED

LONG using CDO, HP Fortran replaces the definition of FIELD1 with the following declaration:

STRUCTURE FIELD1

BYTE %FILL(4)

END STRUCTURE

HP Fortran does not declare it as INTEGER*4, which results in signed operations if the field was used in an arithmetic expression.

Table 2–4 summarizes the CDO data types and corresponding HP Fortran data types.

Table 2–4 CDO Data Types and Corresponding HP Fortran Data Types

CDO Data Type HP Fortran Data Type

DATE

DATE AND TIME

VIRTUAL

BIT m ALIGNED

STRUCTURE (length 8)

STRUCTURE (length n) ignored

STRUCTURE (length n+7/8)

(continued on next page)

Compiling HP Fortran Programs 2–99

Table 2–4 (Cont.) CDO Data Types and Corresponding HP Fortran Data Types

CDO Data Type HP Fortran Data Type

BIT m

UNSPECIFIED

TEXT

VARYING TEXT

VARYING STRING

D_FLOATING

D_FLOATING COMPLEX

F_FLOATING

F_FLOATING COMPLEX

G_FLOATING

G_FLOATING COMPLEX

H_FLOATING

H_FLOATING COMPLEX

SIGNED BYTE

UNSIGNED BYTE

SIGNED WORD

UNSIGNED WORD

SIGNED LONGWORD

UNSIGNED LONGWORD

SIGNED QUADWORD

UNSIGNED QUADWORD

SIGNED OCTAWORD

UNSIGNED OCTAWORD

PACKED NUMERIC

SIGNED NUMERIC

UNSIGNED NUMERIC

LEFT OVERPUNCHED

STRUCTURE (length n+7/8)

STRUCTURE (length n)

CHARACTER*n

STRUCTURE (length n)

REAL*8 (/FLOAT=D_FLOAT only)

COMPLEX*16 (/FLOAT=D_FLOAT only)

REAL*4 (/FLOAT=D_FLOAT or /FLOAT=G_

FLOAT)

COMPLEX*8 (/FLOAT=D_FLOAT or /FLOAT=G_

FLOAT)

REAL*8 (/FLOAT=G_FLOAT only)

COMPLEX*16 (/FLOAT=G_FLOAT only)

STRUCTURE (length 16)

STRUCTURE (length 32)

LOGICAL*1

STRUCTURE (length 1)

INTEGER*2

STRUCTURE (length 2)

INTEGER*4

STRUCTURE (length 4)

STRUCTURE (length 8)

STRUCTURE (length 16)

STRUCTURE (length n)

(continued on next page)

2–100 Compiling HP Fortran Programs

Table 2–4 (Cont.) CDO Data Types and Corresponding HP Fortran Data Types

CDO Data Type HP Fortran Data Type

LEFT SEPARATE

RIGHT OVERPUNCHED

RIGHT SEPARATE

STRUCTURE (length n)

Note

D_floating and G_floating data types cannot be mixed in one subroutine because both types cannot be handled simultaneously. You can use both types, each in a separate subroutine, depending on the OPTIONS statement qualifier in effect for the individual subroutine. For a discussion of the handling of REAL*8 data types in HP Fortran, see the HP Fortran for OpenVMS Language Reference Manual.

The compiler issues an error message if it encounters a CDD/Repository feature that conflicts with HP Fortran. It ignores any CDD/Repository features that it does not support.

2.6 Compiler Limits, Diagnostic Messages, and Error

Conditions

The following sections discuss the compiler limits and error messages.

2.6.1 Compiler Limits

Table 2–5 lists the limits to the size and complexity of a single HP Fortran program unit and to individual statements contained in it.

The amount of data storage, the size of arrays, and the total size of executable programs are limited only by the amount of process virtual address space available, as determined by process quotas and system parameters.

Compiling HP Fortran Programs 2–101

Table 2–5 Compiler Limits

Language Element

Actual number of arguments per CALL or function reference

Arguments in a function reference in a specification expression

Array dimensions

Array elements per dimension

Constants; character and Hollerith

Constants; characters read in list-directed I/O

Continuation lines

DO and block IF statement nesting (combined)

DO loop index variable

Format group nesting

Fortran source line length

INCLUDE file nesting

Labels in computed or assigned GOTO list

Lexical tokens per statement

Parentheses nesting in expressions

Structure nesting

Symbolic-name length

Limit

255

9,223,372,036,854,775,807 or process limit

2000 characters

2048 characters

511

128

9,223,372,036,854,775,807 or process limit

132 characters

20 levels

500

3000

63 characters

For More Information:

On relevant process quotas and system parameters, see Section 1.2.

2.6.2 Compiler Diagnostic Messages and Error Conditions

The HP Fortran compiler identifies syntax errors and violations of language rules in the source program.

If the compiler locates any errors, it writes messages to your default output device; so, if you enter the FORTRAN command interactively, the messages are displayed on your terminal. If the FORTRAN command is executed in a batch job, the messages appear in the log file for the batch job.

2–102 Compiling HP Fortran Programs

A sample message from the compiler as it would appear on a terminal screen follows:

40 FORMAT (I3,)

................^

%F90-W-ERROR, An extra comma appears in the format list.

at line number 13 in file DISK$:[USER]SAMP_MESS.FOR;4

This sample message consists of the following lines:

• The source file line that caused the message

• A pointer (...^ on a terminal or ...1 in a listing file) to the part of the source line causing the error

• The actual message (facility, severity, mnemonic, and text)

• The line number and name of source file

The message line has the following format:

%F90-s-ident, message-text

The facility, F90, follows the percent sign ( % ). The severity of the message

(I for informational, W for warning, E for error, or F for fatal) replaces s.

A mnemonic for that message replaces ident. The explanatory text of the message replaces message-text.

Diagnostic messages usually provide enough information for you to determine the cause of an error and correct it. If you compile using the /OPTIMIZE qualifier (the default) and have difficulty determining the cause of an error

(possibly because of the optimizations), consider compiling using a lower optimization level or /NOOPTIMIZE.

If the compiler creates a listing file, it also writes the messages to the listing.

The pointer (...1) and messages follow the statement that caused the error.

2.7 Compiler Output Listing Format

A compiler output listing produced by a FORTRAN command with the /LIST qualifier consists of the following sections:

• A source code section

• A machine code section—optional

• A storage map section (cross-reference)—optional

• A compilation summary

Section 2.7.1 through Section 2.7.5 describe the compiler listing sections in detail.

Compiling HP Fortran Programs 2–103

For More Information:

• On the /LIST qualifier, see Section 2.3.28)

• On the /MACHINE_CODE qualifier, see Section 2.3.29.

• On the /SHOW qualifier, see Section 2.3.43.

2.7.1 Source Code Section

The source code section of a compiler output listing displays the source program as it appears in the input file, with the addition of sequential line numbers generated by the compiler. Example 2–1 and Example 2–2 show a sample of a source code section of a free-form compiler output listing.

Example 2–1 Sample Listing of Source Code on OpenVMS I64

SIMPLE$MAIN$BLK Source Listing 26-OCT-2004 15:29:44 HP Fortran V8.0-48291 Page 1

26-OCT-2004 15:29:26 DISK$DKA100:[USERNAME.BUG]SIMPLE.F90;1

1 integer i

2 i = 10

3 type *,i

4 end

PROGRAM SECTIONS

Name

1 $LITERAL$

2 $CODE$

3 $SBSS$

Total Space Allocated

Bytes Attributes

24 PIC CON REL LCL SHR NOEXE RD NOWRT OCTA

224 PIC CON REL LCL SHR EXE NORD NOWRT OCTA

12 NOPIC CON REL LCL NOSHR NOEXE RD WRT OCTA

260

ENTRY POINTS

Address Name

2-00000000 SIMPLE$MAIN

VARIABLES

Address Type Name

3-00000008 I*4 I

2–104 Compiling HP Fortran Programs

Example 2–2 Sample Listing of Source Code on OpenVMS Alpha

RELAX2 Source Listing 19-DEC-2004 16:12:46 HP Fortran V8.x-xxxx Page 1

12-DEC-2004 10:41:04 F90$DISK:[TUCKER]LIST_EX.F90;3

1 SUBROUTINE RELAX2(EPS)

2 INTEGER, PARAMETER :: M=40

INTEGER, PARAMETER :: N=60

COMMON X (M,N)

7 LOGICAL DONE

8 10 DONE = .TRUE.

DO J=1,N-1

DO I=1,M-1

XNEW = (X(I-1,J)+X(I+1,J)+X(I,J-1)+X(I,J+1))/4

IF (ABS(XNEW-X(I,J)) > EPS) DONE = .FALSE.

X(I,J) = XNEW

END DO

IF (.NOT. DONE) GO TO 10

RETURN

END SUBROUTINE

Compiler-generated line numbers appear in the left margin and are used with the %LINE prefix in debugger commands. These compiler-generated line numbers are displayed by compiler-generated messages and certain run-time error messages. (For more information on messages, see Appendix C.)

2.7.2 Machine Code Section

The machine code section of a compiler output listing provides a symbolic representation of the compiler-generated object code. The representation of the generated code and data is similar to that of a MACRO assembly listing.

The machine code section is optional. To receive a listing file with a machine code section, you must specify the following:

$ FORTRAN/LIST/MACHINE_CODE

Example 2–3 shows a sample of part of a machine code section of a compiler output listing for OpenVMS I64 systems.

Compiling HP Fortran Programs 2–105

Example 2–3 Sample (Partial) Listing of Machine Code on OpenVMS I64

SIMPLE$MAIN$BLK Machine Code Listing 26-OCT-2004 15:29:34 HP Fortran V8.0-48291 Page 2

26-OCT-2004 15:29:26 DISK$DKA100:[USERNAME.BUG]SIMPLE.F90;1

.psect $CODE$, CON, LCL, SHR, EXE, NOWRT, NOVEC, NOSHORT

.proc

MAIN__

.align 32

.global

MAIN__

.personality

DFOR$HANDLER

MAIN__:

.handlerdata

-32

// 000002

{ .mii

002C0081A980

0119F8C80300

0108001009C0

}

0000

0001

0002 alloc adds mov r38 = rspfs, 0, 8, 5, 0 sp = -64, sp r39 = gp ;;

// r12 = -64, r12

// r39 = r1

{ .mib

010800C40080

000188000940

004000000000

}

{ .mii

008CC0200000

0120001000C0

012000002640

}

{ .mmi

0010

0011

0012

0020

0021

0022 adds mov nop.b

0 ;; st8 add mov r2 = 32, sp // r2 = 32, r12 r37 = rp

[r2] = r0

// r37 = br0 r3 = @ltoff($LITERAL$+16), gp // r3 = @ltoff($LITERAL$+16), r1 ai = 1 // r25 = 1

012000014880

0080C03000C0

000008000000

}

{ .mfb

010800300A00

000008000000

00A000001000

}

{ .mii

010802700040

012000002640

012000100800

0030

0031

0032

0040

0041

0042 mov ld8 nop.i

0 ;; mov r34 = 10 ;; r3 = $LITERAL$ out0 = r3 nop.f

// r3 = [r3]

// r40 = r3 br.call.sptk.many rp = DFOR$SET_FPE ;; // br0 = DFOR$SET_FPE

0050

0051

0052 mov mov add gp = r39 // r1 = r39 ai = 1 ;; // r25 = 1 r32 = @ltoff($LITERAL$+8), gp ;; // r32 = @ltoff($LITERAL$+8), r1

}

{ .mfb

0080C2000A00

000008000000

00A000001000

010800C208C0

010800C40840

}

{ .mmi

0060

0061

0062

DFOR$SET_REENTRANCY ;;

}

{ .mii

010802700040 0070 mov

0071

0072 ld8 out0 = $LITERAL$ // r40 = [r32] nop.f

0 br.call.sptk.many rp = // br0 = DFOR$SET_REENTRANCY adds adds gp = r39 // r1 = r39 r35 = 16, sp // r35 = 16, r12 r33 = 32, sp // r33 = 32, r12

// 000003

(continued on next page)

2–106 Compiling HP Fortran Programs

Example 2–3 (Cont.) Sample (Partial) Listing of Machine Code on OpenVMS I64

01200000A640

012000100900

010800C20B00

}

{ .mlx

0119F80FCA40

000000000002

019FF20015

}

{ .mii

0080C2400AC0

010800C40A00

000008000000

}

0080

0081

0082

0090

0091

00A0

00A1

00A2 mov add adds adds movl ai = 5 ;; out4 = 16, sp out1 = -2, r0 ld8.mov out3 = [r36], $LITERAL$ adds out0 = 32, sp // r40 = 32, r12 nop.i

0 ;;

// r25 = 5 r36 = @ltoffx($LITERAL$), gp // r36 = @ltoffx($LITERAL$), r1

// r44 = 16, r12

// r41 = -2, r0 out2 = 8716160 ;; // r42 = 8716160

{ .mmb

008C82344000

008C82100000

00A000001000

00B0

00B1

00B2 st4 st4

[r35] = r34

[r33] = r0 br.call.sptk.many rp =

DFOR$WRITE_SEQ_LIS ;;

}

{ .mii

012000002200

010802700040

00C0

00C1

00C2 mov mov mov.i

r8 = 1 gp = r39 rspfs = r38 ;;

// br0 = DFOR$WRITE_SEQ_LIS

// 000004

// r1 = r39 // 000003

// 000004 00015404C000

}

{ .mib

010800C80300 00D0

000E0014A000

000108001100

}

00D1

00D2

.endp

MAIN__ adds sp = 64, sp // r12 = 64, r12 mov rp = r37 // br0 = r37 br.ret.sptk.many rp ;; // br0

Routine Size: 224 bytes, Routine Base: $CODE$ + 0000

00010109

00000000

00200000

00000000

.psect $SBSS$, CON, LCL, NOSHR, NOEXE, WRT, NOVEC, SHORT

.lcomm

var$0004, 1, 1

.lcomm

fill$$1, 11, 16

.psect $LITERAL$, CON, LCL, SHR, NOEXE, NOWRT, NOVEC, NOSHORT

0000 string "\X09\X01\X01\X00" data8 0x0 // data8 0 0008

000C

0010

0014 data8 0x200000 // data8 2097152

The following list explains how generated code and data are represented in machine code listings on OpenVMS I64 systems:

• Machine instruction bundles are marked by curly braces, and the bundle type is at the top after the open brace.

Compiling HP Fortran Programs 2–107

• Machine instructions in a bundle are shown in hexadecimal on the far left. The next column to the right is the hexadecimal address offset of the instruction from the routine base address. The next column is a symbolic representation, using memnonics and symbolic operand expressions (such as ‘‘out1’’). The actual operand registers are shown in comments in the next column to the right (such as ‘‘r40’’).

• A predicate register controlling an instruction is shown in parentheses before the mnemonic representation.

• Line numbers corresponding to the generated code are shown on the far right side of the listing.

Example 2–4 shows a sample of part of a machine code section of a compiler output listing for OpenVMS Alpha systems.

Example 2–4 Sample (Partial) Listing of Machine Code on OpenVMS Alpha

RELAX2 Machine Code Listing 19-DEC-2004 16:12:46 HP Fortran V8.x-xxxx Page 3

12-DEC-2004 10:41:04 F90$DISK:[TUCKER]LIST_EX.F90;3

.PSECT $CODE$, OCTA, PIC, CON, REL, LCL, SHR,-

EXE, NORD, NOWRT

(continued on next page)

2–108 Compiling HP Fortran Programs

Example 2–4 (Cont.) Sample (Partial) Listing of Machine Code on OpenVMS Alpha

0000 RELAX2::

23DEFFC0

80100000

0000

0004

LDA SP, -64(SP)

LDF F0, (R16)

A41B0020

B77E0000

B75E0008

B7BE0010

9C5E0018

9C7E0020

9C9E0028

0008

000C

0010

0014

0018

001C

0020

LDQ R0, 32(R27)

STQ R27, (SP)

STQ R26, 8(SP)

STQ FP, 16(SP)

STT F2, 24(SP)

STT F3, 32(SP)

STT F4, 40(SP)

9CBE0030

9CDE0038

47FE041D

803B0028

0024 STT F5, 48(SP)

0028 STT F6, 56(SP)

002C MOV SP, FP

0030 LDF F1, 40(R27)

2FFE0000

0034 UNOP

0038 UNOP

2FFE0000 003C UNOP

0040 .10:

2FFE0000

0040 UNOP

0044 UNOP

0048 UNOP

; 000013

; 000012

; 000001

; 000012

; 000008

2FFE0000

203FFFFF

47E77411

47F41412

2FFE0000

40120413

47E4F414

2273FF5C

004C UNOP

0050 MOV -1, DONE ; -1, R1

0054 MOV 59, var$0002 ; 59, R17 ; 000010

0058 MOV 160, R18 ; 000014

2FFE0000 005C UNOP

0060 lab$0004:

2FFE0000

0060

0064

0068

UNOP

; 000010

006C UNOP

0070 ADDQ R0, R18, R19

0074 MOV 39, var$0003 ; 39, R20 ; 000011

0078 LDA R19, -164(R19) ; 000012

2FFE0000 007C UNOP

0080 lab$0008:

2FFE0000

0080

0084

0088

UNOP

2FFE0000

81530008

8193FF64

47FF0418

81730000

81B300A4

81D3000C

8213FF68

823300A8

82730010

82B3FF6C

82D300AC

82F30014

008C

0090

0094

0098

UNOP

LDF F10, 8(R19)

LDF F12, -156(R19)

CLR R24

009C LDF F11, (R19)

00A0 LDF F13, 164(R19)

00A4 LDF F14, 12(R19)

00A8 LDF F16, -152(R19)

00AC

00B0

00B4

00B8

00BC

LDF F17, 168(R19)

LDF F19, 16(R19)

LDF F21, -148(R19)

LDF F22, 172(R19)

LDF F23, 20(R19)

; 000011

; 000013

; 000012

(continued on next page)

Compiling HP Fortran Programs 2–109

Example 2–4 (Cont.) Sample (Partial) Listing of Machine Code on OpenVMS Alpha

8333FF70

835300B0

83730018

00C0 LDF F25, -144(R19)

00C4 LDF F26, 176(R19)

00C8 LDF F27, 24(R19)

Routine Size: 1020 bytes, Routine Base: $CODE$ + 0000

.PSECT $LINK$, OCTA, NOPIC, CON, REL, LCL,-

NOSHR, NOEXE, RD, NOWRT

0000 ; Stack-Frame invocation descriptor

Entry point:

Entry Length:

Registers used:

RELAX2

R0-R1, R16-R25, R27-FP,

Registers saved:

Fixed Stack Size:

00000000

00003F80

0020

0028

FP, F2-F6

.ADDRESS $BLANK

.LONG X^3F80 ; .F_FLOATING 0.2500000

F0-F6, F10-F30

The following list explains how generated code and data are represented in machine code listings on OpenVMS Alpha systems:

• Machine instructions are represented by MACRO mnemonics and syntax.

To enable you to identify the machine code that is generated from a particular line of source code, the compiler-generated line numbers that appear in the source code listing are also used in the machine code listing.

These numbers appear in the right margin, preceding the machine code generated from individual lines of source code.

• The first line contains a .TITLE assembler directive, indicating the program unit from which the machine code was generated:

For a main program, the title is as declared in a PROGRAM statement.

If you did not specify a PROGRAM statement, the main program is titled filename$MAIN, where filename is the name of the source file.

For a subprogram, the title is the name of the subroutine or function.

For a BLOCK DATA subprogram, the title is either the name declared in the BLOCK DATA statement or filename$DATA (by default).

• The lines following .TITLE provide information such as the contents of storage initialized for FORMAT statements, DATA statements, constants, and subprogram argument call lists.

2–110 Compiling HP Fortran Programs

• General registers (0 through 31) are represented by R0 through R31 and floating-point registers are represented by F0 through F31. The relative PC for each instruction or data item is listed at the left margin, in hexadecimal.

• Variables and arrays defined in the source program are shown as they were defined in the program. Offsets from variables and arrays are shown in decimal. (Optimization frequently places variables in registers, so some names may be missing.)

• HP Fortran source labels referenced in the source program are shown with a period prefix ( . ). For example, if the source program refers to label 300, the label appears in the machine code listing as .300. Labels that appear in the source program, but are not referenced or are deleted during compiler optimization, are ignored. They do not appear in the machine code listing unless you specified /NOOPTIMIZE.

• The compiler might generate labels for its own use. These labels appear as L$n or lab$000n, where the value of n is unique for each such label in a program unit.

• Integer constants are shown as signed integer values; real and complex constants are shown as unsigned hexadecimal values preceded by ^X.

• Addresses are represented by the program section name plus the hexadecimal offset within that program section. Changes from one program section to another are indicated by PSECT lines.

2.7.3 Annotations Section

The annotations section of the compiler output listing describes special instructions used for optimizations such as prefetching, inlining, and loop unrolling. It is controlled by the /ANNOTATIONS qualifier. See Section 2.3.5.

Example 2–5 shows the list of annotations that is produced from the following source code:

1 2 3 4 5 6 7

8 9 10 11 12

287 work1=sqrt((xlatt*real(mindex,LONGreal))

**2+(ylatt*real(nindex,LONGreal))**2+(q-p)**2)

288 work2=q-p

Compiling HP Fortran Programs 2–111

Example 2–5 Sample (Partial) Listing of Annotations

1. Software pipelining across 4 iterations; unrolling loop 2 times; steady state estimated 180 cycles; 0 prefetch iterations

2. Unrolling loop 6 times

3. Prefetching MINDEX, 128 bytes ahead

4. Prefetching NINDEX, 128 bytes ahead

5. Prefetching Q, 128 bytes ahead

6. Write-hinting WORK1, distance 128

7. Prefetching P, 128 bytes ahead

8. Software pipelining across 2 iterations; unrolling loop 2 times; steady state estimated 17 cycles; 0 prefetch iterations

9. Prefetching P, 192 bytes ahead

10. Write-hinting WORK2, distance 128

11. Unrolling loop 7 times

12. Prefetching Q, 192 bytes ahead

2.7.4 Storage Map Section

The storage map section of the compiler output listing is printed after each program unit, or library module. It is not generated when a fatal compilation error is encountered.

The storage map section summarizes information in the following categories:

• Program sections

The program section summary describes each program section (PSECT) generated by the compiler. The descriptions include:

PSECT number (used by most of the other summaries)

Name

Size in bytes

Attributes

PSECT usage and attributes are described in Section 13.1.

• Total memory allocated

Following the program sections, the compiler prints the total memory allocated for all program sections compiled in the following form:

Total Space Allocated nnn

• Entry points

The entry point summary lists all entry points and their addresses. If the program unit is a function, the declared data type of the entry point is also included.

2–112 Compiling HP Fortran Programs

• Variables

The variable summary lists all simple variables, with the data type and address of each. If the variable is removed as a result of optimization, a double asterisk (**) appears in place of the address.

• Records

The record summary lists all record variables and derived types. It shows the address, the structure that defines the fields of the individual records or types, and the total size of each record or type.

• Arrays

The array summary is similar to the variable summary. In addition to data type and address, the array summary gives the total size and dimensions of the array. If the array is an adjustable array or assumed-size array, its size is shown as a double asterisk (**), and each adjustable dimension bound is shown as a single asterisk (*).

• Record Arrays

The record array summary is similar to the record summary. The record array summary gives the dimensions of the record or derived-type array in addition to address, defining structure, and total size. If the record or derived-type array is an adjustable array or assumed-size array, its size is shown as a double asterisk (**), and each adjustable dimension bound is shown as a single asterisk (*).

• Labels

The label summary lists all user-defined statement labels. FORMAT statement labels are suffixed with an apostrophe (

’

). If the label address field contains a double asterisk (**), the label was not used or referred to by the compiled code.

• Functions and subroutines

The functions and subroutines summary lists all external routine references made by the source program. This summary does not include references to routines that are dummy arguments, because the actual function or subroutine name is supplied by the calling program.

A heading for an information category is printed in the listing only when entries are generated for that category.

Compiling HP Fortran Programs 2–113

Example 2–6 shows an example of a storage map section.

Example 2–6 Sample Storage Map Section

RELAX2 Source Listing

PROGRAM SECTIONS

Name Bytes Attributes

1 $CODE$

2 $LINK$

3 $BLANK

Total Space Allocated

19-DEC-2004 16:12:46 HP Fortran v8.x-xxxx

12-DEC-2004 10:41:04

Page 1

F90$DISK:[TUCKER]LIST_EX.F90;3

1020 PIC CON REL LCL SHR EXE NORD NOWRT OCTA

44 NOPIC CON REL LCL NOSHR NOEXE RD NOWRT OCTA

9600 NOPIC OVR REL GBL NOSHR NOEXE RD WRT OCTA

10664

ENTRY POINTS

Address Name

1-00000000 RELAX2

VARIABLES

Address Type Name Address Type Name Address Type Name Address Type Name Address Type Name

** L*4 DONE ** R*4 EPS ** I*4 I ** I*4 J ** R*4 XNEW

ARRAYS

Address Type Name

3-00000000 R*4 X

LABELS

Address Label

1-00000040 10

Bytes

9600

Dimensions

(40, 60)

As shown in Example 2–6, a section size is specified as a number of bytes, expressed in decimal. A data address is specified as an offset from the start of a program section, expressed in hexadecimal.

2.7.5 Compilation Summary Section

The final entries on the compiler output listing are the compiler qualifiers and compiler statistics.

The body of the compilation summary contains information about OPTIONS statement qualifiers (if any), FORTRAN command line qualifiers, and compilation statistics.

‘‘Compilation Statistics’’ shows the machine resources used by the compiler.

2–114 Compiling HP Fortran Programs

Example 2–7 shows a sample compilation summary.

Example 2–7 Sample Compilation Summary

COMMAND QUALIFIERS

/ADDRESSING_MODEL=NORMAL

/ALIGNMENT=(COMMONS=(NONATURAL,PACKED,NOSTANDARD,NOMULTILANGUAGE),

RECORDS=NATURAL,NOSEQUENCE)

/ANNOTATIONS=(NOCODE,NODETAIL,NOFEEDBACK,NOINLINING,NOLINKAGES,

NOLOOP_TRANSFORMS,NOLOOP_UNROLLING,NOPREFETCHING,

NOSHRINKWRAPPING,NOSOFTWARE_PIPELINING,NOTAIL_CALLS)

/ARCHITECTURE=GENERIC

/ASSUME=(ACCURACY_SENSITIVE,ALTPARAM,NOBUFFERED_IO,NOBYTERECL,

NODUMMY_ALIASES,NOF77RTL,NOFP_CONSTANT,NOINT_CONSTANT,

NOMINUS0,PROTECT_CONSTANTS,NOSOURCE_INCLUDE,NOUNDERSCORE)

/NOAUTOMATIC

/NOBY_REF_CALL

/CCDEFAULT=DEFAULT

/CHECK=(NOARG_TEMP_CREATED,NOBOUNDS,FORMAT,NOFP_EXCEPTIONS,OUTPUT_CONVERSION,

NOOVERFLOW,POWER,NOUNDERFLOW,NOARG_INFO,NOFP_MODE)

/CONVERT=NATIVE

/DEBUG=(NOSYMBOLS,TRACEBACK)

/NODEFINE

/DOUBLE_SIZE=64

/NOD_LINES

/ERROR_LIMIT=30

/NOEXTEND_SOURCE

/F77

/NOFAST

/FLOAT=IEEE_FLOAT

/GRANULARITY=QUADWORD

/IEEE_MODE=DENORM_RESULTS

/INTEGER_SIZE=32

/MACHINE_CODE

/MATH_LIBRARY=ACCURATE

/NOMODULE

/NAMES=UPPERCASE

/OPTIMIZE=(INLINE=SPEED,LEVEL=4,NOLOOPS,PIPELINE,TUNE=GENERIC,UNROLL=0)

/NOPAD_SOURCE

/REAL_SIZE=32

/NORECURSIVE

/REENTRANCY=NONE

/ROUNDING_MODE=NEAREST

/NOSEPARATE_COMPILATION

/SEVERITY=(WARNING=WARNING)

/SHOW=(NODICTIONARY,NOINCLUDE,MAP,NOPREPROCESSOR)

/SOURCE_FORM=FREE

/STANDARD=NONE

/NOSYNCHRONOUS_EXCEPTIONS

/NOSYNTAX_ONLY

/NOTIE

/VMS

(continued on next page)

Compiling HP Fortran Programs 2–115

Example 2–7 (Cont.) Sample Compilation Summary

/WARNINGS=(ALIGNMENT,NOARGUMENT_CHECKING,NODECLARATIONS,GENERAL,GRANULARITY,NOIGNORE_LOC,

NOTRUNCATED_SOURCE,UNCALLED,UNINITIALIZED,NOUNUSED,USAGE)

/NOANALYSIS_DATA

/NODIAGNOSTICS

/INCLUDE=FORT$INCLUDE:

/LIST=GEMI64$DKA100:[JBISHOP.BUG]SIMPLE.LIS;1

/OBJECT=GEMI64$DKA100:[JBISHOP.BUG]SIMPLE.OBJ;1

/NOLIBRARY

COMPILER: HP Fortran V8.0-xxxxx-xxxxx

COMPILATION STATISTICS

CPU time:

Elapsed time:

Pagefaults:

I/O Count:

0.13 seconds

1.06 seconds

720

2–116 Compiling HP Fortran Programs

Linking and Running HP Fortran Programs

This chapter describes:

• Section 3.1, Linker Overview

• Section 3.2, LINK Command Qualifiers and Messages

• Section 3.3, Running HP Fortran Programs

• Section 3.4, Symbol Table and Traceback Information: Locating Run-Time

Errors

3.1 Linker Overview

The primary functions of the linker are to allocate virtual memory within the executable image, to resolve symbolic references among object modules being linked, to assign values to relocatable global symbols, to perform relocation, and to perform any requested special-purpose tasks. The linker creates an executable or shareable image that you can run on an OpenVMS system.

For any HP Fortran program unit, the object file generated by the compiler may contain calls and references to HP Fortran run-time procedures, which the linker locates automatically in the default system object libraries, such as

IMAGELIB.OLB.

For More Information:

On linker capabilities, default system object libraries, and detailed descriptions of LINK command qualifiers and options, see the HP OpenVMS Linker Utility

Manual.

3.2 LINK Command Qualifiers and Messages

The LINK command initiates the linking of the object file. The command has the following form:

LINK[/command-qualifiers] file-spec[/file-qualifiers]...

Linking and Running HP Fortran Programs 3–1

/command-qualifiers

Specify output file options.

file-spec

Specifies the input object file to be linked.

/file-qualifiers

Specify input file options.

In interactive mode, you can issue the LINK command without a file specification. The system then requests the file specifications with the following prompt:

_File:

You can enter multiple file specifications by separating them with commas

( , ) or plus signs ( + ). When used with the LINK command, the comma has the same effect as the plus sign; a single executable image is created from the input files specified. If no output file is specified, the linker produces an executable image with the same name as that of the first object file and with a file type of EXE.

Table 3–1 lists the linker qualifiers of particular interest to HP Fortran users.

3–2 Linking and Running HP Fortran Programs

Table 3–1 LINK Command Qualifiers

Function Qualifiers

Request output file, define a file specification, and specify whether to create an executable or shareable image.

Allow the executable image to interoperate with nonnative shared libraries.

Request and specify the contents of an image map

(memory allocation) listing.

/EXECUTABLE[=file-spec]

/SHAREABLE[=file-spec]

(see Section 3.2.1.1)

/[NO]NATIVE_ONLY

(see Section 3.2.1.2)

Specify the amount of debugging information.

Indicate the type of input files and request the inclusion of only certain object modules.

Request or disable the searching of default user libraries and system libraries.

Indicate that an input file is a linker options file.

Request a symbol table.

/BRIEF

/[NO]CROSS_REFERENCE

/FULL

/[NO]MAP

(see Section 3.2.1.3)

/[NO]DEBUG

/[NO]TRACEBACK

(see Section 3.2.2)

/INCLUDE=(module-name...)

/LIBRARY

/SELECTIVE_SEARCH as positional qualifier:

/SHAREABLE

(see Section 3.2.3)

/[NO]SYSLIB

/[NO]SYSSHR

/[NO]USERLIBRARY[=table]

/OPTIONS

(see Section 3.2.5)

/[NO]SYMBOL_TABLE[=file-

spec]

(see Section 3.2.4)

Defaults

/EXECUTABLE=name.EXE

where name is the name of the first input file.

/NOSHAREABLE

/NATIVE_ONLY

(see Section 3.2.1)

/NOCROSS_REFERENCE

/NOMAP (interactive)

/MAP=name.MAP (batch) where name is the name of the first input file.

/NODEBUG

/TRACEBACK

Not applicable

/SYSLIB

/SYSSHR

/USERLIBRARY=ALL

Not applicable

/NOSYMBOL_TABLE

3.2.1 Linker Output File Qualifiers

You can use qualifiers on the LINK command line to control the output produced by the linker. You can also specify whether traceback and debugging information is included. (The /DEBUG and /TRACEBACK qualifiers are described in Section 3.2.2.)

Linker output consists of an image file and, optionally, a map file. The qualifiers that control image and map files are described under the headings that follow.

Linking and Running HP Fortran Programs 3–3

3.2.1.1 Image File Qualifiers

The LINK command /[NO]EXECUTABLE and /[NO]SHAREABLE qualifiers control whether the linker creates an executable image, a shareable image, or no image file.

• /EXECUTABLE

If you omit /EXECUTABLE and /SHAREABLE, the default is /EXECUTABLE, and the linker produces an executable image.

To suppress production of an image, specify /NOEXECUTABLE. For example, in the following command, the file CIRCLE.OBJ is linked, but no image is generated:

$ LINK/NOEXECUTABLE CIRCLE

The /NOEXECUTABLE qualifier is useful if you want to verify the results of linking an object file without actually producing the image.

To designate a file specification for an executable image, use the

/EXECUTABLE qualifier in the following form:

/EXECUTABLE=file-spec

For example, the following command links the file CIRCLE.OBJ. The linker generates an executable image named TEST.EXE:

$ LINK/EXECUTABLE=TEST CIRCLE

• /SHAREABLE

A shareable image has all of its internal references resolved, but must be linked with one or more object modules to produce an executable image.

A shareable image file, for example, can contain a library of routines. To create a shareable image, specify the /SHAREABLE qualifier, as shown in the following example:

$ LINK/SHAREABLE CIRCLE

To include a shareable image as input to the linker, you can either use a linker options file or insert the shareable image into a shareable-image library and specify the library as input to the LINK command. By default, the linker automatically searches the system-supplied shareable-image library SYS$LIBRARY:IMAGELIB.OLB after searching any libraries you specify on the LINK command line.

If you specify (or default to) /NOSHAREABLE, the linker creates an executable image, which cannot be linked with other images.

You can also use the /SHAREABLE qualifier in an options file as a positional qualifier (following a file specification).

3–4 Linking and Running HP Fortran Programs

To create a shareable-image library, use the LIBRARIAN command with the /CREATE, /INSERT, and /SHARE qualifiers.

For More Information:

• On creating and populating libraries, see the HP OpenVMS Command

Definition, Librarian, and Message Utilities Manual.

• On libraries searched by the linker, see the HP OpenVMS Linker Utility

Manual.

3.2.1.2 /NATIVE_ONLY Qualifier

The FORTRAN command /[NO]TIE qualifier and the LINK command

/[NO]NATIVE_ONLY qualifier together control whether procedure signature block (PSB) information is placed in the executable image.

The image activator uses the procedure signature block (PSB) information in the executable image to build jackets that allow calls (interoperability) with translated VAX shareable images on Alpha systems, and translated Alpha images on I64 systems. To allow interoperability with translated shareable images, you must:

• Specify the /TIE qualifier on the FORTRAN command line. This places the

PSB information into the object module.

• Specify /NONATIVE_ONLY on the LINK command line. This propagates the PSB information in the object module into the executable image, so the image activator can use it with translated images.

The following command combination creates an executable image for translated image interoperability:

$ FORTRAN/TIE file

$ LINK/NONATIVE_ONLY file

Unless you need the PSB information for calls to translated shareable images, avoid placing PSB information in the executable image to minimize its size for performance reasons.

The default for the FORTRAN command, /NOTIE, results in the PSB information not being placed in the object module. The default for the

LINK command, /NATIVE_ONLY, results in the linker not passing any PSB information present in the object module into the executable image.

For example, the following command combination creates a executable image for native use only (no PSB information in the executable image):

$ FORTRAN/TIE file

$ LINK file

Linking and Running HP Fortran Programs 3–5

The FORTRAN /TIE qualifier places the PSB information in the object module.

By default, the linker does not propagate the PSB information, if found in the object module, to the executable image (default is /NATIVE_ONLY). The same object module might be retained and used in a different application that requires interoperability.

For More Information:

On interoperability, see Section B.6 and the manuals Migrating an Application

from OpenVMS VAX to OpenVMS Alpha and Porting Applications from HP

OpenVMS Alpha to HP OpenVMS Industry Standard 64 for Integrity Servers.

3.2.1.3 Map File Qualifiers

The LINK command /MAP qualifier and its associated qualifiers indicate whether an image map file is to be generated and, if so, the amount of information to be included in the image map file.

The map qualifiers are specified as follows:

(

/BRIEF

/[NO]MAP[=file-spec] /CROSS_REFERENCE

/FULL

)

In interactive mode, the default is to suppress the map; in batch mode, the default is to generate the map.

If you do not include a file specification with the /MAP qualifier, the map file has the name of the first input file and a file type of MAP. It is stored on the default device in the default directory.

The /BRIEF and /FULL qualifiers define the amount of information included in the map file. They function as follows:

• /BRIEF produces a summary of the image’s characteristics and a list of contributing object modules.

• /FULL produces a summary of the image’s characteristics and a list of contributing object modules (as produced by /BRIEF). It also produces a list, in symbol-name order, of global symbols and values (program, subroutine, and common block names, and names declared EXTERNAL) and a summary of characteristics of image sections in the linked image.

If neither /BRIEF nor /FULL is specified, the map file, by default, contains a summary of the image’s characteristics, a list of contributing object modules (as produced by /BRIEF), and a list of global symbols and values, in symbol-name order.

3–6 Linking and Running HP Fortran Programs

You can use the /CROSS_REFERENCE qualifier with either the default or

/FULL map qualifiers to request cross-reference information for global symbols.

This cross-reference information indicates the object modules that define or refer to global symbols encountered during linking. The default is /NOCROSS_

REFERENCE.

For More Information:

On image maps, see the HP OpenVMS Linker Utility Manual.

3.2.2 /DEBUG and /TRACEBACK Qualifiers

The /DEBUG qualifier includes the debugger and places local symbol information (contained in the object modules) in the executable image. The default is /NODEBUG.

When you use the /TRACEBACK qualifier, run-time error messages are accompanied by a symbolic traceback. This shows the sequence of calls that transferred control to the program unit in which the error occurred. If you specify /NOTRACEBACK, this information is not produced. The default is

/TRACEBACK.

If you specify /DEBUG, the traceback capability is automatically included, and the /TRACEBACK qualifier is ignored.

For More Information:

• On the OpenVMS debugger, see Chapter 4.

• On a sample traceback list, see Section 3.4.1.

3.2.3 Linker Input File Qualifiers

The LINK command input file qualifier /LIBRARY identifies the input file as a library file. The LINK command /INCLUDE qualifier specifies the names of one or more object modules in a library to be used as input files. The

/SELECTIVE_SEARCH qualifier indicates that only symbols referenced from previous input files be taken from the specified file’s list of global symbols, rather than all of the input file’s global symbols.

To specify a shareable image as an input file, place the /SHAREABLE positional qualifier after the file specification in a link options file. In contrast to the /SHAREABLE qualifier you use on a LINK command line to create a shareable image, the /SHAREABLE positional qualifier in a link options file specifies a shareable image input file.

Input files can be object files, previously linked shareable files, or library files.

• /LIBRARY

Linking and Running HP Fortran Programs 3–7

The /LIBRARY qualifier specifies that the input file is an object-module or shareable-image library that is to be searched to resolve undefined symbols referenced in other input object modules. The default file type is OLB.

The /LIBRARY qualifier has the following form:

file.type/LIBRARY

• /INCLUDE

The /INCLUDE qualifier specifies that the input file is an object-module or shareable-image library and that the object modules named are the only object modules in the library to be explicitly included as input. In the case of shareable-image libraries, the object module is the shareable-image name.

The /INCLUDE qualifier has the following form:

file.type/INCLUDE=module-name

At least one object module name is required. To specify more than one, enclose the object module names in parentheses and separate the names with commas.

The default file type is OLB. The /LIBRARY qualifier can also be used, with the same file specification, to indicate that the same library is to be searched for unresolved references.

• /SELECTIVE_SEARCH

The /SELECTIVE_SEARCH qualifier specifies that the linker only include those global symbols already referenced from previous input files, instead of all the global symbols defined by the specified input file.

The /SELECTIVE_SEARCH positional qualifier has the following form:

file.OBJ/SELECTIVE_SEARCH

• /SHAREABLE

When used as a positional qualifier in a linker options file, the

/SHAREABLE qualifier specifies that the input file it follows is a shareable image. The /SHAREABLE positional qualifier has the following form:

file.EXE/SHAREABLE

3–8 Linking and Running HP Fortran Programs

For More Information:

• On defining DCL commands, creating libraries, and related topics, see the HP OpenVMS Command Definition, Librarian, and Message Utilities

Manual.

• On linker capabilities and detailed descriptions of LINK command qualifiers and options, see the HP OpenVMS Linker Utility Manual.

3.2.4 Linker Symbol Table Qualifier

The /SYMBOL_TABLE qualifier requests that the symbol table be written to a file.

The qualifier has the following form:

/SYMBOL_TABLE=file-spec

If you omit the file name, the linker uses a default file type of STB.

3.2.5 Linker Options File Qualifier

The /OPTIONS qualifier identifies a file as a linker options file, which contains additional information about the current link operation.

The qualifier has the following form:

file-spec/OPTIONS

The file specification is usually a file with default file type of OPT.

You can use an options file to specify additional information to the linker, including a shared image as input to the linker, declare universal symbols, and other features.

For more information on using an OPTIONS file, see the HP OpenVMS Linker

Utility Manual.

3.2.6 Other Linker Qualifiers

This chapter discusses the more frequently used linker qualifiers. Other linker qualifiers specify additional libraries to be searched or to prevent default libraries from being searched, control image section characteristics and placement, creation of a global symbol table, and other linker operations.

HP Fortran programs should not be linked with certain linker qualifiers, such as /SYSTEM and /PROTECT.

Linking and Running HP Fortran Programs 3–9

3.2.7 Linker Messages

If the linker detects any errors while linking object modules, it displays messages about their cause and severity. If any errors or fatal conditions occur

(severities E or F), the linker does not produce an image file.

Linker messages are descriptive; you do not normally need additional information to determine the specific error. Some of the more common errors that occur during linking are as follows:

• An object module has compilation errors. This error occurs when you attempt to link a object module that had warnings or errors during compilation. Although you can usually link compiled object modules for which the compiler generated messages, you should verify that the object modules actually produce the expected results during program execution.

• The object modules that are being linked define more than one transfer address. The linker generates a warning if more than one main program has been defined. This can occur, for example, when an extra END statement exists in the program. In this case, the image file created by the linker can be run; the entry point to which control is transferred is the first one that the linker finds.

• A reference to a symbol name remains unresolved. This error occurs when you omit required object module or library names on the LINK command line, and the linker cannot locate the definition for a specified global symbol reference.

If an error occurs when you link object modules, you can often correct it simply by reentering the command string and specifying the correct object files or libraries.

You can use the OpenVMS HELP/MESSAGE facility to view error recovery descriptions associated with messages from any OpenVMS facility.

For More Information:

On using the HELP/MESSAGE command, see OpenVMS System Messages:

Companion Guide for Help Message Users.

3.3 Running HP Fortran Programs

This section describes the following considerations for executing HP Fortran programs on an OpenVMS operating system:

• Using the RUN command to execute programs interactively

• Passing status values to the command interpreter

3–10 Linking and Running HP Fortran Programs

3.3.1 RUN Command

The RUN command initiates execution of a program. The command has the following form:

RUN[/[NO]DEBUG] file-spec

You must specify the file name. If you omit optional elements of the file specification, the system automatically provides a default value. The default file type is EXE.

The /DEBUG qualifier allows you to use the debugger, even if you omitted this qualifier on the FORTRAN and LINK command lines. Refer to Section 3.4 for details.

3.3.2 System Processing at Image Exit

When the main program executes an END statement, or when any program unit in the program executes a STOP statement, the image is terminated.

With the OpenVMS operating system, the termination of an image, or image exit, causes the system to perform a variety of clean-up operations during which open files are closed, system resources are freed, and so on.

3.3.3 Interrupting a Program

When you execute the RUN command interactively, you cannot execute any other program images or DCL commands until the current image completes.

However, if your program is not performing as expected—if, for instance, you have reason to believe it is in an endless loop—you can interrupt it by using the Ctrl/Y key sequence. (You can also use the Ctrl/C key sequence, unless your program takes specific action in response to Ctrl/C.) For example:

$ RUN APPLIC

Ctrl/Y

This command interrupts the program APPLIC. After you have interrupted a program, you can terminate it by entering a DCL command that causes another image to be executed or by entering the DCL commands EXIT or

STOP.

Following a Ctrl/Y interruption, you can also force an entry to the debugger by entering the DEBUG command.

Some of the other DCL commands you can enter have no direct effect on the image. After using them, you can resume the execution of the image with the

DCL command CONTINUE. For example:

$ RUN APPLIC

Linking and Running HP Fortran Programs 3–11

Ctrl/Y

$ SHOW LOGICAL INFILE

%SHOW-S-NOTRAN, no translation for logical name INFILE

$ DEFINE INFILE $1$DUA1:[TESTFILES]JANUARY.DAT

$ CONTINUE

As noted previously, you can use Ctrl/C to interrupt your program; in most cases, the effect of Ctrl/C and Ctrl/Y is the same. However, some programs

(including programs you may write) establish particular actions to take to respond to Ctrl/C. If a program has no Ctrl/C handling routine, then Ctrl/C is the same as Ctrl/Y.

For More Information:

• On defining DCL commands, creating libraries, and related topics, see the HP OpenVMS Command Definition, Librarian, and Message Utilities

Manual.

• On commands you can enter following a Ctrl/Y interruption without affecting the current image, see the VMS DCL Concepts Manual.

• On an example of handling Ctrl/C interrupts, see Section F.2.

3.3.4 Returning Status Values to the Command Interpreter

If you run your program as part of a command procedure, it is often useful to return a status value to the command procedure. This indicates whether the program actually executed properly.

To return such a status value, call the EXIT system subroutine rather than terminating execution with a STOP, RETURN, or END statement. The EXIT subroutine can be called from any executable program unit. It terminates your program and returns the value of the argument as the return status value of the program.

When the command interpreter receives a status value from a terminating program, it attempts to locate a corresponding message in a system message file or a user-defined message file. Every message that can be issued by a system program, command, or component, has a unique 32-bit numeric value associated with it. These 32-bit numeric values are called condition symbols.

Condition symbols are described in Section 14.4.3.

The command interpreter does not display messages on completion of a program under the following circumstances:

• The EXIT argument specifies the value 1, corresponding to SUCCESS.

3–12 Linking and Running HP Fortran Programs

• The program does not return a value. If the program terminates with a

RETURN, STOP, or END statement, a value of 1 is always returned and no message is displayed.

For More Information:

On the EXIT subroutine, see the HP Fortran for OpenVMS Language Reference

Manual.

3.4 Symbol Table and Traceback Information: Locating

Run-Time Errors

Both the compiler and the OpenVMS Run-Time Library include facilities for detecting and reporting errors. You can use the OpenVMS Debugger and the traceback facility to help you locate errors that occur during program execution.

3.4.1 Effects of Error-Related Command Qualifiers

At each step in compiling, linking, and executing your program, you can specify command qualifiers that affect how errors are processed.

• At compile time, you can specify the /DEBUG qualifier on the FORTRAN command line to ensure that symbolic information is created for use by the debugger.

• At link time, you can also specify the /DEBUG qualifier on the LINK command line to make the symbolic information available to the debugger.

• At run time, you can specify the /DEBUG qualifier on the RUN command line to invoke the debugger.

Table 3–2 summarizes the /DEBUG and /TRACEBACK qualifiers.

Linking and Running HP Fortran Programs 3–13

Table 3–2 /DEBUG and /TRACEBACK Qualifiers

Command Qualifier Effect

FORTRAN /DEBUG

LINK

RUN

The HP Fortran compiler creates symbolic data needed by the debugger.

Default: /DEBUG=(NOSYMBOLS,TRACEBACK)

/DEBUG Symbolic data created by the HP Fortran compiler is passed to the debugger.

Default: /NODEBUG

/TRACEBACK Traceback information is passed to the debugger.

Traceback will be produced.

Default: /TRACEBACK

/DEBUG Invokes the debugger. The DBG> prompt will be displayed.

Not needed if LINK/DEBUG was specified.

/NODEBUG If /DEBUG was specified in the LINK command line,

RUN/NODEBUG starts program execution without first invoking the debugger.

If an exception occurs and these qualifiers are not specified at any point in the compile-link-execute sequence, a traceback list is generated by default.

To perform symbolic debugging, you must use the /DEBUG qualifier with both the FORTRAN and LINK command lines; you do not need to specify it with the RUN command. If /DEBUG is omitted from either the FORTRAN or

LINK command lines, you can still use it with the RUN command to invoke the debugger. However, any debugging you perform must then be done by specifying virtual addresses rather than symbolic names.

If you linked your program with the debugger, but wish to execute the program without debugger intervention, specify the following command:

$ RUN/NODEBUG program-name

If you specify LINK/NOTRACEBACK, you receive no traceback if there are errors.

3.4.2 Sample Source Program and Traceback

Example 3–1 shows a sample source program and a traceback.

3–14 Linking and Running HP Fortran Programs

Example 3–1 Sample HP Fortran Program

PROGRAM TRACE_TEST

REAL ST

ST = 2.4E20

! Constant inside range for REAL*4 formats

CALL SUB1(ST)

END PROGRAM TRACE_TEST

SUBROUTINE SUB1(RV)

REAL RV,RES

RV = RV * RV ! Generates overflow value

RES=LOG(RV) ! Uses + Infinity value for IEEE floating-point data

RETURN

END SUBROUTINE SUB1

The program (TRACEBK.F90) shown in Example 3–1 is compiled, linked, and run to generate the traceback information shown after the RUN command:

$ FORTRAN/NOOPTIMIZ/DEBUG=TRACEBACK/SYNCHRONOUS_EXCEPTIONS/

FLOAT=IEEE_FLOAT TRACEBK.F90

$ LINK TRACEBK

$ RUN TRACEBK

%SYSTEM-F-HPARITH, high performance arithmetic trap, Imask=00000000,

Fmask=00000001, summary=08, PC=0002007C, PS=0000001B

-SYSTEM-F-FLTOVF, arithmetic trap,floating overflow at PC=0002007C,PS=0000001B

%TRACE-F-TRACEBACK, symbolic stack dump follows

Image Name Module Name

LINK_TRACEBA TRACE_TEST

Routine Name Line Number rel PC

SUB1 10 0000007C abs PC

0002007C

TRACE_TEST 6 00000030 00020030

0 88EEFA50 88EEFA50

On the FORTRAN command line, the following qualifiers are used:

• /NOOPTIMIZE prevents optimizations that might prevent accurate reporting of information.

• /DEBUG=TRACEBACK, the default, ensures there is sufficient traceback information in the object file.

• /SYNCHRONOUS_EXCEPTIONS (Alpha only) ensures that exceptions reporting will be precise (reported at the statement line causing the error).

• /FLOAT=IEEE_FLOAT requests use of IEEE floating-point data types in memory.

Linking and Running HP Fortran Programs 3–15

When an error condition is detected, you receive the appropriate message, followed by the traceback information. The Run-Time Library displays a message indicating the nature of the error and the address at which the error occurred (user PC). This is followed by the traceback information, which is presented in inverse order to the calls.

Values can be produced for relative and absolute PC, with no corresponding values for routine name and line. These PC values reflect procedure calls internal to the Run-Time Library.

Of particular interest are the values listed under ‘‘Routine Name’’ and ‘‘Line

Number’’:

• The names under ‘‘Routine Name’’ show which routine or subprogram called the Run-Time Library, which subsequently reported the error.

• The value given for ‘‘Line Number’’ corresponds to the compiler-generated line number in the source program listing.

With this information, you can usually isolate the error in a short time.

If you specify either LINK/DEBUG or RUN/DEBUG, the debugger assumes control of execution and you do not receive a traceback list if an error occurs.

To display traceback information, you can use the debugger command SHOW

CALLS.

You should use the /NOOPTIMIZE qualifier on the FORTRAN command line whenever you use the debugger.

For More Information:

• On the /OPTIMIZE qualifier, see Section 2.3.14.

• On HP Fortran run-time errors, see Chapter 7.

3–16 Linking and Running HP Fortran Programs

Using the OpenVMS Debugger

This chapter describes:

• Section 4.1, Debugger Overview

• Section 4.2, Getting Started with the Debugger

• Section 4.3, Sample Debugging Session

• Section 4.4, Displaying HP Fortran Variables

• Section 4.5, Debugger Command Summary

• Section 4.6, Locating an Exception

• Section 4.7, Locating Unaligned Data

4.1 Debugger Overview

A debugger is a tool that helps you locate run-time errors quickly. It is used with a program that has already been compiled and linked successfully, but does not run correctly. For example, the output may be obviously wrong, or the program goes into an infinite loop or terminates prematurely. The debugger enables you to observe and manipulate the program’s execution interactively so you can locate the point at which the program stopped working correctly.

The OpenVMS Debugger is a symbolic debugger, which means that you can refer to program locations by the symbols (names) you used for those locations in your program—the names of variables, subroutines, labels, and so on. You do not need to use virtual addresses to refer to memory locations.

By issuing debugger commands at your terminal, you can perform the following operations:

• Start, stop, and resume the program’s execution

• Trace the execution path of the program

• Monitor selected locations, variables, or events

Using the OpenVMS Debugger 4–1

• Examine and modify the contents of variables, or force events to occur

• Test the effect of some program modifications without having to edit, recompile, and relink the program

Such techniques allow you to isolate an error in your code much more quickly than you could without the debugger.

Once you have found the error in the program, you can then edit the source code and compile, link, and run the corrected version.

4.2 Getting Started with the Debugger

This section explains how to use the debugger with HP Fortran programs. The section focuses on basic debugger functions, to get you started quickly. It also provides any debugger information that is specific to HP Fortran.

For More Information:

• About the OpenVMS Debugger (not specific to the HP Fortran language), see the HP OpenVMS Debugger Manual.

• On OpenVMS Debugger commands, use online HELP during debugging sessions.

4.2.1 Compiling and Linking a Program to Prepare for Debugging

Before you can use the debugger, you must compile and link your program.

The following example shows how to compile and link a HP Fortran program

(consisting of a single compilation unit in the file INVENTORY.F90) prior to using the debugger.

$ FORTRAN/DEBUG/NOOPTIMIZE INVENTORY

$ LINK/DEBUG INVENTORY

The /DEBUG qualifier on the FORTRAN command line causes the compiler to write the debug symbol records associated with INVENTORY.F90 into the object module INVENTORY.OBJ. These records allow you to use the names of variables and other symbols declared in INVENTORY.F90 in debugger commands. (If your program has several compilation units, each of the program units that you want to debug must be compiled with the /DEBUG qualifier.)

Use the /NOOPTIMIZE qualifier when you compile a program in preparation for debugging. Otherwise, the object code is optimized (to reduce the size of the program and make it run faster), so that the symbolic evaluation of some program locations may be inconsistent with what you might expect from viewing the source code. For example, a variable in an optimized program may not be available. (After debugging the program, recompile it without

4–2 Using the OpenVMS Debugger

the /NOOPTIMIZE qualifier.) For a description of the various optimizations performed by the compiler, see Chapter 5.

The /DEBUG qualifier on the LINK command line causes the linker to include all symbol information that is contained in INVENTORY.OBJ in the executable image. This qualifier also causes the OpenVMS image activator to start the debugger at run time. (If your program has several object modules, you may need to specify the other modules on the LINK command line.)

For More Information:

On the effects of specifying the /DEBUG qualifier on the FORTRAN, LINK, and RUN command lines, see Section 2.3.14 and Section 3.4.

4.2.2 Establishing the Debugging Configuration and Interface

Before invoking the debugger, check that the debugging configuration is appropriate for the kind of program you want to debug.

The configuration depends on the current value of the logical name

DBG$PROCESS. Before invoking the debugger, issue the DCL command

SHOW LOGICAL DBG$PROCESS to determine the current definition of

DBG$PROCESS.

The default configuration is appropriate for almost all programs. To request the default debugging configuration. the logical name DBG$PROCESS is undefined or has the value DEFAULT. For example, the following command shows when DBG$PROCESS is undefined:

$ SHOW LOGICAL DBG$PROCESS

%SHOW-S-NOTRAN, no translation for logical name DBG$PROCESS

To define DBG$PROCESS to have a value of DEFAULT, enter:

$ DEFINE DBG$PROCESS DEFAULT

To remove (deassign) a logical name definition, use the DEASSIGN command.

If the DECwindows Motif product is installed and running on your workstation, by default the OpenVMS Debugger uses the DECwindows Motif interface. To use the character cell interface on a DECwindows system, define the logical:

$ DEFINE/PROCESS DBG$DECW$DISPLAY " "

To define this logical name for multiple users, use other logical name tables.

To enable use of the DECwindows interface, deassign the logical:

$ DEASSIGN/PROCESS DBG$DECW$DISPLAY

Using the OpenVMS Debugger 4–3

The DECwindows interface provides a main window in which portions are updated as the program executes, including the source code, entered commands, and debugger messages. This interface provides pull-down menus and uses the kept debugger (equivalent of DEBUG/KEEP).

The examples in this chapter show the command line (character cell) interface to the OpenVMS Debugger.

The character cell interface to the OpenVMS Debugger provides the following debugging interfaces:

• Screen mode

• Line-oriented mode

Screen mode is activated by pressed PF3 on the keypad (or enter the command

SET MODE SCREEN). Screen mode allows the debugger character cell interface to simultaneously display separate groups of data similar to the

DECwindows interface. For example, your screen might show the source code

(SRC), debugger output (OUT), and debugger command input (PROMPT) displays.

While in screen mode, use the SHOW DISPLAY command to view the predefined displays and the DISPLAY command to define a new display.

To view the keypad definitions in screen mode, press PF2 on the keypad.

To leave screen mode and resume line-oriented mode, press PF1 PF3 (or enter the command SET SCREEN NOSCREEN).

For More Information:

On the DECwindows Motif debugger interface (including a source browser) and screen mode, see the HP OpenVMS Debugger Manual.

4.2.3 Invoking the Debugger

After you compile and link your program and establish the appropriate debugging configuration, you can then invoke the debugger. To do so, enter the

DCL command RUN, specifying the executable image of your program as the parameter. For example, enter the following command to debug the program

INVENTORY:

$ RUN INVENTORY

OpenVMS DEBUG (IA64 Debug64) Version x.x-xxx

4–4 Using the OpenVMS Debugger

%DEBUG-I-INITIAL, language is FORTRAN, module set to INVENTORY

DBG> GO

%DEBUG-I-EXITSTATUS, is ’%SYSTEM-S-NORMAL, normal successful completion’

DBG> EXAMINE N

INVENTORY\N: 4

DBG> EXIT

The diagnostic message that is displayed at the debugger startup indicates that this debugging session is initialized for an HP Fortran program and that the name of the main program unit is INVENTORY. In the initial ‘‘%DEBUG-

I-INITIAL’’ message, the OpenVMS Debugger term ‘‘module’’ is equivalent to an HP Fortran ‘‘procedure.’’

When some qualifiers are used to compile (/WARNINGS=ALIGNMENT or most /CHECK keywords), the debugger does not start up in the main program.

When this happens, enter GO once to get to the beginning of the main program.

The DBG> prompt indicates that you can now enter debugger commands.

At this point, if you enter the GO command, program execution begins and continues until it is forced to pause or stop (for example, if the program prompts you for input or an error occurs).

You can specify the DEBUG command /KEEP qualifier to use the kept debugger. The kept debugger allows you to run one (or more) programs with the RUN command, rerun the last program run with a RERUN command, and connect and disconnect to a running process. For example:

$ DEBUG /KEEP

OpenVMS DEBUG (IA64 Debug64) Version x.x-xxx

DBG> RUN SQUARES

%DEBUG-I-INITIAL, language is FORTRAN, module set to SQUARES

DBG> GO

%DEBUG-I-EXITSTATUS, is ’%SYSTEM-S-NORMAL, normal successful completion’

DBG> RERUN

DBG> STEP stepped to SQUARES\%LINE 4

4: OPEN(UNIT=8, FILE=’DATAFILE.DAT’, STATUS=’OLD’)

DBG> EXAMINE N

DEBUGEX$MAIN\N: 0

DBG> GO

%DEBUG-I-EXITSTATUS, is ’%SYSTEM-S-NORMAL, normal successful completion’

DBG> EX N

DEBUGEX$MAIN\N: 4

DBG> EXIT

For more information on using the debugger and invoking the debugger for other display modes, see the HP OpenVMS Debugger Manual.

Using the OpenVMS Debugger 4–5

4.2.4 Debugger Commands Used Often

You can use the following debugger commands when debugging any program:

• To get help on debugger commands, enter the HELP command.

• To control program execution, enter the GO, STEP, CALL, or EXIT commands. To control whether the STEP command steps into or over a routine (or performs other functions), you can use the SET STEP command or qualifiers to the STEP command (such as STEP/OVER).

• To look at the contents of a location, enter the EXAMINE command.

• To modify the contents of a location, enter the DEPOSIT command.

• To view source lines, you usually use the TYPE command.

• You can use the debugger SPAWN command (followed by the desired DCL command) to execute a DCL command. For instance, if you have some mail messages you need to read, enter the following:

DBG> SPAWN MAIL

For More Information:

• About the types of available debugger commands, see Section 4.5.

• On the available debugger commands, see the HP OpenVMS Debugger

Manual.

4.2.5 Debugger Breakpoints, Tracepoints, and Watchpoints

The OpenVMS Debugger supports breakpoints, tracepoints, and watchpoints to help you find out what happens at critical points in your program.

Set a breakpoint if you want the debugger to stop program execution at a certain point in your program (routine, line number, and so on). After you set a breakpoint and begin program execution, execution stops at the breakpoint, allowing you to look at the contents of program variables to see if they contain the correct values.

Use the following commands to control breakpoints:

• To set a breakpoint, use one of the forms of the SET BREAK commands.

You can also specify an action for the breakpoint, such as displaying the value of a variable.

• To view the currently set breakpoints, use the SHOW BREAK command.

4–6 Using the OpenVMS Debugger

• To cancel a breakpoint, use CANCEL BREAK. You can temporarily deactivate a breakpoint with a DEACTIVATE BREAK command, which you can later activate with an ACTIVATE BREAK command.

Set a tracepoint to request that the debugger display messages when certain parts of your program execute. You can also specify an action for the tracepoint, such as displaying the value of a variable. Unlike breakpoints, execution continues past the tracepoint. For example, a tracepoint lets you see how many times a routine gets called.

Use the following commands to control tracepoints:

• To set a tracepoint, use one of the forms of the SET TRACE commands.

You can also specify an action for the tracepoint, such as displaying the current value of a variable.

• To view the currently set tracepoints, use a SHOW TRACE command.

• To cancel a tracepoint, use a CANCEL TRACE command. You can temporarily deactivate a tracepoint with a DEACTIVATE TRACE command, which you can later activate with an ACTIVATE TRACE command.

Set a watchpoint to request that the debugger stop execution when the values of certain variables (or memory locations) change. A breakpoint stops execution when a certain part of program is reached. In contrast, a watchpoint stops execution when a certain value changes.

The following commands are usually used to control watchpoints:

• To set a watchpoint, use one of the forms of the SET WATCH commands.

You can also specify an action for the watchpoint, such as displaying the value of a variable.

• To view the currently set watchpoints, use the SHOW WATCH command.

• To cancel a watchpoint, use CANCEL WATCH command. You can temporarily deactivate a watchpoint with a DEACTIVATE WATCH command, which you can later activate with an ACTIVATE WATCH command.

Before you set a breakpoint, tracepoint, or watchpoint, you can define the scope to be used (by using the SET SCOPE or SET MODULE command, for instance) or you can add a pathname prefix before a symbol name.

Using the OpenVMS Debugger 4–7

4.2.6 Ending a Debugging Session

To end a debugging session and return to the DCL level, enter EXIT or press

Ctrl/Z:

DBG> EXIT

The following message, displayed during a debugging session, indicates that your program has completed normally:

%DEBUG-I-EXITSTATUS, is ’%SYSTEM-S-NORMAL, normal successful completion’

DBG>

To continue debugging after seeing this message, enter EXIT and start a new debugging session with the DCL RUN command.

If you specified the DEBUG command with the /KEEP qualifier when you invoked the debugger, you can run the same program again from within the debugging session (RERUN) and perform other functions.

4.2.7 Notes on Debugger Support for HP Fortran

In general, the debugger supports the data types and operators of HP Fortran and the other debugger-supported languages. However, the following are language-specific limitations and differences:

• Although the type codes for unsigned integers (BU, WU, LU) are used internally to describe the LOGICAL data types, the debugger treats

LOGICAL variables and values as being signed when used in language expressions.

• The debugger prints the numeric values of LOGICAL variables or expressions instead of .TRUE. or .FALSE. Normally, only the low-order bit of a LOGICAL variable or value is significant (0 is .FALSE. and 1 is

.TRUE.). However, HP Fortran does allow all bits in a LOGICAL value to be manipulated, and LOGICAL values can be used in integer expressions.

For this reason, it is sometimes necessary to see the entire integer value of a LOGICAL variable or expression, which is what the debugger shows.

• Fortran modules (defined by a MODULE statement) are treated as debugger modules. To see whether a module is known to the debugger, use the SHOW MODULE command. To load the symbolic information about the Fortran module into the debugger, use a SET MODULE command (see

Section 4.4.5).

4–8 Using the OpenVMS Debugger

• The default name for a main program unit is filename$MAIN, where

filename is the name of your source file. If filename is larger than 26 characters and a name is not specified in a PROGRAM or BLOCK DATA statement, the name is truncated to 26 characters and $MAIN is appended to form the program name.

• COMPLEX constants such as (1.0, 2.0) are not supported in debugger expressions.

• Floating-point number representation depends on the specified precision

(KIND) and the FORTRAN command /FLOAT qualifier used during compilation:

Single-precision numbers of type REAL (KIND=4) and COMPLEX

(KIND=4) can be represented by the F_float or IEEE S_float format, depending on the FORTRAN command /FLOAT qualifier.

Double-precision numbers of type REAL (KIND=8) and COMPLEX

(KIND=8) can be represented by the D_float, G_float, or IEEE T_float format, depending on the FORTRAN command /FLOAT qualifier.

Extended-precision numbers of type REAL (KIND=16) are always represented in X_float format (based on IEEE).

For More Information:

• About the supported data types and operators of any of the languages, enter the HELP LANGUAGE command at the DBG> prompt.

• On HP Fortran little endian data type representation, see Chapter 8.

• On the FORTRAN /FLOAT qualifier, see Section 2.3.22.

4.3 Sample Debugging Session

Example 4–1 shows a program called SQUARES that requires debugging. The program was compiled and linked without diagnostic messages from either the compiler or the linker. Compiler-assigned line numbers have been added in the example so that you can identify the source lines referenced in the explanatory text.

Using the OpenVMS Debugger 4–9

Example 4–1 Sample Program SQUARES

PROGRAM SQUARES

INTEGER (KIND=4) :: INARR(20), OUTARR(20)

3 ! Read the input array from the data file.

4 OPEN(UNIT=8, FILE=’datafile.dat’, STATUS=’OLD’)

READ(8,*,END=5) N, (INARR(I), I=1,N)

5 CLOSE (UNIT=8)

7 ! Square all nonzero elements and store in OUTARR.

K = 0

DO I = 1, N

IF (INARR(I) .NE. 0) THEN

OUTARR(K) = INARR(I)**2

ENDIF

END DO

15 ! Print the squared output values.

Then stop.

16 PRINT 20, K

17 20 FORMAT (’ Number of nonzero elements is’,I4)

DO I = 1, K

PRINT 30, I, OUTARR(I)

20 30 FORMAT(’ Element’,I4,’ has value’,I6)

21 END DO

22 END PROGRAM SQUARES

The program SQUARES performs the following functions:

Reads a sequence of integer numbers from a data file and saves these numbers in the array INARR (lines 4 and 5). The file DATAFILE.DAT

contains one record with the integer values 4, 3, 2, 5, and 2. The first number (4) indicates the number of data items (array elements) that follow.

Enters a loop in which it copies the square of each nonzero integer into another array OUTARR (lines 9 through 13).

Prints the number of nonzero elements in the original sequence and the square of each such element (lines 16 through 21).

When you run SQUARES, it produces the following output, regardless of the number of nonzero elements in the data file:

$ RUN SQUARES

Number of nonzero elements is 0

The error occurs because variable K, which keeps track of the current index into OUTARR, is not incremented in the loop on lines 9 through 13. The statement K = K + 1 should be inserted just before line 11.

4–10 Using the OpenVMS Debugger

Example 4–2 shows how to start the debugging session and use the debugger to find the error in the program in Example 4–1. Comments keyed to the callouts follow the example.

Example 4–2 Sample Debugging Session Using Program SQUARES

$ FORTRAN/DEBUG/NOOPTIMIZE SQUARES

$ LINK/DEBUG SQUARES

$ SHOW LOGICAL DBG$PROCESS

%SHOW-S-NOTRAN, no translation for logical name DBG$PROCESS

$ RUN SQUARES

OpenVMS DEBUG (IA64 Debug64) Version x.x-xxx

%DEBUG-I-INITIAL, language is FORTRAN, module set to SQUARES

DBG> STEP 5

% stepped to SQUARES\%LINE 9

9: DO 10 I = 1, N

DBG> EXAMINE N,K &

SQUARES\N: 4

SQUARES\K:

DBG> STEP 2

DBG> EXAMINE I,K

’ stepped to SQUARES\%LINE 11

11: OUTARR(K) = INARR(I)**2

(

SQUARES\I: 1

SQUARES\K:

DBG> GO

DBG> DEPOSIT K = 1 )

DBG> SET TRACE/SILENT %LINE 11 DO (DEPOSIT K = K + 1)

Number of nonzero elements is 4

Element 1 has value

Element 2 has value

Element 3 has value 25

Element 4 has value 4

%DEBUG-I-EXITSTATUS, is ’SYSTEM-S-NORMAL, normal successful completion’

DBG> EXIT +@

+A $ EDIT SQUARES.FOR

10:

11:

12:

13:

IF(INARR(I) .NE. 0) THEN

K = K + 1

OUTARR(K) = INARR(I)**2

ENDIF

(continued on next page)

Using the OpenVMS Debugger 4–11

Example 4–2 (Cont.) Sample Debugging Session Using Program SQUARES

$ FORTRAN/DEBUG/NOOPTIMIZE SQUARES

$ LINK/DEBUG SQUARES

$ RUN SQUARES

OpenVMS DEBUG (IA64 Debug64) Version x.x-xxx

%DEBUG-I-INITIAL, language is FORTRAN, module set to SQUARES

DBG> SET BREAK %LINE 12 DO (EXAMINE I,K)

DBG> SHOW BREAK breakpoint at SQUARES\%LINE 12 do (EXAMINE I,K)

DBG> TYPE 7:14 module SQUARES

7: C ! Square all nonzero elements and store in OUTARR.

8: K = 0

10:

11:

12:

DO I = 1, N

IF (INARR(I) .NE. 0) THEN

K = K + 1

OUTARR(K) = INARR(I)**2

13:

14:

DBG> GO break at SQUARES\%LINE 12

12:

SQUARES\I:

SQUARES\K:

DBG> GO

ENDIF

END DO

OUTARR(K) = INARR(I)**2 break at SQUARES\%LINE 12

12: OUTARR(K) = INARR(I)**2

SQUARES\I:

SQUARES\K:

(continued on next page)

4–12 Using the OpenVMS Debugger

Example 4–2 (Cont.) Sample Debugging Session Using Program SQUARES

DBG> GO break at SQUARES\%LINE 12

12:

SQUARES\I:

SQUARES\K:

DBG> GO

OUTARR(K) = INARR(I)**2 break at SQUARES\%LINE 12

12: OUTARR(K) = INARR(I)**2

SQUARES\I:

SQUARES\K:

DBG> GO

Number of nonzero elements is 4

Element 1 has value

Element 2 has value

Element 3 has value 25

Element 4 has value 4

%DEBUG-I-EXITSTATUS, is ’%SYSTEM-S-NORMAL, normal successful completion’

DBG> EXIT +F

The /DEBUG qualifier on the DCL FORTRAN command directs the compiler to write the symbol information associated with SQUARES into the object module, SQUARES.OBJ, in addition to the code and data for the program.

The /NOOPTIMIZE qualifier disables optimization by the FORTRAN compiler, to ensure that the executable code matches the source code of the program. Debugging optimized code can be confusing because the contents of some program locations might be inconsistent with what you would expect from viewing the source code.

" The /DEBUG qualifier on the DCL LINK command causes the linker to include all symbol information that is contained in SQUARES.OBJ in the executable image.

# The SHOW LOGICAL DBG$PROCESS command shows that the logical name DBG$PROCESS is undefined, thus the debugger starts in the default configuration.

$ The DCL command RUN SQUARES starts the debugger, which displays its banner and the debugger prompt, DBG>. You can now enter debugger commands. The informational message identifies the source language of the program (FORTRAN) and the name of the main program unit

(SQUARES).

Using the OpenVMS Debugger 4–13

After the RUN SQUARES command, execution is initially paused at the start of the main program unit (line 1 of SQUARES, in this example).

% You decide to test the values of variables N and K after the READ statement has been executed and the value 0 has been assigned to K.

The command STEP 5 executes 5 source lines of the program. Execution is now paused at line 9. The STEP command ignores source lines that do not result in executable code; also, by default, the debugger identifies the source line at which execution is paused.

& The command EXAMINE N, K displays the current values of N and K.

Their values are correct at this point in the execution of the program.

’ The command STEP 2 executes the program into the loop (lines 9 to 11) that copies and squares all nonzero elements of INARR into OUTARR

( The command EXAMINE I,K displays the current values of I and K.

I has the expected value, 1. But K has the value 0 instead of 1, which is the expected value. To fix this error, K should be incremented in the loop just before it is used in line 11.

)

The DEPOSIT command assigns K the value it should have now: 1.

The SET TRACE command is now used to patch the program so that the value of K is incremented automatically in the loop. The command sets a tracepoint that triggers every time execution reaches line 11:

• The /SILENT qualifier suppresses the

" trace at

" message that would otherwise appear each time line 11 is executed.

• The DO clause issues the DEPOSIT K = K + 1 command every time the tracepoint is triggered.

To test the patch, the GO command starts execution from the current location.

The program output shows that the patched program works properly. The

EXITSTATUS message shows that the program executed to completion.

The EXIT command returns control temporarily to DCL level so that you can correct the source file and recompile and relink the program.

The DCL command EDIT invokes an editor and the source file is edited to add K = K + 1 after line 10, as shown. (Compiler-assigned line numbers have been added to clarify the example.)

+B The revised program is compiled and linked.

4–14 Using the OpenVMS Debugger

+C The RUN SQUARES (DCL command) starts the debugger using the revised program so that its correct execution can be verified.

+D The SET BREAK command sets a breakpoint that triggers every time line

12 is executed. The DO clause displays the values of I and K automatically when the breakpoint triggers.

The SHOW BREAK command displays the currently set breakpoints.

The TYPE 7:14 command displays source lines 7 to 14.

+E The GO command starts execution.

At the first breakpoint, the value of K is 1, indicating that the program is running correctly so far. Each additional GO command shows the current values of I and K. After two GO commands, K is now 3, as expected.

However, I is 4, because one of the INARR elements was zero so that lines

11 and 12 were not executed (and K was not incremented) for that iteration of the DO loop. This confirms that the program is running correctly.

+F The EXIT command ends the debugging session, returning control to DCL level.

4.4 Displaying HP Fortran Variables

You usually display the values of variables by using the debugger EXAMINE command, which accepts numerous qualifiers.

4.4.1 Accessing HP Fortran Common Block Variables

To display common block variables, enter the EXAMINE command followed by the variable names that make up the common block. For example:

DBG> TYPE 1:8

2: PROGRAM TEST

3: INTEGER*4 INT4

4: CHARACTER(LEN=1) CHR

5: COMMON /COM_STRA/ INT4, CHR

6: CHR = ’L’

7: INT4 = 0

8: END PROGRAM TEST

DBG> STEP 3 stepped to TEST\%LINE 8

8: END PROGRAM TEST

DBG> EXAMINE CHR, INT4

TEST\CHR: ’L’

TEST\INT4: 0

Using the OpenVMS Debugger 4–15

4.4.2 Accessing HP Fortran Derived-Type Variables

To display derived-type structure variables, enter the EXAMINE command followed by the derived-type variable name, a period ( . ) (or a %), and the member name. For example:

DBG> TYPE 1:6

1: PROGRAM TEST

TYPE X

INTEGER A(5)

END TYPE X

TYPE (X) Z

DBG> STEP 2

Z%A = 1 stepped to TEST\%LINE 10

10: END PROGRAM TEST

DBG> EXAMINE Z.A

TEST\Z.A(1:5)

(1):

(2):

(3):

(4):

(5):

4.4.3 Accessing HP Fortran Record Variables

To display a field in a record structure, enter the EXAMINE command followed by the record name, a period ( . ), and the field name. To display the entire record structure, enter EXAMINE followed by the record name. For example:

4–16 Using the OpenVMS Debugger

DBG> TYPE 1:9 module TEST

1: PROGRAM TEST

2: STRUCTURE /STRA/

INTEGER*4 INT4

CHARACTER(LEN=1) CHR

END STRUCTURE

RECORD /STRA/ REC 6:

8: REC.CHR = ’L’

9: END PROGRAM TEST

DBG> STEP 2 stepped to TEST\%LINE 11

11: END PROGRAM TEST

DBG> EXAMINE REC.CHR

TEST\REC.CHR: ’L’

DBG> EXAMINE REC.INT4

TEST\REC.INT4: 0

DBG> EXAMINE REC

TEST\REC

INT4:

CHR:

’L’

4.4.4 Accessing HP Fortran Array Variables

To display one or more array elements, enter the EXAMINE command followed by the array name and subscripts in parentheses, as in Fortran source statements. To display the entire array, enter EXAMINE following by the array name. For example:

DBG> TYPE 1:5 module ARRAY1

1: PROGRAM ARRAY1

2: INTEGER (KIND=4) ARRAY1(6)

3: ARRAY1 = 0

4: ARRAY1(1) = 1

5: ARRAY1(2) = 2

DBG> STEP 5 stepped to ARRAY1\%LINE 8

DBG> EXAMINE ARRAY1(1:2)

ARRAY\ARRAY1(1):

ARRAY\ARRAY1(2):

DBG> EXAMINE ARRAY1

ARRAY\ARRAY1(1:6)

(1):

(2):

(3):

(4):

(5):

(6):

Using the OpenVMS Debugger 4–17

4.4.5 Accessing HP Fortran Module Variables

To display a variable defined in a module, enter a SET MODULE command before examining module variables. For example, with a variable named

PINTA defined in a module named MOD1, enter the following EXAMINE command to display its value:

DBG> SET MODULE MOD1

DBG> TYPE 1:6

1: PROGRAM USEMODULE

2: USE MOD1

3: INT4=0

4: INT4(1)=1

5: PINTA = 4

6: END PROGRAM USEMODULE

DBG> STEP 4 stepped to USEMODULE\%LINE 6

6: END PROGRAM USEMODULE

DBG> EXAMINE PINTA

USEMODULE\PINTA: 4

4.5 Debugger Command Summary

The following sections list all the debugger commands and any related DCL commands in functional groupings, along with brief descriptions. See the debugger’s online help for complete details on commands.

During a debugging session, you can get online HELP on any command and its qualifiers by typing the HELP command followed by the name of the command in question. The HELP command has the following form:

HELP command

4.5.1 Starting and Terminating a Debugging Session

$ RUN

$ RUN/[NO]DEBUG

DBG> Ctrl/Z or EXIT

DBG> QUIT

DBG> Ctrl/C

Invokes the debugger if LINK/DEBUG was used.

Controls whether the debugger is invoked when the program is executed.

Ends a debugging session, executing all exit handlers.

Ends a debugging session without executing any exit handlers declared in the program.

Aborts program execution or a debugger command without interrupting the debugging session.

4–18 Using the OpenVMS Debugger

DBG> SET

DBG> SHOW o

ABORT_KEY

$ Ctrl/Y DEBUG

DBG> ATTACH

DBG> SPAWN

$ DEBUG/KEEP

DBG> RUN image-name

DBG> RERUN

Assigns the default Ctrl/C abort function to another Ctrl-key sequence or identifies the Ctrlkey sequence currently defined for the abort function.

The sequence Ctrl/Y DEBUG interrupts a program that is running without debugger control and invokes the debugger.

Passes control of your terminal from the current process to another process (similar to the DCL command ATTACH).

Creates a subprocess; lets you issue DCL commands without interrupting your debugging context (similar to the DCL command SPAWN).

Invokes the kept debugger, which allows certain additional commands to be used, including RUN and RERUN.

When using the kept debugger, runs the specified program.

When using the kept debugger, runs the last program executed again.

4.5.2 Controlling and Monitoring Program Execution

STEP n

SET

SHOW o

STEP

SET

SHOW

CANCEL

ACTIVATE

DEACTIVATE

BREAK

SET

SHOW

CANCEL

ACTIVATE

DEACTIVATE

TRACE

Starts or resumes program execution.

Executes the program up to the next line, instruction, or specified instruction.

Establishes or displays the default qualifiers for the

STEP command.

Sets, displays, cancels, activates, or deactivates breakpoints.

Sets, displays, cancels, activates, or deactivates tracepoints.

Using the OpenVMS Debugger 4–19

> SET

SHOW

CANCEL

ACTIVATE

DEACTIVATE

WATCH

Sets, displays, cancels, activates, or deactivates watchpoints.

SHOW CALLS

SHOW STACK

Identifies the currently active subroutine calls.

Gives additional information about the currently active subroutine calls.

Calls a subroutine.

CALL

4.5.3 Examining and Manipulating Data

EXAMINE

SET MODE [NO]OPERANDS

DEPOSIT

Displays the value of a variable or the contents of a program location

Controls whether the address and contents of the instruction operands are displayed when you examine an instruction.

Changes the value of a variable or the contents of a program location.

Evaluates a language or address expression.

EVALUATE

4.5.4 Controlling Type Selection and Symbolization

(

SET

SHOW

CANCEL

(

SET

SHOW

CANCEL

)

RADIX

TYPE

Establishes the radix for data entry and display, displays the radix, or restores the radix.

Establishes the type for program locations that are not associated with a compiler generated type, displays the type, or restores the type.

SET MODE [NO]G_FLOAT Controls whether double-precision floating-point constants are interpreted as G_FLOAT or D_

FLOAT.

You can also use SET TYPE or EXAMINE commands to define untyped program locations, such as SET TYPE S_FLOAT, EXAMINE/T_

FLOAT, or EXAMINE/X_FLOAT.

4–20 Using the OpenVMS Debugger

4.5.5 Controlling Symbol Lookup

SHOW SYMBOL n

SET o

MODULE

SHOW n

SET

SHOW o

IMAGE

SET MODE [NO]DYNAMIC

(

SET

SHOW

CANCEL

)

SCOPE

Displays symbols in your program

Sets a module by loading its symbol records into the debugger’s symbol table, identifies a set module, or cancels a set module.

Sets a shareable image by loading data structures into the debugger’s symbol table, identifies a set image, or cancels a set image.

Controls whether modules and shareable images are set automatically when the debugger interrupts execution.

Establishes, displays, or restores the scope for symbol lookup.

SET MODE [NO]LINE

SET MODE [NO]SYMBOLIC

Controls whether code locations are displayed as line numbers or routine-name + byte offset.

Controls whether code locations are displayed symbolically or as numeric addresses.

Converts a virtual address to a symbolic address.

SYMBOLIZE

4.5.6 Displaying Source Code

TYPE

EXAMINE/SOURCE

(

SET

SHOW

CANCEL

)

SOURCE

SEARCH n

SET

SHOW o

Displays lines of source code.

Displays the source code at the location specified by the address expression.

Creates, displays, or cancels a source directory search list.

Searches the source code for the specified string.

Establishes or displays the default qualifiers for the SEARCH command.

Using the OpenVMS Debugger 4–21

SET STEP [NO]SOURCE n

SET

SHOW n

SET

SHOW o

MAX_SOURCE_FILES o

MARGINS

Enables or disables the display of source code after a STEP command has been executed or at a breakpoint, tracepoint, or watchpoint.

Establishes or displays the maximum number of source files that may be kept open at one time.

Establishes or displays the left and right margin settings for displaying source code.

4.5.7 Using Screen Mode

SET MODE [NO]SCREEN

SET MODE [NO]SCROLL

DISPLAY

(

SET

SHOW

CANCEL

(

SET

SHOW

CANCEL

)

DISPLAY

WINDOW

SELECT

SHOW SELECT

Enables or disables screen mode.

Controls whether an output display is updated line by line or once per command.

Modifies an existing display.

Creates, identifies, or deletes a display.

Creates, identifies, or deletes a window definition.

SCROLL

SAVE

EXTRACT

EXPAND

MOVE n

SET

SHOW o

TERMINAL n

Ctrl/W

DISPLAY/REFRESH o

Selects a display for a display attribute.

Identifies the displays selected for each of the display attributes.

Scrolls a display.

Saves the current contents of a display and writes it to another display.

Saves a display or the current screen state and writes it to a file.

Expands or contracts a display.

Moves a display across the screen.

Establishes or displays the height and width of the screen.

Refreshes the screen.

4–22 Using the OpenVMS Debugger

4.5.8 Editing Source Code

EDIT n

SET

SHOW o

EDITOR

Invokes an editor during a debugging session.

Establishes or identifies the editor invoked by the

EDIT command.

4.5.9 Defining Symbols

DEFINE

DELETE n

SET

SHOW o

DEFINE

SHOW SYMBOL/DEFINED

4.5.10 Using Keypad Mode

Defines a symbol as an address, command, value, or process group.

Deletes symbol definitions.

Establishes or displays the default qualifier for the

DEFINE command.

Identifies symbols that have been defined.

SET MODE [NO]KEYPAD

DEFINE/KEY

DELETE/KEY

SET KEY

SHOW KEY

Enables or disables keypad mode.

Creates key definitions.

Deletes key definitions.

Establishes the key definition state.

Displays key definitions.

4.5.11 Using Command Procedures and Log Files

DECLARE n

SET

SHOW o

LOG

SET OUTPUT [NO]LOG

SET OUTPUT [NO]SCREEN_LOG

SET OUTPUT [NO]VERIFY

Defines parameters to be passed to command procedures.

Specifies or identifies the debugger log file.

Controls whether a debugging session is logged.

Controls whether, in screen mode, the screen contents are logged as the screen is updated.

Controls whether debugger commands are displayed as a command procedure is executed.

Using the OpenVMS Debugger 4–23

SHOW OUTPUT n

SET

SHOW o

ATSIGN

Displays the current output options established by the SET OUTPUT command.

Establishes or displays the default file specification that the debugger uses to search for command procedures.

Executes a command procedure.

@file-spec

4.5.12 Using Control Structures

FOR

REPEAT

WHILE

Executes a list of commands conditionally.

Executes a list of commands repetitively.

Executes a list of commands conditionally, possibly multiple times.

Exits an enclosing WHILE, REPEAT, or FOR loop.

EXITLOOP

4.5.13 Additional Commands

SET PROMPT

SET OUTPUT [NO]TERMINAL n

SET

SHOW n

SET

SHOW o o

LANGUAGE

EVENT_FACILITY

SHOW EXIT_HANDLERS n

SET

SHOW o

(

DISABLE

ENABLE

SHOW

TASK

)

AST

SET MODE [NO]SEPARATE

Specifies the debugger prompt.

Controls whether debugger output is displayed or suppressed, except for diagnostic messages.

Establishes or displays the current language.

Establishes or identifies the current run-time facility for language-specific events.

Identifies the exit handlers declared in the program.

Modifies the tasking environment or displays task information.

Disables the delivery of ASTs in the program, enables the delivery of ASTs, or identifies whether delivery is enabled or disabled.

Controls whether a separate window is created on a workstation for debugger input and output

(this command has no effect on VT-series terminals).

4–24 Using the OpenVMS Debugger

For More Information:

• On debugger commands and the DECwindows Motif interface, see the HP

OpenVMS Debugger Manual.

• On debugger command syntax, enter the online debugger HELP command.

4.6 Locating an Exception

The OpenVMS Debugger supports the SET BREAK/EXCEPTION and SET

TRACE/EXCEPTION commands to set a breakpoint or tracepoint when an exception occurs. To allow precise reporting of the exception, compile the program using:

• The FORTRAN command qualifier /SYNCHRONOUS_EXCEPTIONS

(Alpha only)

• The FORTRAN command qualifier /CHECK=ALL (in general) or

/CHECK=FP_EXCEPTIONS (if you know it is a floating-point exception)

• The FORTRAN command qualifiers /DEBUG and /NOOPTIMIZE

If you use the FORTRAN command qualifier /FLOAT=IEEE_FLOAT to specify

IEEE floating-point (S_float and T_float) data, you can also use the /IEEE_

MODE qualifier to indicate how exceptions should be handled.

For example, you might use the following commands to create the executable program:

$ FORTRAN/DEBUG/NOOPTIMIZE/FLOAT=IEEE_FLOAT/SYNCHRONOUS_EXC/CHECK=ALL TEST

$ LINK/DEBUG TEST

$ RUN TEST

OpenVMS DEBUG (IA64 Debug64) Version x.x-xxx

%DEBUG-I-INITIAL, language is FORTRAN, module set to SQUARES

%DEBUG-I-NOTATMAIN, enter GO to get to start of main program

DBG> GO " break at routine TEST$MAIN

1: REAL (KIND=4) :: A,B

DBG> SET BREAK/EXCEPTION DO (SHOW CALLS) #

DBG> GO $

Using the OpenVMS Debugger 4–25

%SYSTEM-F-HPARITH, high performance arithmetic trap, Imask=00000000,

Fmask=00000002, summary=08, PC=00020050, PS=0000001B %

-SYSTEM-F-FLTOVF, arithmetic trap,floating overflow at PC=00020050,PS=0000001B break on exception preceding TEST$MAIN\%LINE 3+20

3: B=A*A module name

*TEST$MAIN routine name

TEST$MAIN line

3 rel PC

00000050 abs PC

00020050

00000130 00020130

SHARE$DEC$FORRTL

00000000 000B0A30

00000130 00020130

00000000 84F4BAD8

DBG> TYPE 1:3

DBG> EXIT

REAL (KIND=4) :: A,B

A=2.5138E20

B=A*A

The FORTRAN command line specifies qualifiers that ensure reporting of exceptions and sufficient information for debugging.

The LINK command /DEBUG qualifier requests that debug symbol information be included in the executable image.

" The first debugger GO command is needed because run-time checking was requested.

# The debugger command SET BREAK/EXCEPTION sets a breakpoint for exceptions. If omitted, the exception is not reported.

The second debugger GO command runs the program.

The ‘‘%SYSTEM-F-HPARITH, high performance arithmetic trap’’ message indicates an exception has occurred. The ‘‘-SYSTEM-F-FLTOVF, arithmetic trap, floating overflow’’ message indicates the type of exception. The remaining display (requested by the SHOW CALLS command) shows the routine and line number where the error occurred.

& The TYPE command displays the area of source code associated with the exception.

For More Information:

• On the /SYNCHRONOUS_EXCEPTIONS (Alpha only) qualifier, see

Section 2.3.46.

• On the /IEEE_MODE qualifier, see Section 2.3.24.

• On the /FLOAT qualifier, see Section 2.3.22.

4–26 Using the OpenVMS Debugger

• On other FORTRAN command qualifiers, see Section 2.3 or online DCL

HELP (HELP FORTRAN).

4.7 Locating Unaligned Data

The OpenVMS Debugger supports the SET BREAK/UNALIGNED command to set a breakpoint when unaligned data is accessed. To allow precise reporting of the source code accessing the unaligned data, compile the program using the

FORTRAN command qualifier /SYNCHRONOUS_EXCEPTIONS (Alpha only).

For example, you might use the following commands to create the executable program:

$ FORTRAN/DEBUG/NOOPTIMIZE/SYNCHRONOUS_EXCEPT INV_ALIGN

$ LINK/DEBUG INV_ALIGN

$ RUN INV_ALIGN

OpenVMS DEBUG (IA64 Debug64) Version x.x-xxx

%DEBUG-I-INITIAL, language is FORTRAN, module set to INV_ALIGN

DBG> SET BREAK/UNALIGNED

DBG> GO

Unaligned data access: virtual address = 0003000A, PC = 000200A0

# break on unaligned data trap preceding INV_ALIGN\OOPS\%LINE 10 end 10:

DBG> TYPE 7:9

9: subroutine oops(i4) integer*4 i4 i4 = 1

DBG> EXIT

The FORTRAN command line specifies qualifiers that ensure reporting of exceptions and sufficient information for debugging.

The LINK command /DEBUG qualifier requests that debug symbol information be included in the executable image.

" The debugger command SET BREAK/UNALIGNED sets a breakpoint for unaligned data. If omitted, the unaligned data would not be reported.

# The ‘‘Unaligned data access’’ message indicate the line causing the unaligned data was just before line 10.

The TYPE command is used to display the lines before line 10. In this case, the integer argument whose address is passed to subroutine OOPS is unaligned, resulting in the unaligned access.

Using the OpenVMS Debugger 4–27

For More Information:

• On unaligned data, see Section 5.3.

• On the FORTRAN command /ALIGNMENT qualifier, see Section 2.3.3.

• On other FORTRAN command qualifiers, see Section 2.3 or online DCL

HELP (HELP FORTRAN).

4–28 Using the OpenVMS Debugger

Performance: Making Programs Run

Faster

This chapter describes:

• Section 5.1, Software Environment and Efficient Compilation

• Section 5.2, Analyzing Program Performance

• Section 5.3, Data Alignment Considerations

• Section 5.4, Using Arrays Efficiently

• Section 5.5, Improving Overall I/O Performance

• Section 5.6, Additional Source Code Guidelines for Run-Time Efficiency

• Section 5.7, Optimization Levels: /OPTIMIZE=LEVEL=~ Qualifier

• Section 5.8, Other Qualifiers Related to Optimization

• Section 5.9, Compiler Directives Related to Performance

5.1 Software Environment and Efficient Compilation

Before you attempt to analyze and improve program performance, you should:

• Obtain and install the latest version of HP Fortran, along with performance products that can improve application performance, such as the Compaq

Extended Mathematical Library (CXML).

• If possible, obtain and install the latest version of the OpenVMS operating system and processor firmware for your system.

• Use the FORTRAN command and its qualifiers in a manner that lets the

HP Fortran compiler perform as many optimizations as possible to improve run-time performance.

• Use certain performance capabilities provided by the OpenVMS operating system.

Performance: Making Programs Run Faster 5–1

5.1.1 Install the Latest Version of HP Fortran and Performance

Products

To ensure that your software development environment can significantly improve the run-time performance of your applications, obtain and install the following optional software products:

• The latest version of HP Fortran

New releases of the HP Fortran compiler and its associated run-time libraries may provide new features that improve run-time performance.

The HP Fortran run-time libraries are shipped with the OpenVMS operating system.

If your application will be run on an OpenVMS system other than your program development system, be sure to use the same (or later) version of the OpenVMS operating system on those systems.

You can obtain the appropriate HP Services software product maintenance contract to automatically receive new versions of HP Fortran (or the

OpenVMS operating system). For information on more recent HP Fortran releases, contact the HP Customer Support Center (CSC) if you have the appropriate support contract, or contact your local HP sales representative or authorized reseller.

• Compaq Extended Mathematical Library (CXML) for OpenVMS Alpha

Systems

Calling the Compaq Extended Mathematical Library (CXML) routines and installing the CXML product can make certain applications run significantly faster on OpenVMS Alpha systems. Refer to Chapter 15 for information on CXML.

• Performance and Coverage Analyzer (profiler part of DECset)

You can purchase the Performance and Coverage Analyzer (PCA) product, which performs code profiling. PCA is one of a group of products comprising a development environment available from HP known as

DECset. Other DECset products include the Language-Sensitive Editor

(LSE), Source Code Analyzer (SCA), Code Management System (CMS), and the DEC/Test Manager (DTM).

Use of the Source Code Analyzer (SCA) is supported by using the

/ANALYSIS_DATA qualifier (see Section 2.3.4) to produce an analysis data file.

5–2 Performance: Making Programs Run Faster

• Other system-wide performance products

Other products are not specific to a particular programming language or application, but can improve system-wide performance, such as minimizing disk device I/O.

Adequate process quotas and pagefile space as well as proper system tuning are especially important when running large programs, such as those accessing large arrays.

For More Information:

About system-wide tuning and suggestions for other performance enhancements on OpenVMS systems, see the HP OpenVMS System Manager’s Manual,

Volume 2: Tuning, Monitoring, and Complex Systems.

5.1.2 Compile Using Multiple Source Files and Appropriate FORTRAN

Qualifiers

During the earlier stages of program development, you can use incremental compilation with minimal optimization. For example:

$ FORTRAN /OPTIMIZE=LEVEL=1 SUB2

$ FORTRAN /OPTIMIZE=LEVEL=1 SUB3

$ FORTRAN /OPTIMIZE=LEVEL=1 MAIN

$ LINK MAIN SUB2 SUB3

During the later stages of program development, you should compile multiple source files together and use an optimization level of at least

/OPTIMIZE=LEVEL=4 on the FORTRAN command line to allow more interprocedure optimizations to occur. For instance, the following command compiles all three source files together using the default level of optimization

(/OPTIMIZE=LEVEL=4):

$ FORTRAN MAIN.F90+SUB2.F90+SUB3.F90

$ LINK MAIN.OBJ

Compiling multiple source files using the plus sign ( + ) separator lets the compiler examine more code for possible optimizations, which results in:

• Inlining more procedures

• More complete data flow analysis

• Reducing the number of external references to be resolved during linking

When compiling all source files together is not feasible (such as for very large programs), consider compiling source files containing related routines together with multiple FORTRAN commands, rather than compiling source files individually.

Performance: Making Programs Run Faster 5–3

Table 5–1 shows FORTRAN qualifiers that can improve performance. Most of these qualifiers do not affect the accuracy of the results, while others improve run-time performance but can change some numeric results.

HP Fortran performs certain optimizations unless you specify the appropriate

FORTRAN command qualifiers. Additional optimizations can be enabled or disabled using FORTRAN command qualifiers.

Table 5–1 lists the FORTRAN qualifiers that can directly improve run-time performance.

Table 5–1 FORTRAN Qualifiers Related to Run-Time Performance

Qualifier Names Description and For More Information

/ALIGNMENT=keyword

/ASSUME=NOACCURACY_

SENSITIVE

/ARCHITECTURE=keyword

(Alpha only)

/FAST

/INTEGER_SIZE=nn

Controls whether padding bytes are added between data items within common blocks, derived-type data, and Compaq

Fortran 77 record structures to make the data items naturally aligned.

See Section 5.3.

Allows the compiler to reorder code based on algebraic identities to improve performance, enabling certain optimizations. The numeric results can be slightly different from the default (/ASSUME=ACCURACY_SENSITIVE) because of the way intermediate results are rounded. This slight difference in numeric results is acceptable to most programs.

See Section 5.8.8.

Specifies the type of Alpha architecture code instructions to be generated for the program unit being compiled; it uses the same options (keywords) as used by the /OPTIMIZE=TUNE qualifier (Alpha only) (which controls instruction scheduling).

See Section 2.3.6.

Sets the following performance-related qualifiers:

/ALIGNMENT=(COMMONS=NATURAL, RECORDS=NATURAL,

SEQUENCE) /ARCHITECTURE=HOST, /ASSUME=NOAC-

CURACY_SENSITIVE, /MATH_LIBRARY=FAST (Alpha only), and /OPTIMIZE=TUNE=HOST (Alpha only).

See Section 5.8.3.

Controls the sizes of INTEGER and LOGICAL declarations without a kind parameter.

See Section 2.3.26.

(continued on next page)

5–4 Performance: Making Programs Run Faster

Table 5–1 (Cont.) FORTRAN Qualifiers Related to Run-Time Performance

Qualifier Names Description and For More Information

/MATH_LIBRARY=FAST (Alpha only)

/OPTIMIZE=INLINE=keyword

/OPTIMIZE=LEVEL=n

(n = 0 to 5)

/OPTIMIZE=LOOPS

/OPTIMIZE=PIPELINE

/OPTIMIZE=TUNE=keyword

(Alpha only)

/OPTIMIZE=UNROLL=n

Requests the use of certain math library routines (used by intrinsic functions) that provide faster speed. Using this option causes a slight loss of accuracy and provides less reliable arithmetic exception checking to get significant performance improvements in those functions.

See Section 2.3.30.

Specifies the types of procedures to be inlined. If omitted,

/OPTIMIZE=LEVEL=n determines the types of procedures inlined. Certain INLINE keywords are relevant only for

/OPTIMIZE=LEVEL=1 or higher.

See Section 2.3.35.

Controls the optimization level and thus the types of optimization performed. The default optimization level is /OPTIMIZE=LEVEL=4. Use /OPTIMIZE=LEVEL=5 to activate loop transformation optimizations.

See Section 5.7.

Activates a group of loop transformation optimizations (a subset of /OPTIMIZE=LEVEL=5).

See Section 5.7.

Activates the software pipelining optimization (a subset of

/OPTIMIZE=LEVEL=4).

See Section 5.7.

Specifies the target processor generation (chip) architecture on which the program will be run, allowing the optimizer to make decisions about instruction tuning optimizations needed to create the most efficient code. Keywords allow specifying one particular Alpha processor generation type, multiple processor generation types, or the processor generation type currently in use during compilation. Regardless of the setting of /OPTIMIZE=TUNE=xxxx, the generated code will run correctly on all implementations of the Alpha architecture.

See Section 5.8.6.

Specifies the number of times a loop is unrolled (n) when specified with optimization level /OPTIMIZE=LEVEL=3 or higher. If you omit /OPTIMIZE=UNROLL=n, the optimizer determines how many times loops are unrolled.

See Section 5.7.4.1.

(continued on next page)

Performance: Making Programs Run Faster 5–5

Table 5–1 (Cont.) FORTRAN Qualifiers Related to Run-Time Performance

Qualifier Names Description and For More Information

/REENTRANCY Specifies whether code generated for the main program and any Fortran procedures it calls will be relying on threaded or asynchronous reentrancy.

See Section 2.3.39.

Table 5–2 lists qualifiers that can slow program performance. Some applications that require floating-point exception handling or rounding need to use the /IEEE_MODE and /ROUNDING_MODE qualifiers. Other applications might need to use the /ASSUME=DUMMY_ALIASES qualifier for compatibility reasons. Other qualifiers listed in Table 5–2 are primarily for troubleshooting or debugging purposes.

Table 5–2 Qualifiers that Slow Run-Time Performance

Qualifier Names Description and For More Information

/ASSUME=DUMMY_ALIASES

/CHECK[=keyword]

Forces the compiler to assume that dummy (formal) arguments to procedures share memory locations with other dummy arguments or with variables shared through use association, host association, or common block use.

These program semantics slow performance, so you should specify /ASSUME=DUMMY_ALIASES only for the called subprograms that depend on such aliases.

The use of dummy aliases violates the FORTRAN-77,

Fortran 90, and Fortran 95 standards but occurs in some older programs.

See Section 5.8.9.

Generates extra code for various types of checking at run time. This increases the size of the executable image, but may be needed for certain programs to handle arithmetic exceptions. Avoid using /CHECK=ALL except for debugging purposes.

See Section 2.3.11.

(continued on next page)

5–6 Performance: Making Programs Run Faster

Table 5–2 (Cont.) Qualifiers that Slow Run-Time Performance

Qualifier Names Description and For More Information

/IEEE_MODE=keyword other than /IEEE_MODE=DENORM_

RESULTS (on I64) or /IEEE_

MODE=FAST (on Alpha)

/ROUNDING_MODE=DYNAMIC

/SYNCHRONOUS_EXCEPTIONS

/OPTIMIZE=LEVEL=0,

/OPTIMIZE=LEVEL=1,

/OPTIMIZE=LEVEL=2,

/OPTIMIZE=LEVEL=3

/OPTIMIZE=INLINE=NONE,

/OPTIMIZE=INLINE=MANUAL

On Alpha systems, using /IEEE_MODE=UNDERFLOW_

TO_ZERO slows program execution (like

/SYNCHRONOUS_EXCEPTIONS (Alpha only)). Using

/IEEE_MODE=DENORM_RESULTS slows program execution even more than /IEEE_MODE=UNDERFLOW_

TO_ZERO.

See Section 2.3.24.

Certain rounding modes and changing the rounding mode can slow program execution slightly.

See Section 2.3.40.

Generates extra code to associate an arithmetic exception with the instruction that causes it, slowing program execution. Use this qualifier only when troubleshooting, such as when identifying the source of an exception.

See Section 2.3.46.

Minimizes the optimization level (and types of optimizations). Use during the early stages of program development or when you will use the debugger.

See Section 2.3.35 and Section 5.7.

Minimizes the types of inlining done by the optimizer. Use such qualifiers only during the early stages of program development. The type of inlining optimizations are also controlled by the /OPTIMIZE=LEVEL qualifier.

See Section 2.3.35 and Section 5.7.

For More Information:

• On compiling multiple files, see Section 2.2.1.

• On minimizing external references, see Section 10.2.1.

5.1.3 Process Environment and Related Influences on Performance

Certain DCL commands and system tuning can improve run-time performance:

• Specify adequate process limits and do system tuning.

Especially when compiling or running large programs, check to make sure that process limits are adequate. In some cases, inadequate process limits may prolong compilation or program execution. For more information, see

Section 1.2.

Performance: Making Programs Run Faster 5–7

Your system manager can tune the system for efficient use. For example, to monitor system use during program execution or compilation, a system manager can use the MONITOR command.

For more information on system tuning, see your operating system documentation.

• Redirect scrolled text.

For programs that display a lot of text, consider redirecting text that is usually displayed to SYS$OUTPUT to a file. Displaying a lot of text will slow down execution; scrolling text in a terminal window on a workstation can cause an I/O bottleneck (increased elapsed time) and use some CPU time.

The following commands show how to run the program more efficiently by redirecting output to a file and then displaying the program output:

$ DEFINE /USER FOR006 RESULTS.LIS

$ RUN MYPROG

$ TYPE/PAGE RESULTS.LIS

For More Information:

About system-wide tuning and suggestions for other performance enhancements on OpenVMS systems, see the HP OpenVMS System Manager’s Manual,

Volume 2: Tuning, Monitoring, and Complex Systems.

5.2 Analyzing Program Performance

This section describes how you can:

• Analyze program performance using timings of program execution using

LIB$xxxx_TIMER routines or an equivalent DCL command procedure

(Section 5.2.1)

• Analyze program performance using the optional Performance Coverage

Analyzer tool (Section 5.2.2)

Before you analyze program performance, make sure any errors you might have encountered during the early stages of program development have been corrected.

5–8 Performance: Making Programs Run Faster

**5.2.1 Measuring Performance Using LIB$xxxx_TIMER Routines or**

Command Procedures

You can use LIB$xxxx_TIMER routines or an equivalent DCL command procedure to measure program performance.

Using the LIB$xxxx_TIMER routines allows you to display timing and related statistics at various points in the program as well as at program completion, including elapsed time, actual CPU time, buffered I/O, direct I/O, and page faults. If needed, you can use other routines or system services to obtain and report other information.

You can measure performance for the entire program by using a DCL command procedure (see Section 5.2.1.2). Although using a DCL command procedure does not report statistics at various points in the program, it can provide information for the entire program similar to that provided by the LIB$xxxx_

TIMER routines.

5.2.1.1 The LIB$xxxx_TIMER Routines

Use the following routines together to provide information about program performance at various points in your program:

• LIB$INIT_TIMER stores the current values of specified times and counts for use by LIB$SHOW_TIMER or LIB$STAT_TIMER routines.

• LIB$SHOW_TIMER returns times and counts accumulated since the last call to LIB$INIT_TIMER and displays them on SYS$OUTPUT.

• LIB$STAT_TIMER returns times and counts accumulated since the last call to LIB$INIT_TIMER and stores them in memory.

Run program timings when other users are not active. Your timing results can be affected by one or more CPU-intensive processes also running while doing your timings.

Try to run the program under the same conditions each time to provide the most accurate results, especially when comparing execution times of a previous version of the same program. Use the same CPU system (model, amount of memory, version of the operating system, and so on) if possible.

If you do need to change systems, you should measure the time using the same version of the program on both systems, so you know each system’s effect on your timings.

For programs that run for less than a few seconds, repeat the timings several times to ensure that the results are not misleading. Overhead functions might influence short timings considerably.

Performance: Making Programs Run Faster 5–9

You can use the LIB$SHOW_TIMER (or LIB$STAT_TIMER) routine to return elapsed time, CPU time, buffered I/O, direct I/O, and page faults:

• The elapsed time, which will be greater than the total charged actual

CPU time. Sometimes called ‘‘wall clock’’ time.

• Charged actual CPU time is the amount of actual CPU time used by the process.

• Buffered I/O occurs when an intermediate buffer is used from the system buffer pool, instead of a process-specific buffer.

• Direct I/O is when I/O transfer takes place directly between the process buffer and the device.

• A page fault is when a reference to a page occurs that is not in the process working set.

The HP Fortran program shown in Example 5–1 reports timings for the three different sections of the main program, including accumulative statistics (for a scalar program).

Example 5–1 Measuring Program Performance Using LIB$SHOW_TIMER and LIB$INIT_TIMER

Example use of LIB$SHOW_TIMER to time an HP Fortran program

PROGRAM TIMER

INTEGER TIMER_CONTEXT

DATA TIMER_CONTEXT /0/

Initialize default timer stats to 0

CALL LIB$INIT_TIMER

Sample first section of code to be timed

DO I=1,100

CALL MOM

ENDDO

Display stats

TYPE *,’Stats for first section’

CALL LIB$SHOW_TIMER

Zero second timer context

CALL LIB$INIT_TIMER (TIMER_CONTEXT)

(continued on next page)

5–10 Performance: Making Programs Run Faster

Example 5–1 (Cont.) Measuring Program Performance Using LIB$SHOW_

TIMER and LIB$INIT_TIMER

Sample second section of code to be timed

DO I=1,1000

CALL MOM

ENDDO

Display stats

TYPE *,’Stats for second section’

CALL LIB$SHOW_TIMER (TIMER_CONTEXT)

TYPE *,’Accumulated stats for two sections’

CALL LIB$SHOW_TIMER

Re-Initialize second timer stats to 0

CALL LIB$INIT_TIMER (TIMER_CONTEXT)

Sample Third section of code to be timed

DO I=1,1000

CALL MOM

ENDDO

Display stats

TYPE *,’Stats for third section’

CALL LIB$SHOW_TIMER (TIMER_CONTEXT)

TYPE *,’Accumulated stats for all sections’

CALL LIB$SHOW_TIMER

END PROGRAM TIMER

Sample subroutine performs enough processing so times aren’t all 0.0

SUBROUTINE MOM

COMMON BOO(10000)

DOUBLE PRECISION BOO

BOO = 0.5

! Initialize all array elements to 0.5

DO I=2,10000

BOO(I) = 4.0+(BOO(I-1)+1)*BOO(I)*COSD(BOO(I-1)+30.0)

BOO(I-1) = SIND(BOO(I)**2)

ENDDO

RETURN

END SUBROUTINE MOM

The LIB$xxxx_TIMER routines use a single default time when called without an argument. When you call LIB$xxxx_TIMER routines with an INTEGER argument whose initial value is 0 (zero), you enable use of multiple timers.

Performance: Making Programs Run Faster 5–11

The LIB$INIT_TIMER routine must be called at the start of the timing. It can be called again at any time to reset (set to zero) the values.

In Example 5–1, LIB$INIT_TIMER is:

• Called once at the start of the program without an argument. This initializes what will become accumulated statistics and starts the collection of the statistics. You can think of this as the first timer.

• Called once at the start of each section with the INTEGER context argument TIMER_CONTEXT. This resets the values for the current section to zero and starts the collection of the statistics. You can think of this as the second timer, which gets reset for each section.

The LIB$SHOW_TIMER routine displays the timer values saved by LIB$INIT_

TIMER to SYS$OUTPUT (or to a specified routine). Your program must call

LIB$INIT_TIMER before LIB$SHOW_TIMER at least once (to start the timing).

Like LIB$INIT_TIMER:

• Calling LIB$SHOW_TIMER without any arguments displays the default accumulated statistics.

• Calling LIB$SHOW_TIMER with an INTEGER context variable (TIMER_

CONTEXT) displays the statistics for the current section.

The free-format source file, TIMER.F90, might be compiled and linked as follows:

$ FORTRAN/FLOAT=IEEE_FLOAT TIMER

$ LINK TIMER

When the program is run (on a low-end Alpha system), it displays timing statistics for each section of the program as well as accumulated statistics:

$ RUN TIMER

Stats for first section

ELAPSED: 0 00:00:02.36

CPU: 0:00:02.21

BUFIO: 1 DIRIO: 0 FAULTS: 23

Stats for second section

ELAPSED: 0 00:00:22.31

CPU: 0:00:22.09

BUFIO: 1 DIRIO: 0 FAULTS: 0

Accumulated stats for two sections

ELAPSED: 0 00:00:24.68

CPU: 0:00:24.30

BUFIO: 5 DIRIO: 0 FAULTS: 27

Stats for third section

ELAPSED: 0 00:00:22.24

CPU: 0:00:21.98

BUFIO: 1 DIRIO: 0 FAULTS: 0

Accumulated stats for all sections

ELAPSED: 0 00:00:46.92

CPU: 0:00:46.28

BUFIO: 9 DIRIO: 0 FAULTS: 27

5–12 Performance: Making Programs Run Faster

You might:

• Run the program multiple times and average the results.

• Use different compilation qualifiers to see which combination provides the best performance.

Instead of the LIB$xxxx_TIMER routines (specific to the OpenVMS operating system), you might consider modifying the program to call other routines within the program to measure execution time (but not obtain other process information). For example, you might use HP Fortran intrinsic procedures, such as SYSTEM_CLOCK, DATE_AND_TIME, and TIME.

For More Information:

• On the LIB$ RTL routines, see the HP OpenVMS RTL Library (LIB$)

Manual.

• On HP Fortran intrinsic procedures, see the HP Fortran for OpenVMS

Language Reference Manual.

5.2.1.2 Using a Command Procedure

Some of the information obtained by using the LIB$xxxx_TIMER routines can be obtained using a command procedure. You should be aware of the following:

• Using a command procedure does not require source code modification.

Using LIB$xxxx_TIMER routines requires that you modify the source program.

• Using a command procedure can only provide performance timings and statistics for the entire program. Using LIB$xxxx_TIMER routines provides performance timings and statistics for individual sections of the program and/or the entire program.

Before using a command procedure to measure performance, define a foreign symbol that runs the program to be measured in a subprocess. In the following example, the name of the command procedure is TIMER:

$ TIMER :== SPAWN /WAIT /NOLOG @SYS$LOGIN:TIMER

The command procedure shown in Example 5–2 uses the F$GETJPI lexical function to measure performance statistics and the F$FAO lexical function to report the statistics. Each output line is saved as a logical name, which can be saved by the parent process if needed.

Performance: Making Programs Run Faster 5–13

Example 5–2 Command Procedure that Measures Program Performance

$ verify = ’f$verify(0)

$! Get initial values for stats (this removes SPAWN overhead or the current

$! process values).

$ bio1 = f$getjpi (0, "BUFIO")

$ dio1 = f$getjpi (0, "DIRIO")

$ pgf1 = f$getjpi (0, "PAGEFLTS")

$ vip1 = f$getjpi (0, "VIRTPEAK")

$ wsp1 = f$getjpi (0, "WSPEAK")

$ dsk1 = f$getdvi ("sys$disk:","OPCNT")

$ tim1 = f$time ()

$ set noon

$ tik1 = f$getjpi (0, "CPUTIM")

$ set noverify

$! User command being timed:

$ ’p1’ ’p2’ ’p3’ ’p4’ ’p5’ ’p6’ ’p7’ ’p8’

$ tik2 = f$getjpi (0, "CPUTIM")

$ bio2 = f$getjpi (0, "BUFIO")

$ dio2 = f$getjpi (0, "DIRIO")

$ pgf2 = f$getjpi (0, "PAGEFLTS")

$ vip2 = f$getjpi (0, "VIRTPEAK")

$ wsp2 = f$getjpi (0, "WSPEAK")

$ dsk2 = f$getdvi ("sys$disk:","OPCNT")

$ tim2 = f$time ()

$ tim = f$cvtime("’’f$cvtime(tim2,,"TIME")’-’’f$cvtime(tim1,,"TIME")’",,"TIME")

$ thun = ’f$cvtime(tim,,"HUNDREDTH")

$ tsec = (f$cvtime(tim,,"HOUR")*3600) + (f$cvtime(tim,,"MINUTE")*60) + f$cvtime(tim,,"SECOND")

(continued on next page)

5–14 Performance: Making Programs Run Faster

Example 5–2 (Cont.) Command Procedure that Measures Program Performance

$ bio = bio2 - bio1

$ dio = dio2 - dio1

$ pgf = pgf2 - pgf1

$ dsk = dsk2 - dsk1

$ vip = ""

$ if vip2 .le. vip1 then vip = "*" ! Asterisk means didn’t change (from parent)

$ wsp = ""

$ if wsp2 .le. wsp1 then wsp = "*"

$ tiks = tik2 - tik1

$ secs = tiks / 100

$ huns = tiks - (secs*100)

$ write sys$output ""

$ time$line1 == f$fao("Execution (CPU) sec!5UL.!2ZL

Direct I/O !7UL

Peak working set!7UL!1AS", secs, huns, dio, wsp2, wsp)

$ write sys$output time$line1

$ time$line2 == f$fao("Elapsed (clock) sec!5UL.!2ZL

Buffered I/O!7UL

Peak virtual !7UL!1AS", tsec, thun, bio, vip2, vip)

$ write sys$output time$line2

$ time$line3 == f$fao("Process ID !AS

SYS$DISK I/O!7UL

Page faults f$getjpi(0,"pid"), dsk, pgf)

!7UL", -

$ write sys$output time$line3

$ if wsp+vip .nes. "" then write sys$output -

$ write sys$output ""

(* peak from parent)"

$! Place these output lines in the job logical name table, so the parent

$! can access them (useful for batch jobs to automate the collection).

$ define /job/nolog time$line1 "’’time$line1’"

$ define /job/nolog time$line2 "’’time$line2’"

$ define /job/nolog time$line3 "’’time$line3’"

$ verify = f$verify(verify)

This example command procedure accepts multiple parameters, which include the RUN command, the name of the executable image to be run, and any parameters to be passed to the executable image.

Performance: Making Programs Run Faster 5–15

$ TIMER RUN PROG_TEST

$! User command being timed:

$ RUN PROG_TEST.EXE;

Execution (CPU) sec

Elapsed (clock) sec

Process ID

45.39

45.96

20A00999

Direct I/O

Buffered I/O

SYS$DISK I/O

3 Peak working set 2224

18 Peak virtual 15808

6 Page faults 64

If your program displays a lot of text, you can redirect the output from the program. Displaying text increases the buffered I/O count. Redirecting output from the program will change the times reported because of reduced screen

I/O.

For More Information:

About system-wide tuning and suggestions for other performance enhancements on OpenVMS systems, see the HP OpenVMS System Manager’s Manual,

Volume 2: Tuning, Monitoring, and Complex Systems.

5.2.2 Performance and Coverage Analyzer (PCA)

To generate profiling information, you can use the optional Performance and

Coverage Analyzer (PCA) tool.

Profiling helps you identify areas of code where significant program execution time is spent; it can also identify those parts of an application that are not executed (by a given set of test data).

PCA has two components:

• The Collector gathers performance or test coverage data on the running program and writes that data to a performance data file. You can specify the image to be used (image selection) and characteristics of the data collection (measurement and control selection). Data collection characteristics include:

Program counter (PC) sampling

CPU sampling data

Counts of program execution at a location

Coverage of program locations

Other information

• The Analyzer reads and processes the performance data file and displays the collected data graphically in the form of histograms, tables, and annotated source listings.

5–16 Performance: Making Programs Run Faster

PCA works with related DECset tools LSE and the Test Manager. PCA provides a callable routine interface, as well as a command-line and

DECwindows Motif graphical windowing interface. The following examples demonstrate the character-cell interface.

When compiling a program for which PCA will record and analyze data, specify the /DEBUG qualifier on the FORTRAN command line:

$ FORTRAN /DEBUG TEST_PROG.F90

On the LINK command line, specify the PCA debugging module PCA$OBJ using the Linker /DEBUG qualifier:

$ LINK /DEBUG=SYS$LIBRARY:PCA$OBJ.OBJ TEST_PROG

When you run the program, the PCA$OBJ.OBJ debugging module invokes the

Collector and is ready to accept your input to run your program under Collector control and gather the performance or coverage data:

$ RUN TEST_PROG

PCAC>

You can enter Collector commands, such as SET DATAFILE, SET PC_

SAMPLING, GO, and EXIT.

To run the Analyzer, type the PCA command and specify the name of a performance data file, such as the following:

$ PCA TEST_PROG

PCAA>

You can enter the appropriate Analyzer commands to display the data in the performance data file in a graphic representation.

For More Information:

• On the windowing interface for PCA, see the Guide to Performance and

Coverage Analyzer for VMS Systems.

• On the character-cell interface for PCA, see the Performance and Coverage

Analyzer Command-Line Reference.

5.3 Data Alignment Considerations

The HP Fortran compiler aligns most numeric data items on natural

boundaries to avoid run-time adjustment by software that can slow performance.

Performance: Making Programs Run Faster 5–17

A natural boundary is a memory address that is a multiple of the data item’s size (data type sizes are described in Table 8–1). For example, a REAL

(KIND=8) data item aligned on natural boundaries has an address that is a multiple of 8. An array is aligned on natural boundaries if all of its elements are.

All data items whose starting address is on a natural boundary are naturally

aligned. Data not aligned on a natural boundary is called unaligned data.

Although the HP Fortran compiler naturally aligns individual data items when it can, certain HP Fortran statements (such as EQUIVALENCE) can cause data items to become unaligned (see Section 5.3.1).

Although you can use the FORTRAN command /ALIGNMENT qualifier to ensure naturally aligned data, you should check and consider reordering data declarations of data items within common blocks and structures. Within each common block, derived type, or record structure, carefully specify the order and sizes of data declarations to ensure naturally aligned data. Start with the largest size numeric items first, followed by smaller size numeric items, and then nonnumeric (character) data.

5.3.1 Causes of Unaligned Data and Ensuring Natural Alignment

Common blocks (COMMON statement), derived-type data, and Compaq

Fortran 77 record structures (STRUCTURE and RECORD statements) usually contain multiple items within the context of the larger structure.

The following declaration statements can force data to be unaligned:

• Common blocks (COMMON statement)

The order of variables in the COMMON statement determines their storage order.

Unless you are sure that the data items in the common block will be naturally aligned, specify either /ALIGNMENT=COMMONS=STANDARD or /ALIGNMENT=COMMONS=NATURAL) (set by specifying /FAST), depending on the largest data size used.

For examples and more information, see Section 5.3.3.1.

• Derived-type (user-defined) data

Derived-type data members are declared after a TYPE statement.

If your data includes derived-type data structures, you should avoid specifying the FORTRAN command qualifier /ALIGNMENT=

RECORDS=PACKED unless you are sure that the data items in derivedtype data structures (and Compaq Fortran 77 record structures) will be naturally aligned.

5–18 Performance: Making Programs Run Faster

If you omit the SEQUENCE statement (and /ALIGNMENT=

RECORDS=PACKED), the /ALIGNMENT=RECORDS=NATURAL qualifier ensures all data items are naturally aligned. This is the default.

If you specify the SEQUENCE statement, the /ALIGNMENT=

RECORDS=NATURAL qualifier is prevented from adding necessary padding to avoid unaligned data (data items are packed). When you use the SEQUENCE statement, you should specify data declaration order such that all data items are naturally aligned, or add the

/ALIGNMENT=RECORDS=SEQUENCE compiler qualifier.

For an example and more information, see Section 5.3.3.2.

• Compaq Fortran 77 record structures (RECORD and STRUCTURE statements)

Compaq Fortran 77 record structures usually contain multiple data items.

The order of variables in the STRUCTURE statement determines their storage order. The RECORD statement names the record structure.

If your data includes Compaq Fortran 77 record structures, you should avoid specifying the FORTRAN command qualifier /ALIGNMENT=RECORDS=

PACKED unless you are sure that the data items in derived-type data and Compaq Fortran 77 record structures will be naturally aligned.

For an example and more information, see Section 5.3.3.3.

• EQUIVALENCE statements

EQUIVALENCE statements can force unaligned data or cause data to span natural boundaries. For more information, see the HP Fortran for

OpenVMS Language Reference Manual.

To avoid unaligned data in a common block, derived-type data, or record structure (extension), use one or both of the following:

• For new programs or for programs where the source code declarations can be modified easily, plan the order of data declarations with care.

For example, you should order variables in a COMMON statement such that numeric data is arranged from largest to smallest, followed by any character data (see the data declaration rules in Section 5.3.3).

• For existing programs where source code changes are not easily done or for array elements containing derived-type or record structures, you can use command line qualifiers to request that the compiler align numeric data by adding padding spaces where needed.

Performance: Making Programs Run Faster 5–19

Other possible causes of unaligned data include unaligned actual arguments and arrays that contain a derived-type structure or Compaq Fortran 77 record structure.

When actual arguments from outside the program unit are not naturally aligned, unaligned data access will occur. HP Fortran assumes all passed arguments are naturally aligned and has no information at compile time about data that will be introduced by actual arguments during program execution.

For arrays where each array element contains a derived-type structure or

Compaq Fortran 77 record structure, the size of the array elements may cause some elements (but not the first) to start on an unaligned boundary.

Even if the data items are naturally aligned within a derived-type structure without the SEQUENCE statement or a record structure, the size of an array element might require use of the FORTRAN /ALIGNMENT qualifier to supply needed padding to avoid some array elements being unaligned.

If you specify /ALIGNMENT=RECORDS=PACKED (or equivalent qualifiers), no padding bytes are added between array elements. If array elements each contain a derived-type structure with the SEQUENCE statement, array elements are packed without padding bytes regardless of the FORTRAN command qualifiers specified. In this case, some elements will be unaligned.

When /ALIGNMENT=RECORDS=NATURAL is in effect (default), the number of padding bytes added by the compiler for each array element is dependent on the size of the largest data item within the structure. The compiler determines the size of the array elements as an exact multiple of the largest data item in the derived-type structure without the SEQUENCE statement or a record structure. The compiler then adds the appropriate number of padding bytes.

For instance, if a structure contains an 8-byte floating-point number followed by a 3-byte character variable, each element contains five bytes of padding

(16 is an exact multiple of 8). However, if the structure contains one 4-byte floating-point number, one 4-byte integer, followed by a 3-byte character variable, each element would contain one byte of padding (12 is an exact multiple of 4).

For More Information:

On the FORTRAN command /ALIGNMENT qualifier, see Section 5.3.4.

5–20 Performance: Making Programs Run Faster

5.3.2 Checking for Inefficient Unaligned Data

During compilation, the HP Fortran compiler naturally aligns as much data as possible. Exceptions that can result in unaligned data are described in

Section 5.3.1.

Because unaligned data can slow run-time performance, it is worthwhile to:

• Double-check data declarations within common block, derived-type data, or record structures to ensure all data items are naturally aligned (see the data declaration rules in Section 5.3.3). Using modules to contain data declarations can ensure consistent alignment and use of such data.

• Avoid the EQUIVALENCE statement or use it in a manner that cannot cause unaligned data or data spanning natural boundaries.

• Ensure that passed arguments from outside the program unit are naturally aligned.

• Check that the size of array elements containing at least one derived-type data or record structure (extension) cause array elements to start on aligned boundaries (see Section 5.3.1).

There are two ways unaligned data might be reported:

• During compilation

During compilation, warning messages are issued for any data items that are known to be unaligned (unless you specify the

/WARN=NOALIGNMENTS qualifier).

• During program execution by using the debugger

On Alpha systems, compile the program with the /SYNCHRONOUS_

EXCEPTIONS (Alpha only) qualifier (along with /DEBUG and

/NOOPTIMIZE) to request precise reporting of any data that is detected as unaligned.

Use the debugger (SET BREAK/UNALIGNED) command as described in

Section 4.7 to check where the unaligned data is located.

For More Information:

On the /WARNINGS qualifier, see Section 2.3.51.

Performance: Making Programs Run Faster 5–21

5.3.3 Ordering Data Declarations to Avoid Unaligned Data

For new programs or when the source declarations of an existing program can be easily modified, plan the order of your data declarations carefully to ensure the data items in a common block, derived-type data, record structure, or data items made equivalent by an EQUIVALENCE statement will be naturally aligned.

Use the following rules to prevent unaligned data:

• Always define the largest size numeric data items first.

• Add small data items of the correct size (or padding) before otherwise unaligned data to ensure natural alignment for the data that follows.

• If your data includes a mixture of character and numeric data, place the numeric data first.

Using the suggested data declaration guidelines minimizes the need to use the

/ALIGNMENT qualifier to add padding bytes to ensure naturally aligned data.

In cases where the /ALIGNMENT qualifier is still needed, using the suggested data declaration guidelines can minimize the number of padding bytes added by the compiler.

5.3.3.1 Arranging Data Items in Common Blocks

The order of data items in a COMMON statement determines the order in which the data items are stored. Consider the following declaration of a common block named X:

LOGICAL (KIND=2) FLAG

INTEGER IARRY_I(3)

CHARACTER(LEN=5) NAME_CH

COMMON /X/ FLAG, IARRY_I(3), NAME_CH

As shown in Figure 5–1, if you omit the appropriate FORTRAN command qualifiers, the common block will contain unaligned data items beginning at the first array element of IARRY_I.

5–22 Performance: Making Programs Run Faster

0 2

Figure 5–1 Common Block with Unaligned Data

6 10 14

NAME_CH

FLAG IARRY_I(1) IARRY_I(2) IARRY_I(3)

19 (byte offset)

1 byte per character

ZK−6659A−GE

As shown in Figure 5–2, if you compile the program units that use the common block with the /ALIGNMENT=COMMONS=STANDARD qualifier, data items will be naturally aligned.

Figure 5–2 Common Block with Naturally Aligned Data

FLAG

2 4

IARRY_I(1)

IARRY_I(2)

IARRY_I(3)

NAME_CH

21 (byte offset)

Padding 1 byte per character

ZK−6660A−GE

Because the common block X contains data items whose size is 32 bits or smaller, you can specify the /ALIGNMENT=COMMONS qualifier and still have naturally aligned data. If the common block contains data items whose size might be larger than 32 bits (such as REAL (KIND=8) data), specify

/ALIGNMENT=COMMONS=NATURAL to ensure naturally aligned data.

If you can easily modify the source files that use the common block data, define the numeric variables in the COMMON statement in descending order of size and place the character variable last. This provides more portability, ensures natural alignment without padding, and does not require the FORTRAN command /ALIGNMENT=COMMONS=NATURAL (or equivalent) qualifier:

LOGICAL (KIND=2) FLAG

INTEGER IARRY_I(3)

CHARACTER(LEN=5) NAME_CH

COMMON /X/ IARRY_I(3), FLAG, NAME_CH

As shown in Figure 5–3, if you arrange the order of variables from largest to smallest size and place character data last, the data items will be naturally aligned.

Performance: Making Programs Run Faster 5–23

Figure 5–3 Common Block with Naturally Aligned Reordered Data

0 4 8 12 14

NAME_CH

IARRY_I(1) IARRY_I(2) IARRY_I(3) FLAG

19 (byte offset)

1 byte per character

ZK−7915A−GE

When modifying or creating all source files that use common block data, consider placing the common block data declarations in a module so the declarations are consistent. If the common block is not needed for compatibility

(such as file storage or Compaq Fortran 77 use), you can place the data declarations in a module without using a common block.

5.3.3.2 Arranging Data Items in Derived-Type Data

Like common blocks, derived-type data may contain multiple data items

(members).

Data item components within derived-type data will be naturally aligned on up to 64-bit boundaries, with certain exceptions related to the use of the SEQUENCE statement and FORTRAN qualifiers. See Section 5.3.4 for information about these exceptions.

HP Fortran stores a derived data type as a linear sequence of values, as follows:

• If you specify the SEQUENCE statement, the first data item is in the first storage location and the last data item is in the last storage location. The data items appear in the order in which they are declared. The FORTRAN qualifiers have no effect on unaligned data, so data declarations must be carefully specified to naturally align data.

The /ALIGNMENT=SEQUENCE qualifier specifically aligns data items in a SEQUENCE derived-type on natural boundaries.

• If you omit the SEQUENCE statement, HP Fortran adds the padding bytes needed to naturally align data item components, unless you specify the

/ALIGNMENT=RECORDS=PACKED qualifier.

Consider the following declaration of array CATALOG_SPRING of derived-type

PART_DT:

5–24 Performance: Making Programs Run Faster

MODULE DATA_DEFS

TYPE PART_DT

INTEGER

REAL

IDENTIFIER

WEIGHT

CHARACTER(LEN=15) DESCRIPTION

END TYPE PART_DT

TYPE (PART_DT) CATALOG_SPRING(30)

END MODULE DATA_DEFS

As shown in Figure 5–4, the largest numeric data items are defined first and the character data type is defined last. There are no padding characters between data items and all items are naturally aligned. The trailing padding byte is needed because CATALOG_SPRING is an array; it is inserted by the compiler when the /ALIGNMENT=RECORDS=NATURAL qualifier (default) is in effect.

Figure 5–4 Derived-Type Naturally Aligned Data (in CATALOG_SPRING( ))

0 4 8 DESCRIPTION 23 (byte offset)

IDENTIFIER WEIGHT

1 byte per character

Padding

ZK−6658A−GE

5.3.3.3 Arranging Data Items in Compaq Fortran 77 Record Structures

HP Fortran supports record structures provided by Compaq Fortran

77. Compaq Fortran 77 record structures use the RECORD statement and optionally the STRUCTURE statement, which are extensions to the

FORTRAN-77, Fortran 90, and Fortran 95 standards. The order of data items in a STRUCTURE statement determines the order in which the data items are stored.

HP Fortran stores a record in memory as a linear sequence of values, with the record’s first element in the first storage location and its last element in the last storage location. Unless you specify the

/ALIGNMENT=RECORDS=PACKED qualifier, padding bytes are added if needed to ensure data fields are naturally aligned.

Performance: Making Programs Run Faster 5–25

The following example contains a structure declaration, a RECORD statement, and diagrams of the resulting records as they are stored in memory:

STRUCTURE /STRA/

CHARACTER*1 CHR

INTEGER*4 INT

END STRUCTURE

RECORD /STRA/ REC

Figure 5–5 shows the memory diagram of record REC for naturally aligned records.

Figure 5–5 Memory Diagram of REC for Naturally Aligned Records

0 1 2 3 4

REC.CHR

REC.INT

8 (byte offset)

Padding

Record REC

ZK−2244A−GE

For More Information:

On data declaration statements, see the HP Fortran for OpenVMS Language

Reference Manual.

5.3.4 Qualifiers Controlling Alignment

The following qualifiers control whether the HP Fortran compiler adds padding

(when needed) to naturally align multiple data items in common blocks, derived-type data, and Compaq Fortran 77 record structures:

• Unless you specify /FAST, the default is /ALIGNMENT=COMMONS=-

PACKED or arbitrary byte alignment of common block data. In this case, unaligned data can occur unless the order of data items specified in the

COMMON statement places the largest numeric data item first, followed by the next largest numeric data (and so on), followed by any character data.

5–26 Performance: Making Programs Run Faster

• The /ALIGNMENT=COMMONS=STANDARD qualifier requests that data in common blocks be aligned on up to 4-byte boundaries, by adding padding bytes as needed.

• The /ALIGNMENT=COMMONS=NATURAL qualifier requests that data in common blocks be aligned on up to 8-byte boundaries, by adding padding bytes as needed.

If you specify /FAST, the default is /ALIGNMENT=COMMONS=NATURAL.

• The /ALIGNMENT=COMMONS=NATURAL qualifier is equivalent to specifying /ALIGNMENT=(COMMONS=(NATURAL,NOMULTILANG-

UAGE), RECORDS=NATURAL).

• The /ALIGNMENT=RECORDS=PACKED qualifier requests that multiple data items in derived-type data and record structures be aligned on byte boundaries instead of being naturally aligned. The default is

/ALIGNMENT=RECORDS=NATURAL.

• The /ALIGNMENT=RECORDS=NATURAL qualifier (default) requests that multiple data items in derived-type data without the SEQUENCE statement record structures be naturally aligned, by adding padding bytes as needed.

• The /ALIGNMENT=NOSEQUENCE qualifier controls alignment of derived types with the SEQUENCE attribute. The default

/ALIGNMENT=NOSEQUENCE qualifier means that derived types with the SEQUENCE attribute are packed regardless of any other alignment rules. Note that /ALIGNMENT=NONE implies /ALIGNMENT=-

NOSEQUENCE.

On the other hand, the /ALIGNMENT=SEQUENCE qualifier means that derived types with the SEQUENCE attribute obey whatever alignment rules are currently in use. Consequently, since /ALIGNMENT=RECORDS is a default value, then /ALIGNMENT=SEQUENCE alone on the command line will cause the fields in these derived types to be naturally aligned. Note that /FAST and /ALIGNMENT=ALL imply

/ALIGNMENT=SEQUENCE.

• The /FAST qualifier controls certain defaults, including alignment (sets

/ALIGNMENT=COMMONS=NATURAL qualifier).

The default behavior is that multiple data items in derived-type data and record structures will be naturally aligned; data items in common blocks will

not be naturally aligned (/ALIGNMENT=(COMMONS=(PACKED, NOMULTI-

LANGUAGE), RECORDS=NATURAL).

Performance: Making Programs Run Faster 5–27

In derived-type data, using the SEQUENCE statement prevents

/ALIGNMENT=RECORDS=NATURAL from adding needed padding bytes to naturally align data items.

For More Information:

On the /ALIGNMENT qualifier, see Section 2.3.3.

5.4 Using Arrays Efficiently

The following sections discuss these topics:

• Accessing arrays efficiently

• Passing arrays efficiently

5.4.1 Accessing Arrays Efficiently

Many of the array access efficiency techniques described in this section are applied automatically by the HP Fortran loop transformation optimizations

(see Section 5.8.1).

Several aspects of array use can improve run-time performance. The following sections describe these aspects.

Array Access

The fastest array access occurs when contiguous access to the whole array or most of an array occurs. Perform one or a few array operations that access all of the array or major parts of an array instead of numerous operations on scattered array elements.

Rather than use explicit loops for array access, use elemental array operations, such as the following line that increments all elements of array variable A:

A = A + 1.

When reading or writing an array, use the array name and not a DO loop or an implied DO-loop that specifies each element number. Fortran 90/95 array syntax allows you to reference a whole array by using its name in an expression. For example:

REAL :: A(100,100)

A = 0.0

A = A + 1.

WRITE (8) A

! Increment all elements of A by 1

! Fast whole array use

5–28 Performance: Making Programs Run Faster

Similarly, you can use derived-type array structure components, such as:

TYPE X

INTEGER A(5)

END TYPE X

TYPE (X) Z

WRITE (8) Z%A ! Fast array structure component use

Multidimensional Arrays

Make sure multidimensional arrays are referenced using proper array syntax and are traversed in the natural ascending order (column major) for

Fortran. With column-major order, the leftmost subscript varies most rapidly with a stride of one. Writing a whole array uses column-major order.

Avoid row-major order, as is done by C, where the rightmost subscript varies most rapidly.

For example, consider the nested DO loops that access a two-dimension array with the J loop as the innermost loop:

INTEGER X(3,5), Y(3,5), I, J

Y = 0

DO I=1,3

DO J=1,5

! I outer loop varies slowest

! J inner loop varies fastest

X (I,J) = Y(I,J) + 1 ! Inefficient row-major storage order

END DO ! (rightmost subscript varies fastest)

END DO

END PROGRAM

Since J varies the fastest and is the second array subscript in the expression X

(I,J), the array is accessed in row-major order.

To make the array accessed in natural column-major order, examine the array algorithm and data being modified.

Using arrays X and Y, the array can be accessed in natural column-major order by changing the nesting order of the DO loops so the innermost loop variable corresponds to the leftmost array dimension:

Performance: Making Programs Run Faster 5–29

INTEGER X(3,5), Y(3,5), I, J

Y = 0

DO J=1,5

DO I=1,3

! J outer loop varies slowest

! I inner loop varies fastest

X (I,J) = Y(I,J) + 1 ! Efficient column-major storage order

END DO ! (leftmost subscript varies fastest)

END DO

END PROGRAM

The Fortran 90/95 whole array access ( X = Y + 1 ) uses efficient column major order. However, if the application requires that J vary the fastest or if you cannot modify the loop order without changing the results, consider modifying the application program to use a rearranged order of array dimensions.

Program modifications include rearranging the order of:

• Dimensions in the declaration of the arrays X(5,3) and Y(5,3)

• The assignment of X(J,I) and Y(J,I) within the DO loops

• All other references to arrays X and Y

In this case, the original DO loop nesting is used where J is the innermost loop:

INTEGER X(5,3), Y(5,3), I, J

Y = 0

DO I=1,3

DO J=1,5

! I outer loop varies slowest

! J inner loop varies fastest

X (J,I) = Y(J,I) + 1 ! Efficient column-major storage order

END DO ! (leftmost subscript varies fastest)

END DO

END PROGRAM

Code written to access multidimensional arrays in row-major order (like C) or random order can often make inefficient use of the CPU memory cache. For more information on using natural storage order during record I/O operations, see Section 5.5.3.

5–30 Performance: Making Programs Run Faster

Array Intrinsic Procedures

Use the available Fortran 90/95 array intrinsic procedures rather than create your own.

Whenever possible, use Fortran 90/95 array intrinsic procedures instead of creating your own routines to accomplish the same task. HP Fortran array intrinsic procedures are designed for efficient use with the various HP Fortran run-time components.

Using the standard-conforming array intrinsics can also make your program more portable.

Noncontiguous Access

With multidimensional arrays where access to array elements will be noncontiguous, avoid leftmost array dimensions that are a power of 2 (such as 256, 512).

Since the cache sizes are a power of 2, array dimensions that are also a power of 2 may make inefficient use of cache when array access is noncontiguous. If the cache size is an exact multiple of the leftmost dimension, your program will probably make little use of the cache. This does not apply to contiguous sequential access or whole array access.

One work-around is to increase the dimension to allow some unused elements, making the leftmost dimension larger than actually needed. For example, increasing the leftmost dimension of A from 512 to 520 would make better use of cache:

REAL A (512,100)

DO I = 2,511

DO J = 2,99

A(I,J)=(A(I+1,J-1) + A(I-1, J+1)) * 0.5

END DO

In this code, array A has a leftmost dimension of 512, a power of 2. The innermost loop accesses the rightmost dimension (row major), causing inefficient access. Increasing the leftmost dimension of A to 520 (REAL A

(520,100)) allows the loop to provide better performance, but at the expense of some unused elements.

Because loop index variables I and J are used in the calculation, changing the nesting order of the DO loops changes the results.

Performance: Making Programs Run Faster 5–31

5.4.2 Passing Array Arguments Efficiently

In HP Fortran, there are two general types of array arguments:

• Explicit-shape arrays used with FORTRAN 77.

These arrays have a fixed rank and extent that are known at compile time.

Other dummy argument (receiving) arrays that are not deferred-shape

(such as assumed-size arrays) can be grouped with explicit-shape array arguments.

• Deferred-shape arrays introduced with Fortran 90.

Types of deferred-shape arrays include array pointers and allocatable arrays. Assumed-shape array arguments generally follow the rules about passing deferred-shape array arguments.

When passing arrays as arguments, either the starting (base) address of the array or the address of an array descriptor is passed:

• When using explicit-shape (or assumed-size) arrays to receive an array, the starting address of the array is passed.

• When using deferred-shape or assumed-shape arrays to receive an array, the address of the array descriptor is passed (the compiler creates the array descriptor).

Passing an assumed-shape array or array pointer to an explicit-shape array can slow run-time performance. This is because the compiler needs to create an array temporary for the entire array. The array temporary is created because the passed array may not be contiguous and the receiving (explicit-shape) array requires a contiguous array. When an array temporary is created, the size of the passed array determines whether the impact on slowing run-time performance is slight or severe.

Table 5–3 summarizes what happens with the various combinations of array types. The amount of run-time performance inefficiency depends on the size of the array.

5–32 Performance: Making Programs Run Faster

Table 5–3 Output Argument Array Types

Input Arguments

Array Types Explicit-Shape Arrays

Explicit-Shape Arrays

Deferred-Shape and

Assumed-Shape

Arrays

Very efficient. Does not use an array temporary.

Does not pass an array descriptor. Interface block optional.

When passing an allocatable array, very efficient. Does not use an array temporary. Does not pass an array descriptor.

Interface block optional.

When not passing an allocatable array, not efficient. Instead use allocatable arrays whenever possible.

Uses an array temporary.

Does not pass an array descriptor. Interface block optional.

Deferred-Shape and Assumed-Shape

Arrays

Efficient. Only allowed for assumedshape arrays (not deferred-shape arrays). Does not use an array temporary. Passes an array descriptor.

Requires an interface block.

Efficient. Requires an assumed-shape or array pointer as dummy argument. Does not use an array temporary. Passes an array descriptor. Requires an interface block.

For More Information:

On arrays and their data declaration statements, see the HP Fortran for

OpenVMS Language Reference Manual.

5.5 Improving Overall I/O Performance

Improving overall I/O performance can minimize both device I/O and actual CPU time. The techniques listed in this section can greatly improve performance in many applications.

A bottleneck determines the maximum speed of execution by being the slowest process in an executing program. In some programs, I/O is the bottleneck that prevents an improvement in run-time performance. The key to relieving I/O bottlenecks is to reduce the actual amount of CPU and I/O device time involved in I/O. Bottlenecks may be caused by one or more of the following:

• A dramatic reduction in CPU time without a corresponding improvement

I/O time results in an I/O bottleneck.

Performance: Making Programs Run Faster 5–33

• By such coding practices as:

Unnecessary formatting of data and other CPU-intensive processing

Unnecessary transfers of intermediate results

Inefficient transfers of small amounts of data

Application requirements

Improved coding practices can minimize actual device I/O, as well as the actual

CPU time.

HP offers software solutions to system-wide problems like minimizing device

I/O delays (see Section 5.1.1).

5.5.1 Use Unformatted Files Instead of Formatted Files

Use unformatted files whenever possible. Unformatted I/O of numeric data is more efficient and more precise than formatted I/O. Native unformatted data does not need to be modified when transferred and will take up less space on an external file.

Conversely, when writing data to formatted files, formatted data must be converted to character strings for output, less data can transfer in a single operation, and formatted data may lose precision if read back into binary form.

To write the array than S

A(25,25) in the following statements, S

1 is more efficient

WRITE (7) A

WRITE (7,100) A

100 FORMAT (25(’ ’,25F5.21))

Although formatted data files are more easily ported to other systems, HP

Fortran can convert unformatted data in several formats (see Chapter 9).

5.5.2 Write Whole Arrays or Strings

The general guidelines about array use discussed in Section 5.4 also apply to reading or writing an array with an I/O statement.

To eliminate unnecessary overhead, write whole arrays or strings at one time rather than individual elements at multiple times. Each item in an I/O list generates its own calling sequence. This processing overhead becomes most significant in implied-DO loops. When accessing whole arrays, use the array name (Fortran 90/95 array syntax) instead of using implied-DO loops.

5–34 Performance: Making Programs Run Faster

5.5.3 Write Array Data in the Natural Storage Order

Use the natural ascending storage order whenever possible. This is columnmajor order, with the leftmost subscript varying fastest and striding by 1 (see

Section 5.4). If a program must read or write data in any other order, efficient block moves are inhibited.

If the whole array is not being written, natural storage order is the best order possible.

5.5.4 Use Memory for Intermediate Results

Performance can improve by storing intermediate results in memory rather than storing them in a file on a peripheral device. One situation that may not benefit from using intermediate storage is a disproportionately large amount of data in relation to physical memory on your system. Excessive page faults can dramatically impede virtual memory performance.

5.5.5 Defaults for Blocksize and Buffer Count

HP Fortran provides OPEN statement defaults for BLOCKSIZE and

BUFFERCOUNT that generally offer adequate I/O performance. The default for BLOCKSIZE and BUFFERCOUNT is determined by SET RMS_DEFAULT command default values.

Specifying a BUFFERCOUNT of 2 (or 3) allows Record Management Services

(RMS) to overlap some I/O operations with CPU operations. For sequential and relative files, specify a BLOCKSIZE of at least 1024 bytes.

Any experiments to improve I/O performance should try to increase the amount of data read by each disk I/O. For large indexed files, you can reduce disk I/O by specifying enough buffers (BUFFERCOUNT) to keep most of the index portion of the file in memory.

For More Information:

• On tuning indexed files and optimal BUFFERCOUNT and BLOCKSIZE values, see the Guide to OpenVMS File Applications.

• On specifying BLOCKSIZE and BUFFERCOUNT, see the HP Fortran for

OpenVMS Language Reference Manual.

Performance: Making Programs Run Faster 5–35

5.5.6 Specify RECL

When creating a file, you should consider specifying a RECL value that provides for adequate I/O performance. The RECL value unit differs for unformatted files (4-byte units) and formatted files (1-byte units).

The RECL value unit for formatted files is always 1-byte units. For unformatted files, the RECL unit is 4-byte units, unless you specify the

/ASSUME=BYTERECL qualifier to request 1-byte units (see Section 2.3.7).

When porting unformatted data files from non-HP systems, see Section 9.6.

For More Information:

• On optimal RECL (record length) values, see the Guide to OpenVMS File

Applications.

• On specifying RECL, see the HP Fortran for OpenVMS Language Reference

Manual.

5.5.7 Use the Optimal Record Type

Unless a certain record type is needed for portability reasons (see

Section 6.5.3), choose the most efficient type, as follows:

• For sequential files of a consistent record size, the fixed-length record type gives the best performance.

• For sequential unformatted files when records are not fixed in size, use variable-length or segmented records.

• For sequential formatted files when records are not fixed in size, use variable-length records, unless you need to use Stream_LF records for data porting compatibility (see Section 6.5.3).

For More Information:

• On HP Fortran data files and I/O, see Chapter 6.

• On OPEN statement specifiers and defaults, see Section 6.6 and the HP

Fortran for OpenVMS Language Reference Manual.

5.5.8 Enable Implied-DO Loop Collapsing

DO loop collapsing reduces a major overhead in I/O processing. Normally, each element in an I/O list generates a separate call to the HP Fortran RTL. The processing overhead of these calls can be most significant in implied-DO loops.

HP Fortran reduces the number of calls in implied-DO loops by replacing up to seven nested implied-DO loops with a single call to an optimized run-time library I/O routine. The routine can transmit many I/O elements at once.

5–36 Performance: Making Programs Run Faster

Loop collapsing can occur in formatted and unformatted I/O, but only if certain conditions are met:

• The control variable must be an integer. The control variable cannot be a dummy argument or contained in an EQUIVALENCE or VOLATILE statement. HP Fortran must be able to determine that the control variable does not change unexpectedly at run time.

• The format must not contain a variable format expression.

For More Information:

• On VOLATILE attribute and statement, see the HP Fortran for OpenVMS

Language Reference Manual.

• On loop optimizations, see Section 5.7.

5.5.9 Use of Variable Format Expressions

Variable format expressions (a Compaq Fortran 77 extension) are almost as flexible as run-time formatting, but they are more efficient because the compiler can eliminate run-time parsing of the I/O format. Only a small amount of processing and the actual data transfer are required during run time.

On the other hand, run-time formatting can impair performance significantly.

For example, in the following statements, S

1 is more efficient than S the formatting is done once at compile time, not at run time:

2 because

WRITE (6,400) (A(I), I=1,N)

400 FORMAT (1X, <N> F5.2)

WRITE (CHFMT,500) ’(1X,’,N,’F5.2)’

500 FORMAT (A,I3,A)

WRITE (6,FMT=CHFMT) (A(I), I=1,N)

5.6 Additional Source Code Guidelines for Run-Time

Efficiency

Other source coding guidelines can be implemented to improve run-time performance.

The amount of improvement in run-time performance is related to the number of times a statement is executed. For example, improving an arithmetic expression executed within a loop many times has the potential to improve performance more than improving a similar expression executed once outside a loop.

Performance: Making Programs Run Faster 5–37

5.6.1 Avoid Small or Large Integer and Logical Data Items (Alpha only)

If the target system is an Alpha processor predating EV56, avoid using integer or logical data items whose size is less than 32 bits. On those processors, the smallest unit of efficient single-instruction access is 32 bits, and accessing a

16-bit (or 8-bit) data type can result in a sequence of machine instructions to access the data.

5.6.2 Avoid Mixed Data Type Arithmetic Expressions

Avoid mixing integer and floating-point (REAL) data in the same computation.

Expressing all numbers in a floating-point arithmetic expression (assignment statement) as floating-point values eliminates the need to convert data between fixed and floating-point formats. Expressing all numbers in an integer arithmetic expression as integer values also achieves this. This improves run-time performance.

For example, assuming that I and J are both INTEGER variables, expressing a constant number (2.) as an integer value (2) eliminates the need to convert the data:

Original Code:

Efficient Code:

INTEGER I, J

I = J / 2.

INTEGER I, J

I = J / 2

For applications with numerous floating-point operations, consider using the

/ASSUME=NOACCURACY_SENSITIVE qualifier (see Section 5.8.8) if a small difference in the result is acceptable.

You can use different sizes of the same general data type in an expression with minimal or no effect on run-time performance. For example, using REAL,

DOUBLE PRECISION, and COMPLEX floating-point numbers in the same floating-point arithmetic expression has minimal or no effect on run-time performance.

5.6.3 Use Efficient Data Types

In cases where more than one data type can be used for a variable, consider selecting the data types based on the following hierarchy, listed from most to least efficient:

• Integer (See also Section 5.6.1)

• Single-precision real, expressed explicitly as REAL, REAL (KIND=4), or

REAL*4

• Double-precision real, expressed explicitly as DOUBLE PRECISION, REAL

(KIND=8), or REAL*8

5–38 Performance: Making Programs Run Faster

• Extended-precision real, expressed explicitly as REAL (KIND=16) or

REAL*16

However, keep in mind that in an arithmetic expression, you should avoid mixing integer and floating-point (REAL) data (see Section 5.6.2).

5.6.4 Avoid Using Slow Arithmetic Operators

Before you modify source code to avoid slow arithmetic operators, be aware that optimizations convert many slow arithmetic operators to faster arithmetic operators. For example, the compiler optimizes the expression H=J**2 to be

H=J*J.

Consider also whether replacing a slow arithmetic operator with a faster arithmetic operator will change the accuracy of the results or impact the maintainability (readability) of the source code.

Replacing slow arithmetic operators with faster ones should be reserved for critical code areas. The following hierarchy lists the HP Fortran arithmetic operators, from fastest to slowest:

• Addition ( + ), subtraction ( - ), and floating-point multiplication ( * )

• Integer multiplication ( * )

• Division ( / )

• Exponentiation ( ** )

5.6.5 Avoid EQUIVALENCE Statement Use

Avoid using EQUIVALENCE statements. EQUIVALENCE statements can:

• Force unaligned data or cause data to span natural boundaries.

• Prevent certain optimizations, including:

Global data analysis under certain conditions (see Section 5.7.3)

Implied-DO loop collapsing when the control variable is contained in an

EQUIVALENCE statement

5.6.6 Use Statement Functions and Internal Subprograms

Whenever the HP Fortran compiler has access to the use and definition of a subprogram during compilation, it might choose to inline the subprogram.

Using statement functions and internal subprograms maximizes the number of subprogram references that will be inlined, especially when multiple source files are compiled together at optimization level /OPTIMIZE=LEVEL=4 or higher.

Performance: Making Programs Run Faster 5–39

For more information, see Section 5.1.2.

5.6.7 Code DO Loops for Efficiency

Minimize the arithmetic operations and other operations in a DO loop whenever possible. Moving unnecessary operations outside the loop will improve performance (for example, when the intermediate nonvarying values within the loop are not needed).

For More Information:

• On loop optimizations, see Section 5.8.2 and Section 5.8.4.

• On HP Fortran statements, see the HP Fortran for OpenVMS Language

Reference Manual.

5.7 Optimization Levels: /OPTIMIZE=LEVEL=n Qualifier

HP Fortran performs many optimizations by default. You do not have to recode your program to use them. However, understanding how optimizations work helps you remove any inhibitors to their successful function.

Generally, HP Fortran increases compile time in favor of decreasing run time.

If an operation can be performed, eliminated, or simplified at compile time, HP

Fortran does so, rather than have it done at run time. The time required to compile the program usually increases as more optimizations occur.

The program will likely execute faster when compiled at /OPTIMIZE=LEVEL=4, but will require more compilation time than if you compile the program at a lower level of optimization.

The size of the object file varies with the optimizations requested. Factors that can increase object file size include an increase of loop unrolling or procedure inlining.

Table 5–4 lists the levels of HP Fortran optimization with different

/OPTIMIZE=LEVEL=n levels. For example, /OPTIMIZE=LEVEL=0 specifies no selectable optimizations (certain optimizations always occur);

/OPTIMIZE=LEVEL=5 specifies all levels of optimizations including loop transformation and software pipelining.

5–40 Performance: Making Programs Run Faster

Table 5–4 Types of Optimization Performed at Different

/OPTIMIZE=LEVEL=n Levels

Optimization Type

/OPTIMIZE=LEVEL=n

n=0 n=1 n=2 n=3

Loop transformation

Software pipelining

Automatic inlining

Loop unrolling

Additional global optimizations

Global optimizations

Local (minimal) optimizations

n=4 n=5

The default is /OPTIMIZE=LEVEL=4.

In Table 5–4, the following terms are used to describe the levels of optimization

(described in detail in Section 5.7.1 to Section 5.7.6):

• Local (minimal) optimizations (/OPTIMIZE=LEVEL=1 or higher) occur within the source program unit and include recognition of common subexpressions and the expansion of multiplication and division.

• Global optimizations (/OPTIMIZE=LEVEL=2 or higher) include such optimizations as data-flow analysis, code motion, strength reduction, split-lifetime analysis, and instruction scheduling.

• Additional global optimizations (/OPTIMIZE=LEVEL=3 or higher) improve speed at the cost of extra code size. These optimizations include loop unrolling and code replication to eliminate branches.

• Automatic inlining and Software pipelining (/OPTIMIZE=LEVEL=4 or higher) applies interprocedure analysis and inline expansion of small procedures, usually by using heuristics that limit extra code, and software pipelining.

Software pipelining applies instruction scheduling to certain innermost loops, allowing instructions within a loop to "wrap around" and execute in a different iteration of the loop. This can reduce the impact of long-latency operations, resulting in faster loop execution.

Software pipelining also enables the prefetching of data to reduce the impact of cache misses.

Performance: Making Programs Run Faster 5–41

• Loop transformation (/OPTIMIZE=LEVEL=5 or higher) includes a group of loop transformation optimizations.

The loop transformation optimizations apply to array references within loops and can apply to multiple nested loops. These optimizations can improve the performance of the memory system.

5.7.1 Optimizations Performed at All Optimization Levels

The following optimizations occur at any optimization level (0 through 5):

• Space optimizations

Space optimizations decrease the size of the object or executing program by eliminating unnecessary use of memory, thereby improving speed of execution and system throughput. HP Fortran space optimizations are as follows:

Constant Pooling

Only one copy of a given constant value is ever allocated memory space.

If that constant value is used in several places in the program, all references point to that value.

Dead Code Elimination

If operations will never execute or if data items will never be used, HP

Fortran eliminates them. Dead code includes unreachable code and code that becomes unused as a result of other optimizations, such as value propagation.

• Inlining arithmetic statement functions and intrinsic procedures

Regardless of the optimization level, HP Fortran inserts arithmetic statement functions directly into a program instead of calling them as functions. This permits other optimizations of the inlined code and eliminates several operations, such as calls and returns or stores and fetches of the actual arguments. For example:

SUM(A,B) = A+B

Y = 3.14

X = SUM(Y,3.0) ! With value propagation, becomes: X = 6.14

Most intrinsic procedures are automatically inlined.

Inlining of other subprograms, such as contained subprograms, occurs at optimization level 4.

• Implied-DO loop collapsing

5–42 Performance: Making Programs Run Faster

DO loop collapsing reduces a major overhead in I/O processing. Normally, each element in an I/O list generates a separate call to the HP Fortran

RTL. The processing overhead of these calls can be most significant in implied-DO loops.

If HP Fortran can determine that the format will not change during program execution, it replaces the series of calls in up to seven nested implied-DO loops with a single call to an optimized RTL routine (see

Section 5.5.8). The optimized RTL routine can transfer many elements in one operation.

HP Fortran collapses implied-DO loops in formatted and unformatted I/O operations, but it is more important with unformatted I/O, where the cost of transmitting the elements is a higher fraction of the total cost.

• Array temporary elimination and FORALL statements

Certain array store operations are optimized. For example, to minimize the creation of array temporaries, HP Fortran can detect when no overlap occurs between the two sides of an array expression. This type of optimization occurs for some assignment statements in FORALL constructs.

Certain array operations are also candidates for loop unrolling optimizations (see Section 5.7.4.1).

5.7.2 Local (Minimal) Optimizations

To enable local optimizations, use /OPTIMIZE=LEVEL=1 or a higher optimization level (LEVEL=2, LEVEL=3, LEVEL=4, LEVEL=5).

To prevent local optimizations, specify /NOOPTIMIZE (/OPTIMIZE=LEVEL=0).

5.7.2.1 Common Subexpression Elimination

If the same subexpressions appear in more than one computation and the values do not change between computations, HP Fortran computes the result once and replaces the subexpressions with the result itself:

DIMENSION A(25,25), B(25,25)

A(I,J) = B(I,J)

Without optimization, these statements can be compiled as follows: t1 = ((J-1)*25+(I-1))*4 t2 = ((J-1)*25+(I-1))*4

A(t1) = B(t2)

Performance: Making Programs Run Faster 5–43

Variables t1 and t2 represent equivalent expressions. HP Fortran eliminates this redundancy by producing the following: t = ((J-1)*25+(I-1)*4

A(t) = B(t)

5.7.2.2 Integer Multiplication and Division Expansion

Expansion of multiplication and division refers to bit shifts that allow faster multiplication and division while producing the same result. For example, the integer expression (I*17) can be calculated as I with a 4-bit shift plus the original value of I. This can be expressed using the HP Fortran ISHFT intrinsic function:

J1 = I*17

J2 = ISHFT(I,4) + I ! equivalent expression for I*17

The optimizer uses machine code that, like the ISHFT intrinsic function, shifts bits to expand multiplication and division by literals.

5.7.2.3 Compile-Time Operations

HP Fortran does as many operations as possible at compile time rather than having them done at run time.

Constant Operations

HP Fortran can perform many operations on constants (including PARAMETER constants):

• Constants preceded by a unary minus sign are negated.

• Expressions involving +, –, *, or / operators are evaluated; for example:

PARAMETER (NN=27)

I = 2*NN+J ! Becomes: I = 54 + J

Evaluation of some constant functions and operators is performed at compile time. This includes certain functions of constants, concatenation of string constants, and logical and relational operations involving constants.

• Lower-ranked constants are converted to the data type of the higher-ranked operand:

REAL X, Y

X = 10 * Y ! Becomes: X = 10.0 * Y

• Array address calculations involving constant subscripts are simplified at compile time whenever possible:

INTEGER I(10,10)

I(1,2) = I(4,5) ! Compiled as a direct load and store

5–44 Performance: Making Programs Run Faster

Algebraic Reassociation Optimizations

HP Fortran delays operations to see whether they have no effect or can be transformed to have no effect. If they have no effect, these operations are removed. A typical example involves unary minus and .NOT. operations:

X = -Y * -Z ! Becomes: Y * Z

5.7.2.4 Value Propagation

HP Fortran tracks the values assigned to variables and constants, including those from DATA statements, and traces them to every place they are used.

HP Fortran uses the value itself when it is more efficient to do so.

When compiling subprograms, HP Fortran analyzes the program to ensure that propagation is safe if the subroutine is called more than once.

Value propagation frequently leads to more value propagation. HP Fortran can eliminate run-time operations, comparisons and branches, and whole statements.

In the following example, constants are propagated, eliminating multiple operations from run time:

Original Code

PI = 3.14

PIOVER2 = PI/2

I = 100

IF (I.GT.1) GOTO 10

10 A(I) = 3.0*Q

Optimized Code

PIOVER2 = 1.57

I = 100

10 A(100) = 3.0*Q

5.7.2.5 Dead Store Elimination

If a variable is assigned but never used, HP Fortran eliminates the entire assignment statement:

Performance: Making Programs Run Faster 5–45

X = Y*Z

X = A(I,J)* PI

! If X is not used in between, X=Y*Z is eliminated.

Some programs used for performance analysis often contain such unnecessary operations. When you try to measure the performance of such programs compiled with HP Fortran, these programs may show unrealistically good performance results. Realistic results are possible only with program units using their results in output statements.

5.7.2.6 Register Usage

A large program usually has more data that would benefit from being held in registers than there are registers to hold the data. In such cases, HP Fortran typically tries to use the registers according to the following descending priority list:

For temporary operation results, including array indexes

For variables

For addresses of arrays (base address)

All other usages

HP Fortran uses heuristic algorithms and a modest amount of computation to attempt to determine an effective usage for the registers.

Holding Variables in Registers

Because operations using registers are much faster than using memory, HP

Fortran generates code that uses 64-bit integer and floating-point registers instead of memory locations. Knowing when HP Fortran uses registers may be helpful when doing certain forms of debugging.

HP Fortran uses registers to hold the values of variables whenever the Fortran language does not require them to be held in memory, such as holding the values of temporary results of subexpressions, even if /NOOPTIMIZE (same as

/OPTIMIZE=LEVEL=0 or no optimization) was specified.

HP Fortran may hold the same variable in different registers at different points in the program:

5–46 Performance: Making Programs Run Faster

V = 3.0*Q

X = SIN(Y)*V

V = PI*X

Y = COS(Y)*V

HP Fortran might choose one register to hold the first use of V and another register to hold the second. Both registers can be used for other purposes at points in between. There may be times when the value of the variable does not exist anywhere in the registers. If the value of V is never needed in memory, it is never stored.

HP Fortran uses registers to hold the values of I, J, and K (so long as there are no other optimization effects, such as loops involving the variables):

A(I) = B(J) + C(K)

More typically, an expression uses the same index variable:

A(K) = B(K) + C(K)

In this case, K is loaded into only one register and is used to index all three arrays at the same time.

5.7.2.7 Mixed Real/Complex Operations

In mixed REAL/COMPLEX operations, HP Fortran avoids the conversion and performs a simplified operation on:

• Add ( + ), subtract (–), and multiply ( * ) operations if either operand is

REAL

• Divide ( / ) operations if the right operand is REAL

For example, if variable R is REAL and A and B are COMPLEX, no conversion occurs with the following:

COMPLEX A, B

B = A + R

Performance: Making Programs Run Faster 5–47

5.7.3 Global Optimizations

To enable global optimizations, use /OPTIMIZE=LEVEL=2 or a higher optimization level (LEVEL=3, LEVEL=4, or LEVEL=5). Using /OPTIMIZE=

LEVEL=2 or higher also enables local optimizations (LEVEL=1).

Global optimizations include:

• Data-flow analysis

• Split lifetime analysis

• Strength reduction (replaces a CPU-intensive calculation with one that uses fewer CPU cycles)

• Code motion (also called code hoisting)

• Instruction scheduling

Data-flow and split lifetime analysis (global data analysis) traces the values of variables and whole arrays as they are created and used in different parts of a program unit. During this analysis, HP Fortran assumes that any pair of array references to a given array might access the same memory location, unless a constant subscript is used in both cases.

To eliminate unnecessary recomputations of invariant expressions in loops, HP

Fortran hoists them out of the loops so they execute only once.

Global data analysis includes which data items are selected for analysis. Some data items are analyzed as a group and some are analyzed individually. HP

Fortran limits or may disqualify data items that participate in the following constructs, generally because it cannot fully trace their values.

Data items in the following constructs can make global optimizations less effective:

• VOLATILE declarations

VOLATILE declarations are needed to use certain run-time features of the operating system. Declare a variable as VOLATILE if the variable can be accessed using rules in addition to those provided by the Fortran 90/95 language. Examples include:

COMMON data items or entire common blocks that can change value by means other than direct assignment or during a routine call. For example, if a variable in COMMON can change value by means of an

OpenVMS AST, you must declare the variable or the COMMON block to which it belongs as volatile.

Variables read or written by an AST routine or a condition handler, including those in a common block or module.

5–48 Performance: Making Programs Run Faster

An address not saved by the %LOC built-in function.

As requested by the VOLATILE statement, HP Fortran disqualifies any volatile variables from global data analysis.

• Subroutine calls or external function references

HP Fortran cannot trace data flow in a called routine that is not part of the program unit being compiled, unless the same FORTRAN command compiled multiple program units (see Section 5.1.2). Arguments passed to a called routine that are used again in a calling program are assumed to be modified, unless the proper INTENT is specified in an interface block (the compiler must assume they are referenced by the called routine).

• Common blocks

HP Fortran limits optimizations on data items in common blocks. If common block data items are referenced inside called routines, their values might be altered. In the following example, variable I might be altered by

FOO, so HP Fortran cannot predict its value in subsequent references.

COMMON /X/ I

DO J=1,N

I = J

CALL FOO

A(I) = I

ENDDO

• Variables in Fortran 90/95 modules

HP Fortran limits optimizations on variables in Fortran 90/95 modules.

Like common blocks, if the variables in Fortran modules are referenced inside called routines, their values might be altered.

• Variables referenced by a %LOC built-in function or variables with the

TARGET attribute

HP Fortran limits optimizations on variables indirectly referenced by a

%LOC function or variables with the TARGET attribute, because the called routine may dereference the pointer to such a variable.

• Equivalence groups

An equivalence group is formed explicitly with the EQUIVALENCE statement or implicitly by the COMMON statement. A program section is a particular common block or local data area for a particular routine. HP

Fortran combines equivalence groups within the same program section and in the same program unit.

Performance: Making Programs Run Faster 5–49

The equivalence groups in separate program sections are analyzed separately, but the data items within each group are not, so some optimizations are limited to the data within each group.

5.7.4 Additional Global Optimizations

To enable additional global optimizations, use /OPTIMIZE=LEVEL=3 or a higher optimization level (LEVEL=4 or LEVEL=5). Using /OPTIMIZE=

LEVEL=3 or higher also enables local optimizations (LEVEL=1) and global optimizations (LEVEL=2).

Additional global optimizations improve speed at the cost of longer compile times and possibly extra code size.

5.7.4.1 Loop Unrolling

At optimization level /OPTIMIZE=LEVEL=3 or above, HP Fortran attempts to unroll certain innermost loops, minimizing the number of branches and grouping more instructions together to allow efficient overlapped instruction execution (instruction pipelining). The best candidates for loop unrolling are innermost loops with limited control flow.

As more loops are unrolled, the average size of basic blocks increases. Loop unrolling generates multiple copies of the code for the loop body (loop code iterations) in a manner that allows efficient instruction pipelining.

The loop body is replicated a certain number of times, substituting index expressions. An initialization loop might be created to align the first reference with the main series of loops. A remainder loop might be created for leftover work.

The number of times a loop is unrolled can be determined either by the optimizer or by using the /OPTIMIZE=UNROLL=n qualifier, which can specify the limit for loop unrolling. Unless the user specifies a value, the optimizer unrolls a loop four times for most loops or two times for certain loops (large estimated code size or branches out the loop).

Array operations are often represented as a nested series of loops when expanded into instructions. The innermost loop for the array operation is the best candidate for loop unrolling (like DO loops). For example, the following array operation (once optimized) is represented by nested loops, where the innermost loop is a candidate for loop unrolling:

A(1:100,2:30) = B(1:100,1:29) * 2.0

5–50 Performance: Making Programs Run Faster

5.7.4.2 Code Replication to Eliminate Branches

In addition to loop unrolling and other optimizations, the number of branches are reduced by replicating code that will eliminate branches. Code replication decreases the number of basic blocks and increases instruction-scheduling opportunities.

Code replication normally occurs when a branch is at the end of a flow of control, such as a routine with multiple, short exit sequences. The code at the exit sequence gets replicated at the various places where a branch to it might occur.

For example, consider the following unoptimized routine and its optimized equivalent that uses code replication (R4 is register 4):

Unoptimized Instructions Optimized (Replicated) Instructions

branch to exit1

exit1: move 1 into R4 return

move 1 into R4 return

Similarly, code replication can also occur within a loop that contains a small amount of shared code at the bottom of a loop and a case-type dispatch within the loop. The loop-end test-and-branch code might be replicated at the end of each case to create efficient instruction pipelining within the code for each case.

Performance: Making Programs Run Faster 5–51

5.7.5 Automatic Inlining and Software Pipelining

To enable optimizations that perform automatic inlining and software pipelining, use /OPTIMIZE=LEVEL=4 or a higher optimization level

(LEVEL=5). Using /OPTIMIZE=LEVEL=4 also enables local optimizations

(LEVEL=1), global optimizations (LEVEL=2), and additional global optimizations (LEVEL=3).

The default is /OPTIMIZE=LEVEL=4 (same as /OPTIMIZE).

5.7.5.1 Interprocedure Analysis

Compiling multiple source files at optimization level /OPTIMIZE=LEVEL=4 or higher lets the compiler examine more code for possible optimizations, including multiple program units. This results in:

• Inlining more procedures

• More complete global data analysis

• Reducing the number of external references to be resolved during linking

As more procedures are inlined, the size of the executable program and compile times may increase, but execution time should decrease.

5.7.5.2 Inlining Procedures

Inlining refers to replacing a subprogram reference (such as a CALL statement or function invocation) with the replicated code of the subprogram.

As more procedures are inlined, global optimizations often become more effective.

The optimizer inlines small procedures, limiting inlining candidates based on such criteria as:

• Estimated size of code

• Number of call sites

• Use of constant arguments

You can specify:

• The /OPTIMIZE=LEVEL=n qualifier to control the optimization level.

For example, specifying /OPTIMIZE=LEVEL=4 or higher enables interprocedure optimizations.

Different /OPTIMIZE=LEVEL=n keywords set different levels of inlining.

For example, /OPTIMIZE=LEVEL=4 sets /OPTIMIZE=INLINE=SPEED.

5–52 Performance: Making Programs Run Faster

• One of the /OPTIMIZE=INLINE=xxxxx keywords to directly control the inlining of procedures (see Section 5.8.5). For example,

/OPTIMIZE=INLINE=SPEED inlines more procedures than

/OPTIMIZE=INLINE=SIZE.

5.7.5.3 Software Pipelining

Software pipelining also enables the prefetching of data to reduce the impact of cache misses.

For More Information:

• On HP Fortran statements, see the HP Fortran for OpenVMS Language

Reference Manual.

• On controlling inlining using /OPTIMIZE=INLINE=keyword, see

Section 5.8.5.

• On software pipelining, see Section 5.8.2.

5.7.6 Loop Transformation

A group of optimizations known as loop transformation optimizations with its associated additional software dependence analysis are enabled by using the /OPTIMIZE=LEVEL=5 qualifier. In certain cases, this improves run-time performance.

The loop transformation optimizations apply to array references within loops and can apply to multiple nested loops. These optimizations can improve the performance of the memory system.

For More Information:

• On loop transformations, see Section 5.8.1.

5.8 Other Qualifiers Related to Optimization

In addition to the /OPTIMIZE=LEVEL qualifiers (discussed in Section 5.7), several other FORTRAN command qualifiers and /OPTIMIZE keywords can prevent or facilitate improved optimizations.

Performance: Making Programs Run Faster 5–53

5.8.1 Loop Transformation

The loop transformation optimizations are enabled by using the

/OPTIMIZE=LOOPS qualifier or the /OPTIMIZE=LEVEL=5 qualifier. Loop transformation attempts to improve performance by rewriting loops to make better use of the memory system. By rewriting loops, the loop transformation optimizations can increase the number of instructions executed, which can degrade the run-time performance of some programs.

To request loop transformation optimizations without software pipelining, do one of the following:

• Specify /OPTIMIZE=LEVEL=5 with /OPTIMIZE=NOPIPELINE (preferred method)

• Specify /OPTIMIZE=LOOPS with /OPTIMIZE=LEVEL=4, LEVEL=3, or

LEVEL=2. This optimization is not performed at optimization levels below

LEVEL=2.

The loop transformation optimizations apply to array references within loops. These optimizations can improve the performance of the memory system and usually apply to multiple nested loops. The loops chosen for loop transformation optimizations are always counted loops. Counted loops use a variable to count iterations, thereby determining the number before entering the loop. For example, most DO loops are counted loops.

The types of optimizations associated with /OPTIMIZE=LOOPS include the following:

• Loop blocking—Can minimize memory system use with multidimensional array elements by completing as many operations as possible on array elements currently in the cache. Also known as loop tiling.

• Loop distribution—Moves instructions from one loop into separate, new loops. This can reduce the amount of memory used during one loop so that the remaining memory may fit in the cache. It can also create improved opportunities for loop blocking.

• Loop fusion—Combines instructions from two or more adjacent loops that use some of the same memory locations into a single loop. This can avoid the need to load those memory locations into the cache multiple times and improves opportunities for instruction scheduling.

5–54 Performance: Making Programs Run Faster

• Loop interchange—Changes the nesting order of some or all loops. This can minimize the stride of array element access during loop execution and reduce the number of memory accesses needed. Also known as loop permutation.

• Scalar replacement—Replaces the use of an array element with a scalar variable under certain conditions.

• Outer loop unrolling—Unrolls the outer loop inside the inner loop under certain conditions to minimize the number of instructions and memory accesses needed. This also improves opportunities for instruction scheduling and scalar replacement.

For More Information:

On the interaction of command-line options and timing programs compiled with the loop transformation optimizations, see Section 5.7.

5.8.2 Software Pipelining

Software pipelining and additional software dependence analysis are enabled by using the /OPTIMIZE=PIPELINE qualifier or by the /OPTIMIZE=LEVEL=4 qualifier. Software pipelining in certain cases improves run-time performance.

The software pipelining optimization applies instruction scheduling to certain innermost loops, allowing instructions within a loop to "wrap around" and execute in a different iteration of the loop. This can reduce the impact of long-latency operations, resulting in faster loop execution.

Loop unrolling (enabled at /OPTIMIZE=LEVEL=3 or above) cannot schedule across iterations of a loop. Because software pipelining can schedule across loop iterations, it can perform more efficient scheduling to eliminate instruction stalls within loops.

For instance, if software dependence analysis of data flow reveals that certain calculations can be done before or after that iteration of the loop, software pipelining reschedules those instructions ahead of or behind that loop iteration, at places where their execution can prevent instruction stalls or otherwise improve performance.

Software pipelining also enables the prefetching of data to reduce the impact of cache misses.

On Alpha systems, software pipelining can be more effective when you combine

/OPTIMIZE=PIPELINE (or /OPTIMIZE=LEVEL=4) with the appropriate

OPTIMIZE=TUNE=keyword (Alpha only) for the target Alpha processor generation (see Section 5.8.6).

Performance: Making Programs Run Faster 5–55

To specify software pipelining without loop transformation optimizations, do one of the following:

• Specify /OPTIMIZE=LEVEL=4 (preferred method)

• Specify /OPTIMIZE=PIPELINE with /OPTIMIZE=LEVEL=3, or

/OPTIMIZE=LEVEL=2. This optimization is not performed at optimization levels below LEVEL=2.

For this version of HP Fortran, loops chosen for software pipelining:

• Are always innermost loops (those executed the most).

• Do not contain branches or procedure calls.

• Do not use COMPLEX floating-point data.

By modifying the unrolled loop and inserting instructions as needed before and/or after the unrolled loop, software pipelining generally improves run-time performance, except where the loops contain a large number of instructions with many existing overlapped operations. In this case, software pipelining may not have enough registers available to effectively improve execution performance. Run-time performance using /OPTIMIZE=LEVEL=4

(or /OPTIMIZE=PIPELINE) may not improve performance, as compared to using /OPTIMIZE=(LEVEL=4,NOPIPELINE).

For programs that contain loops that exhaust available registers, longer execution times may result with /OPTIMIZE=LEVEL=4 or

/OPTIMIZE=PIPELINE. In cases where performance does not improve, consider compiling with the OPTIMIZE=UNROLL=1 qualifier along with

/OPTIMIZE=LEVEL=4 or /OPTIMIZE=PIPELINE, to possibly improve the effects of software pipelining.

For More Information:

On the interaction of command-line options and timing programs compiled with software pipelining, see Section 5.7.

5.8.3 Setting Multiple Qualifiers with the /FAST Qualifier

Specifying the /FAST qualifier sets the following qualifiers:

• /ALIGNMENT=(COMMONS=NATURAL,RECORDS=NATURAL,SEQUENCE)

(see Section 5.3)

• /ARCHITECTURE=HOST (see Section 5.8.7)

• /ASSUME=NOACCURACY_SENSITIVE (see Section 5.8.8)

• /MATH_LIBRARY=FAST (Alpha only) (see Section 2.3.30)

5–56 Performance: Making Programs Run Faster

• /OPTIMIZE=TUNE=HOST (Alpha only) (see Section 5.8.6)

You can specify individual qualifiers on the command line to override the

/FAST defaults. Note that /FAST/ALIGNMENT=COMMONS=PACKED sets

/ALIGNMENT=NOSEQUENCE.

5.8.4 Controlling Loop Unrolling

You can specify the number of times a loop is unrolled by using the

/OPTIMIZE=UNROLL=n qualifier (see Section 2.3.35).

Using /OPTIMIZE=UNROLL=n can also influence the run-time results of software pipelining optimizations performed when you specify

/OPTIMIZE=LEVEL=5.

Although unrolling loops usually improves run-time performance, the size of the executable program may increase.

For More Information:

On loop unrolling, see Section 5.7.4.1.

5.8.5 Controlling the Inlining of Procedures

To specify the types of procedures to be inlined, use the

/OPTIMIZE=INLINE=keyword keywords. Also, compile multiple source files together and specify an adequate optimization level, such as

/OPTIMIZE=LEVEL=4.

If you omit /OPTIMIZE=INLINE=keyword, the optimization level

/OPTIMIZE=LEVEL=n qualifier used determines the types of procedures that are inlined.

The /OPTIMIZE=INLINE=keyword keywords are as follows:

• NONE (same as /OPTIMIZE=NOINLINE) inlines statement functions but not other procedures. This type of inlining occurs if you specify

/OPTIMIZE=LEVEL=0, LEVEL=1, LEVEL=2, or LEVEL=3 and omit

INLINE=keyword.

• MANUAL (same as NONE) inlines statement functions but not other procedures. This type of inlining occurs if you specify /OPTIMIZE=LEVEL=2 or LEVEL=3 and omit INLINE=keyword.

• In addition to inlining statement functions, SIZE inlines any procedures that the HP Fortran optimizer expects will improve run-time performance with no likely significant increase in program size.

Performance: Making Programs Run Faster 5–57

• In addition to inlining statement functions, SPEED inlines any procedures that the HP Fortran optimizer expects will improve run-time performance with a likely significant increase in program size. This type of inlining occurs if you specify /OPTIMIZE=LEVEL=4 or LEVEL=5 and omit

/OPTIMIZE=INLINE=keyword.

• ALL inlines every call that can possibly be inlined while generating correct code, including the following:

Statement functions (always inlined).

Any procedures that HP Fortran expects will improve run-time performance with a likely significant increase in program size.

Any other procedures that can possibly be inlined and generate correct code. Certain recursive routines are not inlined to prevent infinite expansion.

For information on the inlining of other procedures (inlined at optimization level /OPTIMIZE=LEVEL=4 or higher), see Section 5.7.5.2.

Maximizing the types of procedures that are inlined usually improves run-time performance, but compile-time memory usage and the size of the executable program may increase.

To determine whether using /OPTIMIZE=INLINE=ALL benefits your particular program, time program execution for the same program compiled with and without /OPTIMIZE=INLINE=ALL.

5.8.6 Requesting Optimized Code for a Specific Processor Generation

(Alpha only)

You can specify the types of optimized code to be generated by using the

/OPTIMIZE=TUNE=keyword (Alpha only) keywords. Regardless of the specified keyword, the generated code will run correctly on all implementations of the Alpha architecture. Tuning for a specific implementation can improve run-time performance; it is also possible that code tuned for a specific target may run slower on another target.

Specifying the correct keyword for /OPTIMIZE=TUNE=keyword (Alpha only) for the target processor generation type usually slightly improves run-time performance. Unless you request software pipelining, the run-time performance difference for using the wrong keyword for

/OPTIMIZE=TUNE=keyword (such as using /OPTIMIZE=TUNE=EV4 for an

EV5 processor) is usually less than 5%. When using software pipelining (using

/OPTIMIZE=LEVEL=5) with /OPTIMIZE=TUNE=keyword, the difference can be more than 5%.

5–58 Performance: Making Programs Run Faster

The combination of the specified keyword for /OPTIMIZE=TUNE=keyword and the type of processor generation used has no effect on producing the expected correct program results.

The /OPTIMIZE=TUNE=keyword keywords are as follows:

• GENERIC generates and schedules code that will execute well for all types of Alpha processor generations. This provides generally efficient code for those applications that will be run on systems using all types of processor generations (an alternative to providing multiple versions of the application compiled for each processor generation type).

• HOST generates and schedules code optimized for the type of processor generation in use on the system being used for compilation.

• EV4 generates and schedules code optimized for the EV4 (21064) processor generation.

• EV5 generates and schedules code optimized for the EV5 (21164) processor generation. This processor generation is faster than EV4.

• EV56 generates and schedules code optimized for some 21164 Alpha architecture implementations that use the BWX (Byte/Word manipulation) instruction extensions of the Alpha architecture.

• PCA56 generates and schedules code optimized for 21164PC Alpha architecture implementation that uses BWX (Byte/Word manipulation) and MAX (Multimedia) instructions extensions.

• EV6 generates and schedules code for the 21264 chip implementation that uses the following extensions to the base Alpha instruction set: BWX

(Byte/Word manipulation) and MAX (Multimedia) instructions, square root and floating-point convert instructions, and count instructions.

• EV67 generates and schedules code optimized for the EV67 processor generation. This processor generation is faster than EV4, EV5, EV56,

PCA56, and EV6.

If you omit /OPTIMIZE=TUNE=keyword, if /FAST is specified, then HOST is used; otherwise, GENERIC is used.

Performance: Making Programs Run Faster 5–59

5.8.7 Requesting Generated Code for a Specific Processor Generation

(Alpha only)

You can specify the types of instructions that will be generated for the program unit being compiled by using the /ARCHITECTURE qualifier. Unlike the

/OPTIMIZE=TUNE=keyword (Alpha only) option that helps with proper instruction scheduling, the /ARCHITECTURE qualifier specifies the type of

Alpha chip instructions that can be used.

Programs compiled with the /ARCHITECTURE=GENERIC option (default) run on all Alpha processors without instruction emulation overhead.

For example, if you specify /ARCHITECTURE=EV6, the code generated will run very fast on EV6 systems, but may run slower on older Alpha processor generations. Because instructions used for the EV6 chip may be present in the program’s generated code, code generated for an EV6 system may slow program execution on older Alpha processors when EV6 instructions are emulated by the OpenVMS Alpha Version 7.1 (or later) instruction emulator.

This instruction emulator allows new instructions, not implemented on the host processor chip, to execute and produce correct results. Applications using emulated instructions will run correctly, but may incur significant software emulation overhead at run time.

The keywords used by /ARCHITECTURE=keyword are the same as those used by /OPTIMIZE=TUNE=keyword. If you omit /ARCHITECTURE=keyword, if

/FAST is specified then HOST is used; otherwise, GENERIC is used. For more information on the /ARCHITECTURE qualifier, see Section 2.3.6.

5.8.8 Arithmetic Reordering Optimizations

If you use the /ASSUME=NOACCURACY_SENSITIVE qualifier, HP Fortran may reorder code (based on algebraic identities) to improve performance. For example, the following expressions are mathematically equivalent but may not compute the same value using finite precision arithmetic:

X = (A + B) + C

X = A + (B + C)

The results can be slightly different from the default (ACCURACY_

SENSITIVE) because of the way intermediate results are rounded. However, the NOACCURACY_SENSITIVE results are not categorically less accurate than those gained by the default. In fact, dot product summations using

NOACCURACY_SENSITIVE can produce more accurate results than those using ACCURACY_SENSITIVE.

5–60 Performance: Making Programs Run Faster

The effect of /ASSUME=NOACCURACY_SENSITIVE is important when HP

Fortran hoists divide operations out of a loop. If NOACCURACY_SENSITIVE is in effect, the unoptimized loop becomes the optimized loop:

Unoptimized Code

DO I=1,N

B(I) = A(I)/V

END DO

Optimized Code

T = 1/V

DO I=1,N

B(I) = A(I)*T

END DO

The transformation in the optimized loop increases performance significantly, and loses little or no accuracy. However, it does have the potential for raising overflow or underflow arithmetic exceptions.

5.8.9 Dummy Aliasing Assumption

Some programs compiled with HP Fortran (or Compaq Fortran 77) might have results that differ from the results of other Fortran compilers. Such programs might be aliasing dummy arguments to each other or to a variable in a common block or shared through use association, and at least one variable access is a store. Alternatively, they may be calling a user-defined procedure with actual arguments that do not match the procedure’s dummy arguments in order, number, or type.

This program behavior is prohibited in programs conforming to the Fortran 90 and Fortran 95 standards, but not by HP Fortran. Other versions of Fortran allow dummy aliases and check for them to ensure correct results. However,

HP Fortran assumes that no dummy aliasing will occur, and it can ignore potential data dependencies from this source in favor of faster execution.

The HP Fortran default is safe for programs conforming to the Fortran 90 and

Fortran 95 standards. It will improve performance of these programs, because the standard prohibits such programs from passing overlapped variables or arrays as actual arguments if either is assigned in the execution of the program unit.

Performance: Making Programs Run Faster 5–61

The /ASSUME=DUMMY_ALIASES qualifier allows dummy aliasing. It ensures correct results by assuming the exact order of the references to dummy and common variables is required. Program units taking advantage of this behavior can produce inaccurate results if compiled with

/ASSUME=NODUMMY_ALIASES.

Example 5–3 is taken from the DAXPY routine in the Fortran-77 version of the

Basic Linear Algebra Subroutines (BLAS).

Example 5–3 Using the /ASSUME=DUMMY_ALIASES Qualifier

SUBROUTINE DAXPY(N,DA,DX,INCX,DY,INCY)

Constant times a vector plus a vector.

uses unrolled loops for increments equal to 1.

DOUBLE PRECISION DX(1), DY(1), DA

INTEGER I,INCX,INCY,IX,IY,M,MP1,N

IF (N.LE.0) RETURN

IF (DA.EQ.0.0) RETURN

IF (INCX.EQ.1.AND.INCY.EQ.1) GOTO 20

Code for unequal increments or equal increments not equal to 1.

RETURN

Code for both increments equal to 1.

Clean-up loop

20 M = MOD(N,4)

IF (M.EQ.0) GOTO 40

DO I=1,M

DY(I) = DY(I) + DA*DX(I)

END DO

IF (N.LT.4) RETURN

40 MP1 = M + 1

DO I = MP1, N, 4

DY(I) = DY(I) + DA*DX(I)

DY(I + 1) = DY(I + 1) + DA*DX(I + 1)

DY(I + 2) = DY(I + 2) + DA*DX(I + 2)

DY(I + 3) = DY(I + 3) + DA*DX(I + 3)

END DO

RETURN

END SUBROUTINE

5–62 Performance: Making Programs Run Faster

The second DO loop contains assignments to DY. If DY is overlapped with

DA, any of the assignments to DY might give DA a new value, and this overlap would affect the results. If this overlap is desired, then DA must be fetched from memory each time it is referenced. The repetitious fetching of DA degrades performance.

Linking Routines with Opposite Settings

You can link routines compiled with the /ASSUME=DUMMY_ALIASES qualifier to routines compiled with /ASSUME=NODUMMY_ALIASES. For example, if only one routine is called with dummy aliases, you can use

/ASSUME=DUMMY_ALIASES when compiling that routine, and compile all the other routines with /ASSUME=NODUMMY_ALIASES to gain the performance value of that qualifier.

Programs calling DAXPY with DA overlapping DY do not conform to the

FORTRAN-77, Fortran 90, and Fortran 95 standards. However, they are supported if /ASSUME=DUMMY_ALIASES was used to compile the DAXPY routine.

5.9 Compiler Directives Related to Performance

Certain compiler source directives (cDEC$ prefix) can be used in place of some performance-related compiler options and provide more control of certain optimizations, as discussed in the following sections:

5.9.1, Using the cDEC$ OPTIONS Directive

5.9.2, Using the cDEC$ UNROLL Directive to Control Loop Unrolling

5.9.3, Using the cDEC$ IVDEP Directive to Control Certain Loop

Optimizations

5.9.1 Using the cDEC$ OPTIONS Directive

The cDEC$ OPTIONS directive allows source code control of the alignment of fields in record structures and data items in common blocks. The fields and data items can be naturally aligned (for performance reasons) or they can be packed together on arbitrary byte boundaries.

Using this directive is an alternative to the compiler option /[NO]ALIGNMENT, which affects the alignment of all fields in record structures and data items in common blocks in the current program unit.

For more information:

See the description of the OPTIONS directive in the HP Fortran for OpenVMS

Language Reference Manual.

Performance: Making Programs Run Faster 5–63

5.9.2 Using the cDEC$ UNROLL Directive to Control Loop Unrolling

The cDEC$ UNROLL directive allows you to specify the number of times certain counted DO loops will be unrolled. Place the cDEC$ UNROLL directive before the DO loop you want to control the unrolling of.

Using this directive for a specific loop overrides the value specified by the compiler option /OPTIMIZE=UNROLL= for that loop. The value specified by unroll affects how many times all loops not controlled by their respective cDEC$ UNROLL directives are unrolled.

For more information:

See the description of the UNROLL directive in the HP Fortran for OpenVMS

Language Reference Manual.

5.9.3 Using the cDEC$ IVDEP Directive to Control Certain Loop

Optimizations

The cDEC$ IVDEP directive allows you to help control certain optimizations related to dependence analysis in a DO loop. Place the cDEC$ IVDEP directive before the DO loop you want to help control the optimizations for. Not all DO loops should use this directive.

The cDEC$ IVDEP directive tells the optimizer to begin dependence analysis by assuming all dependences occur in the same forward direction as their appearance in the normal scalar execution order. This contrasts with normal compiler behavior, which is for the dependence analysis to make no initial assumptions about the direction of a dependence.

For more information:

See the description of the IVDEP directive in the HP Fortran for OpenVMS

Language Reference Manual.

5–64 Performance: Making Programs Run Faster

HP Fortran Input/Output

The following topics are addressed in this chapter:

• Section 6.1, Overview

• Section 6.2, Logical I/O Units

• Section 6.3, Types of I/O Statements

• Section 6.4, Forms of I/O Statements

• Section 6.5, Types of Files and File Characteristics

• Section 6.6, Opening Files and the OPEN Statement

• Section 6.7, Obtaining File Information: The INQUIRE Statement

• Section 6.8, Closing a File: The CLOSE Statement

• Section 6.9, Record Operations

• Section 6.10, Output Data Buffering and RMS Journaling

6.1 Overview

This chapter describes HP Fortran input/output (I/O) as implemented for HP

Fortran. It also provides information about HP Fortran I/O in relation to the

OpenVMS Record Management Services (RMS) and Run-Time Library (RTL).

HP Fortran assumes that all unformatted data files will be in the same native little endian numeric formats used in memory. If you need to read or write unformatted numeric data (on disk) that has a different numeric format than that used in memory, see Chapter 9.

You can use HP Fortran I/O statements to communicate between processes on either the same computer or different computers.

HP Fortran Input/Output 6–1

For More Information:

• On specifying the native floating-point format used in memory, see

Section 2.3.22.

• On supported data types, see Chapter 8.

• On using various HP and non-HP data formats for unformatted files, see

Chapter 9.

• On interprocess communication, see Chapter 13.

• On porting Compaq Fortran 77 for OpenVMS VAX data, see Appendix B.

• On performing I/O to the same unit with HP Fortran and Compaq Fortran

77 object files, see Appendix B.

• On using indexed files, see Chapter 12.

6.2 Logical I/O Units

In HP Fortran, a logical unit is a channel through which data transfer occurs between the program and a device or file. You identify each logical unit with a logical unit number, which can be any nonnegative integer from 0 to a maximum value of 2,147,483,647 (2**31–1).

For example, the following READ statement uses logical unit number 2:

READ (2,100) I,X,Y

This READ statement specifies that data is to be entered from the device or file corresponding to logical unit 2, in the format specified by the FORMAT statement labeled 100.

When opening a file, use the UNIT specifier to indicate the unit number. You can use the LIB$GET_LUN library routine to return a logical unit number not currently in use by your program. If you intend to use LIB$GET_LUN, avoid using logical unit numbers (UNIT) 100 to 119 (reserved for LIB$GET_LUN).

HP Fortran programs are inherently device-independent. The association between the logical unit number and the physical file can occur at run time.

Instead of changing the logical unit numbers specified in the source program, you can change this association at run time to match the needs of the program and the available resources. For example, before running the program, a command procedure can set the appropriate logical name or allow the terminal user to type a directory, file name, or both.

Use the same logical unit number specified in the OPEN statement for other

I/O statements to be applied to the opened file, such as READ and WRITE.

6–2 HP Fortran Input/Output

The OPEN statement connects a unit number with an external file and allows you to explicitly specify file attributes and run-time options using OPEN statement specifiers (all files except internal files are called external files).

ACCEPT, TYPE, and PRINT statements do not refer explicitly to a logical unit

(a file or device) from which or to which data is to be transferred; they refer implicitly to a default preconnected logical unit. The ACCEPT statement is normally preconnected to the default input device, and the TYPE and PRINT statements are normally preconnected to the default output device. These defaults can be overridden with appropriate logical name assignments (see

Section 6.6.1.2).

READ, WRITE, and REWRITE statements refer explicitly to a specified logical unit from which or to which data is to be transferred. However, to use a preconnected device for READ (SYS$INPUT) and WRITE (SYS$OUTPUT), specify the unit number as an asterisk ( * ).

Certain unit numbers are preconnected to OpenVMS standard devices. Unit number 5 is associated with SYS$INPUT and unit 6 with SYS$OUTPUT.

At run time, if units 5 and 6 are specified by a record I/O statement (such as READ or WRITE) without having been explicitly opened by an OPEN statement, HP Fortran implicitly opens units 5 and 6 and associates them with their respective operating system standard I/O files.

For More Information:

On the OPEN statement and preconnected files, see Section 6.6.

6.3 Types of I/O Statements

Table 6–1 lists the HP Fortran I/O statements.

HP Fortran Input/Output 6–3

Table 6–1 Summary of I/O Statements

Category and

Statement Name Description

File Connection

OPEN Connects a unit number with an external file and specifies file connection characteristics.

Disconnects a unit number from an external file.

File Inquiry

INQUIRE Returns information about a named file, a connection to a unit, or the length of an output item list.

Record Position

BACKSPACE

ENDFILE

REWIND

Moves the record position to the beginning of the previous record (sequential access only).

Writes an end-of-file marker after the current record (sequential access only).

Sets the record position to the beginning of the file (sequential access only).

Record Input

READ Transfers data from an external file record or an internal file to internal storage.

Record Output

WRITE

Transfers data from internal storage to an external file record or to an internal file.

Transfers data from internal storage to SYS$OUTPUT

(standard output device). Unlike WRITE, PRINT only provides formatted sequential output and does not specify a unit number.

HP Fortran

Extensions

ACCEPT Reads input from SYS$INPUT. Unlike READ, ACCEPT only provides formatted sequential output and does not specify a unit number.

(continued on next page)

6–4 HP Fortran Input/Output

Table 6–1 (Cont.) Summary of I/O Statements

Category and

Statement Name Description

DELETE

REWRITE

UNLOCK

TYPE

DEFINE FILE

FIND

Marks a record at the current record position in a relative file as deleted (direct access only).

Transfers data from internal storage to an external file record at the current record position. Certain restrictions apply.

Releases a lock held on the current record when file sharing was requested when the file was opened (see Section 6.9.2).

Writes record output to SYS$OUTPUT (same as PRINT).

Specifies file characteristics for a direct access relative file and connects the unit number to the file (like an OPEN statement). Provided for compatibility with compilers older than FORTRAN-77.

Changes the record position in a direct access file. Provided for compatibility with compilers older than FORTRAN-77.

In addition to the READ, WRITE, REWRITE, TYPE, and PRINT statements, other I/O record-related statements are limited to a specific file organization.

For instance:

• The DELETE statement only applies to relative and indexed files.

• The BACKSPACE and REWIND statements only apply to sequential files open for sequential access.

• The ENDFILE statement only applies to certain types of sequential files open for sequential access.

The file-related statements (OPEN, INQUIRE, and CLOSE) apply to any relative or sequential file.

6.4 Forms of I/O Statements

Each type of record I/O statement can be coded in a variety of forms. The form you select depends on the nature of your data and how you want it treated.

When opening a file, specify the form using the FORM specifier. The following are the forms of I/O statements:

• Formatted I/O statements contain explicit format specifiers that are used to control the translation of data from internal (binary) form within a program to external (readable character) form in the records, or vice versa.

HP Fortran Input/Output 6–5

• List-directed and namelist I/O statements are similar to formatted statements in function. However, they use different mechanisms to control the translation of data: formatted I/O statements use explicit format specifiers, and list-directed and namelist I/O statements use data types.

• Unformatted I/O statements do not contain format specifiers and therefore do not translate the data being transferred (important when writing data that will be read later).

Formatted, list-directed, and namelist I/O forms require translation of data from internal (binary) form within a program to external (readable character) form in the records. Consider using unformatted I/O for the following reasons:

• Unformatted data avoids the translation process, so I/O tends to be faster.

• Unformatted data avoids the loss of precision in floating-point numbers when the output data will subsequently be used as input data.

• Unformatted data conserves file storage space (stored in binary form).

To write data to a file using formatted, list-directed, or namelist I/O statements, specify FORM= ’ FORMATTED ’ when opening the file. To write data to a file using unformatted I/O statements, specify FORM= ’ UNFORMATTED ’ when opening the file.

Data written using formatted, list-directed, or namelist I/O statements is referred to as formatted data; data written using unformatted I/O statements is referred to as unformatted data.

When reading data from a file, you should use the same I/O statement form that was used to write the data to the file. For instance, if data was written to a file with a formatted I/O statement, you should read data from that file with a formatted I/O statement.

Although I/O statement form is usually the same for reading and writing data in a file, a program can read a file containing unformatted data (using unformatted input) and write it to a separate file containing formatted data

(using formatted output). Similarly, a program can read a file containing formatted data and write it to a different file containing unformatted data.

As described in Section 6.9.2, you can access records in any sequential, relative, or indexed file using sequential access. For relative files and fixedlength sequential files, you can also access records using direct access. For indexed files, you can use keyed access.

6–6 HP Fortran Input/Output

Table 6–2 shows the main record I/O statements, by category, that can be used in HP Fortran programs.

Table 6–2 Available I/O Statements and Record I/O Forms

File Type, Access, and I/O Form Available Statements

External file, sequential access

Formatted

List-Directed

Namelist

Unformatted

External file, direct access

Formatted

Unformatted

External file, keyed access

Formatted

Unformatted

Internal file

Formatted

List-Directed

Unformatted

READ, WRITE, PRINT, ACCEPT, TYPE 1

READ, WRITE, PRINT, ACCEPT 1

READ, WRITE, PRINT, ACCEPT

READ, WRITE, and REWRITE 1

, TYPE

, and REWRITE

, TYPE 1

, and REWRITE 1

READ, WRITE, and REWRITE

READ, WRITE, and REWRITE 1

READ, WRITE

None

This statement is an HP extension to the Fortran 90 and Fortran 95 standards.

An internal file is a way to reference character data in a buffer using sequential access (see

Section 6.5.2).

6.5 Types of Files and File Characteristics

This section discusses file organization, internal and scratch files, record type, record length, and other file characteristics.

6.5.1 File Organizations

File organization refers to the way records are physically arranged on a storage device.

The default file organization is always ORGANIZATION= ’ SEQUENTIAL ’ for an OPEN statement.

HP Fortran Input/Output 6–7

HP Fortran supports three kinds of file organizations: sequential, relative, and indexed sequential. The organization of a file is specified by means of the

ORGANIZATION specifier in the OPEN statement.

You must store relative files on a disk device. You can store sequential files on magnetic tape or disk devices, and can use other peripheral devices, such as terminals and line printers, as sequential files.

File characteristics, including the file organization and record type, are stored by RMS in the disk file header and can be obtained by using the INQUIRE statement. You can also view the organization of a file using the DCL command

DIRECTORY/FULL.

For more information on the INQUIRE statement, see Section 6.7 and the HP

Fortran for OpenVMS Language Reference Manual.

Sequential Organization

A sequentially organized file consists of records arranged in the sequence in which they are written to the file (the first record written is the first record in the file, the second record written is the second record in the file, and so on).

As a result, records can be added only at the end of the file.

Sequential files are usually read sequentially, starting with the first record in the file. Sequential files stored on disk with a fixed-length record type can also be accessed by relative record number (direct access).

Relative Organization

Within a relative file are numbered positions, called cells. These cells are of fixed equal length and are consecutively numbered from 1 to n, where 1 is the first cell, and n is the last available cell in the file. Each cell either contains a single record or is empty.

Records in a relative file are accessed according to cell number. A cell number is a record’s relative record number (its location relative to the beginning of the file). By specifying relative record numbers, you can directly retrieve, add, or delete records regardless of their locations (direct access).

Relative files allow you to use direct access and detect when a record has been deleted.

When creating a relative file, specify the RECL value to determine the size of the fixed-length cells. Within the cells, you can store variable-length records as long as their size does not exceed the cell size.

6–8 HP Fortran Input/Output

Indexed Files

An indexed file consists of two or more separate sections: one section contains the data records and the other sections contain indexes. When an indexed file is created, each index is associated with a specification defining a field within each record, called a key field or simply key. A record in an indexed file must contain at least one key, called the primary key, which determines the location of the records within the body of the file.

The keys of all records are collected to form one or more structured indexes, through which records are always accessed. The structure of the indexes allows a program to access records in an indexed file either randomly (keyed access) or sequentially (sequential access). With keyed access, you specify a particular key value. With sequential access, you retrieve records with increasing or decreasing key values. You can mix keyed access and sequential access.

Indexed files are supported only on disk devices. When creating an indexed file, specify the RECL value.

For more information on indexed files, see Chapter 12.

6.5.2 Internal Files and Scratch Files

HP Fortran also supports two other types of files that are not file organizations—namely, internal files and scratch files.

Internal Files

You can use an internal file to reference character data in a buffer when using sequential access. The transfer occurs between internal storage and internal storage (unlike external files), such as between character variables and a character array.

An internal file consists of any of the following:

• Character variable

• Character-array element

• Character array

• Character substring

• Character array section without a vector subscript

Instead of specifying a unit number for the READ or WRITE statement, use an internal file specifier in the form of a character scalar memory reference or a character-array name reference.

HP Fortran Input/Output 6–9

An internal file is a designated internal storage space (variable buffer) of characters that is treated as a sequential file of fixed-length records. To perform internal I/O, use formatted and list-directed sequential READ and

WRITE statements. You cannot use such file-related statements such as OPEN and INQUIRE on an internal file (no unit number is used).

If an internal file is made up of a single character variable, array element, or substring, that file comprises a single record whose length is the same as the length of the variable, array element, or substring. If an internal file is made up of a character array, that file comprises a sequence of records, with each record consisting of a single array element. The sequence of records in an internal file is determined by the order of subscript progression.

A record in an internal file can be read only if the character variable, array element, or substring comprising the record has been defined (a value has been assigned to the record).

Prior to each READ and WRITE statement, an internal file is always positioned at the beginning of the first record.

Scratch Files

Scratch files are created by specifying STATUS= ’ SCRATCH ’ on an OPEN statement. By default, the files are created on the user’s default disk

(SYS$DISK) and are not placed in a directory or given a name that is externally visible (accessible using the DCL command DIRECTORY).

You can create scratch files on a disk other than the default disk by using the

FILE specifier in an OPEN statement.

6.5.3 I/O Record Types

Record type refers to whether records in a file are all the same length, are of varying length, or use other conventions to define where one record ends and another begins.

You can use fixed-length and variable-length record types with sequential, relative, or indexed files. You can use any of the record types with sequential files.

Records are stored in one of the following record types:

• Fixed-length

• Variable-length

• Segmented

• Stream

6–10 HP Fortran Input/Output

• Stream_CR

• Stream_LF

You can use fixed-length and variable-length record types with sequential, relative, or indexed files.

Before you choose a record type, consider whether your application will use formatted or unformatted data. If you will be using formatted data, you can use any record type except segmented. When using unformatted data, you should avoid using the stream, stream_CR, and stream_LF record types.

The segmented record type is unique to HP Fortran products; it is not used by other OpenVMS-supported languages. It can only be used for unformatted sequential access with sequential files. You should not use segmented records for files that are read by programs written in languages other than Fortran.

The stream, stream_CR, stream_LF, and segmented record types can only be used with sequential files.

6.5.3.1 Portability Considerations of Record Types

Consider the following portability needs when choosing a record type:

• Data files from HP Fortran and Compaq Fortran 77 on OpenVMS systems are interchangeable.

• You can use any any record type except segmented with other non-Fortran

OpenVMS languages.

HP Fortran indexed files are portable only to other OpenVMS systems.

However, a conversion program can read the records from an indexed file and write them to another file, such as a sequential (or relative) file.

6.5.3.2 Fixed-Length Records

When you create a file that uses the fixed-length record type, you must specify the record size. When you specify fixed-length records, all records in the file must contain the same number of bytes. (The HP Fortran for OpenVMS

Language Reference Manual discusses fixed-length records.)

A sequential file opened for direct access must contain fixed-length records, to allow the record position in the file to be computed correctly.

You can obtain the record length (RECL) before opening the file with unformatted data by using a form of the INQUIRE statement (see Section 6.7.3).

HP Fortran Input/Output 6–11

6.5.3.3 Variable-Length Records

Variable-length records can contain any number of bytes, up to a specified maximum. These records are prefixed by a count field, indicating the number of bytes in the record. The count field comprises two bytes on a disk device and four bytes on magnetic tape. The value stored in the count field indicates the number of data bytes in the record.

Variable-length records in relative files are actually stored in fixed-length cells, the size of which must be specified by means of the RECL specifier in an OPEN statement (see the HP Fortran for OpenVMS Language Reference Manual for details). This RECL value specifies the largest record that can be stored in the file.

The count field of a formatted variable-length record is available when you read the record by issuing a READ statement with a Q format descriptor. You can then use the count field information to determine how many bytes should be in an I/O list.

6.5.3.4 Segmented Records

A segmented record is a single logical record consisting of one or more variablelength, unformatted records in a sequential file. Each variable-length record constitutes a segment. The length of a segmented record is arbitrary.

Segmented records are useful when you want to write exceptionally long records but cannot or do not wish to define one long variable-length record.

When writing unformatted data to a sequential file using sequential access, the default record type is segmented.

As shown in Figure 6–1, the layout of segmented records consists of control information followed by the user data. On disk, the control information consists of four bytes for compatibility with other HP Fortran platforms.

However, OpenVMS RMS removes the first two length bytes when the record is read, so each record has two control bytes (flags) in memory.

Figure 6–1 Segmented Records

LENGTH (n)

FLAGS

ACTUAL DATA

LENGTH (n)

ZK−7916A−GE

6–12 HP Fortran Input/Output

The control information consists of a 2-byte integer record size count (includes the two bytes used by the segment identifier), followed by a 2-byte integer segment identifier that identifies this segment as one of the following:

Identifier Value

Segment Identified

One of the segments between the first and last segments.

First segment.

Last segment.

Only segment.

When you wish to access an unformatted sequential file that contains variablelength records, you must specify FORM= ’ UNFORMATTED ’ when you open the file. If the unformatted data file was not created using an HP Fortran product, specify RECORDTYPE=

’

VARIABLE

’

. If the unformatted data file was created using the segmented record type using an HP Fortran Fortran product, specify RECORDTYPE=

’

SEGMENTED

’

Otherwise, the first two bytes of each record will be mistakenly interpreted as control information, and errors will probably result.

You can obtain the record length (RECL) before opening the file with unformatted data using a form of the INQUIRE statement (see Section 6.7.3).

6.5.3.5 Stream Records

A stream record is a variable-length record whose length is indicated by explicit record terminators embedded in the data, not by a count.

Stream files use the 2-character sequence consisting of a carriage-return and a line-feed as the record terminator. These terminators are automatically added when you write records to a stream file and removed when you read records.

Stream records resemble the Stream_CR or Stream_LF records shown in

Figure 6–2, but use a 2-byte record terminator (carriage-return and line-feed) instead of a 1-byte record terminator.

6.5.3.6 Stream_CR and Stream_LF Records

A Stream_CR or Stream_LF record is a variable-length record whose length is indicated by explicit record terminators embedded in the data, not by a count. These terminators are automatically added when you write records to a stream-type file and are removed when you read records.

Each variety uses a different 1-byte record terminator:

• Stream_CR files use only a carriage-return as the terminator, so Stream_

CR files must not contain embedded carriage-return characters.

HP Fortran Input/Output 6–13

• Stream_LF files use only a line-feed (new line) as the terminator, so

Stream_LF files must not contain embedded line-feed (new line) characters.

The layout of Stream_CR and Stream_LF records appears in Figure 6–2.

Figure 6–2 Stream_CR and Stream_LF Records

User Data

Record length (RECL=value) 1

ZK−9823−GE

6.5.4 Other File Characteristics

Other file characteristics include:

• Carriage control attributes of each record (CARRIAGECONTROL specifier)

• Whether formatted or unformatted data is contained in the records (FORM specifier)

• The record length (RECL specifier)

• Whether records can span block boundaries (NOSPANBLOCK specifier)

• For an indexed file being created, the key number, its location, and its data type (KEY specifier)

The units used for specifying record length depend on the form of the data:

• For formatted files (FORM= ’ FORMATTED ’ ), specify the record length in bytes.

• For unformatted files (FORM= ’ UNFORMATTED ’ ), specify the record length in 4-byte units, unless you specify the /ASSUME=BYTERECL qualifier to request 1-byte units (see Section 2.3.7).

For More Information:

• On statement syntax and specifier values (including defaults), see the HP

Fortran for OpenVMS Language Reference Manual.

• On file characteristics, see Section 6.6.3 and the OPEN statement in the

HP Fortran for OpenVMS Language Reference Manual.

• On I/O performance considerations, see Section 5.5.

6–14 HP Fortran Input/Output

6.6 Opening Files and the OPEN Statement

You can choose to open files by:

• Using default values, such as a preconnected unit. In the following example, the PRINT statement is associated with a preconnected unit

(SYS$OUTPUT) by default:

PRINT *,100

Implicitly opening a file by omitting an OPEN statement prevents you from specifying the file connection characteristics and other information provided by the OPEN statement. You might use implicit opening of a file for terminal I/O.

The following READ statement associates the logical unit 7 with the file

FOR007.DAT (because the FILE specifier was omitted) by default:

OPEN (UNIT=7,STATUS=’OLD’)

READ (7,100)

• Using default logical names, which allows you to specify which file or files are used at run time. If the following example uses an implicit OPEN, the

READ statement causes the logical name FOR007 to be associated with the file FOR007.DAT by default. The TYPE statement causes the logical unit

FOR$TYPE to be associated with SYS$OUTPUT by default.

READ (7,100)

TYPE 100

• Using logical names without an OPEN statement. You can also use DCL commands to set the appropriate logical names to a value that indicates a directory (if needed) and a file name to associate a unit with an external file.

• Specifying a logical name in an OPEN statement. This allows you to specify which file or files are used at run time, but the appropriate logical names must be defined before the program is run. For example:

OPEN (UNIT=7, FILE=’LOGNAM’, STATUS=’OLD’)

• Specifying a file specification in an OPEN statement. The file or files are specified at compile time, so the program may need to be recompiled to specify a different file (or the default device and directory changed if these are not specified by the program). For example:

HP Fortran Input/Output 6–15

OPEN (UNIT=7, FILE=’FILNAM.DAT’, STATUS=’OLD’)

If you choose to specify a logical name with the FILE specifier in an OPEN statement, that logical name must be associated with a file specification and the character expression specified for the logical name must contain no punctuation marks.

6.6.1 Preconnected Files and Fortran Logical Names

You can use OpenVMS logical names to associate logical units with file specifications. A logical name is a string up to 255 characters long that you can use as part of a file specification.

Table 6–3 lists the OpenVMS process logical names for standard I/O devices already associated with particular file specifications.

Table 6–3 Predefined System Logical Names

OpenVMS Logical

Name Meaning Default

SYS$COMMAND Default command stream

SYS$DISK

SYS$ERROR

SYS$INPUT

SYS$OUTPUT

Default disk device

Default error stream

Default input stream

Default output stream

For an interactive user, the default is the terminal; for a batch job, the default is the batch job input command file.

As specified by user.

For an interactive user, the default is the terminal; for a batch job, the default is the batch job log file.

For an interactive user, the default is the terminal; for a batch job, the default is the batch command file.

For an interactive user, the default is the terminal; for a batch job, the default is the batch log file.

You can dynamically create a logical name and associate it with a file specification by means of the DCL commands ASSIGN or DEFINE. For example, before program execution, you can define each logical name recognized by your program with a file specification appropriate to your needs without recompiling and relinking the program. For example:

$ DEFINE LOGNAM USERD:[SMITH]TEST.DAT;2

The preceding command creates the logical name LOGNAM and associates it with the file specification USERD:[SMITH]TEST.DAT;2. As a result, this file specification is used whenever the logical name LOGNAM is encountered during program execution.

6–16 HP Fortran Input/Output

The following statement opens the file associated with the current definition of the logical name LOGNAM:

OPEN (UNIT=7, FILE=’LOGNAM’, STATUS=’OLD’)

Logical names provide great flexibility because they can be associated with either a partial or complete file specification (with either a device or a device and a directory), or even another logical name.

6.6.1.1 Preconnected Files

ACCEPT, TYPE, and PRINT statements do not refer explicitly to a logical unit

(a file or device) from which or to which data is to be transferred; they refer implicitly to a default preconnected logical unit. ACCEPT refers to the default input device SYS$INPUT. TYPE and PRINT refer to the default output device

SYS$OUTPUT. These defaults can be overridden with appropriate logical name assignments (see Section 6.6.1.2).

READ, WRITE, and REWRITE usually refer to explicit unit numbers. If you do not use an OPEN statement to open logical unit 5 or 6 without setting the appropriate logical name (FORnnn), unit number 5 is associated with

SYS$INPUT and unit 6 with SYS$OUTPUT.

To redirect I/O to an external disk file instead of these preconnected files, you can either use an OPEN statement to unit 5 and 6 or set the appropriate logical name. If you set the corresponding HP Fortran logical name, the file specified by that HP Fortran logical name is used.

The order of precedence when you open a file is:

• When you explicitly open a preconnected file by using an OPEN statement with a file name for that unit, the Fortran logical name and OpenVMS standard I/O device are not used. The file is no longer considered preconnected.

If the file name is not present in the OPEN statement, the unit is still preconnected as shown in Table 6–4.

• If the appropriate Fortran logical name is defined, its definition is used instead of the OpenVMS standard I/O logical name.

• If the Fortran logical name is not defined, the OpenVMS standard I/O logical name is used.

HP Fortran Input/Output 6–17

• For units not associated with a preconnected OpenVMS standard I/O device, if you omit the file name and file type, the system supplies certain defaults, such as a file name and type of FORnnn.DAT (see Section 6.6.1.2.

Table 6–4 shows the I/O statements and their associated Fortran logical names and OpenVMS standard I/O logical names.

Table 6–4 Implicit Fortran Logical Units

Statement Fortran Logical Name

READ (*,f) iolist

READ f,iolist

ACCEPT f,iolist

FOR$READ

FOR$ACCEPT

WRITE (*,f) iolist FOR$PRINT

PRINT f,iolist FOR$PRINT

TYPE f,iolist

READ (5),iolist

WRITE (6),iolist

FOR$TYPE

FOR005

FOR006

Equivalent OpenVMS Logical Name

SYS$INPUT

SYS$OUTPUT

SYS$INPUT

SYS$OUTPUT

If the Fortran logical name is defined, it is used; if the Fortran logical name is not defined, the

OpenVMS standard I/O logical names are used.

You can change the file specifications associated with these Fortran logical names by using the DCL commands DEFINE or ASSIGN.

6.6.1.2 HP Fortran Logical Names

HP Fortran I/O is usually performed by associating a logical unit number with a device or file. OpenVMS logical names provide an additional level of association; a user-specified logical name can be associated with a logical unit number.

HP Fortran provides predefined logical names in the following form:

FORnnn

The notation nnn represents a logical unit number, any non-negative 4-byte integer (maximum value is 2,147,483,647). For example, for logical unit 12, the predefined logical name would be FOR012; for logical unit 1024, the predefined logical name would be FOR1024.

By default, each Fortran logical name is associated with a file named

FORnnn.DAT on your default disk under your default directory. For example:

WRITE (17,200)

6–18 HP Fortran Input/Output

If you enter the preceding statement without including an explicit file specification, the data is written to a file named FOR017.DAT on your default disk under your default directory.

You can change the file specification associated with a Fortran logical unit number by using the DCL commands ASSIGN or DEFINE to change the file associated with the corresponding Fortran logical name. For example:

$ DEFINE FOR017 USERD:[SMITH]TEST.DAT;2

The preceding command associates the Fortran logical name FOR017 (and therefore logical unit 17) with file TEST.DAT;2 on device USERD in directory

[SMITH].

You can also associate the Fortran logical names with any of the predefined system logical names, as shown in the following examples:

• The following command associates logical unit 10 with the default output device (for example, the batch output stream):

$ DEFINE FOR010 SYS$OUTPUT

• The following command associates the default command stream with the default input device (for example, the batch input stream):

$ DEFINE SYS$COMMAND SYS$INPUT

For More Information:

On the DCL commands you can use to assign or deassign logical names, see

Appendix D.

6.6.2 Disk Files and File Specifications

Most I/O operations involve a disk file, keyboard, or screen display. You can access the terminal screen or keyboard by using preconnected files, as described in Section 6.6. Otherwise, this chapter discusses disk files.

HP Fortran recognizes logical names for each logical I/O unit number in the form of FORnnn, where nnn is the logical I/O unit number, with leading zeros for fewer than three digits. If a file name is not specified in the OPEN statement and the corresponding FORnnn logical name is not set for that unit number, HP Fortran generates a file name in the form FORnnn.DAT, where n is the logical unit number.

Certain HP Fortran logical names are recognized and preconnected files exist for certain unit numbers. Performing an implied OPEN means that the FILE and DEFAULTFILE specifier values are not specified and a logical name is used, if present.

HP Fortran Input/Output 6–19

A complete OpenVMS file specification has the form: node::device:[directory]filename.filetype;version

For example:

BOSTON::USERD:[SMITH]TEST.DAT;2

You can associate a file specification with a logical unit by using a logical name assignment (see Section 6.6.1) or by using an OPEN statement (see

Section 6.6.2). If you do not specify such an association or if you omit elements of the file specification, the system supplies default values, as follows:

• If you omit the node, the local computer is used.

• If you omit the device or directory, the current user default device or directory is used.

• If you omit the file name, the system supplies FORnnn (where nnn is the logical unit number, with leading zeros for one- or two-digit numbers)

• If you omit the file type, the system supplies DAT.

• If you omit the version number, the system supplies either the highest current version number (for input) or the highest current version number plus 1 (for output).

For example, if your default device is USERD and your default directory is

SMITH, and you specified the following statements:

READ (8,100)

WRITE (9,200)

The default input file specification would be:

USERD:[SMITH]FOR008.DAT;n

The default output file specification would be:

USERD:[SMITH]FOR009.DAT;m

In these examples, n equals the highest current version number of

FOR008.DAT and m is 1 greater than the highest existing version number of FOR009.DAT.

6–20 HP Fortran Input/Output

You can use the FILE and DEFAULTFILE specifiers in an OPEN statement to specify the complete definition of a particular file to be opened on a logical unit. For example:

OPEN (UNIT=4, FILE=’USERD:[SMITH]TEST.DAT;2’, STATUS=’OLD’)

In the preceding example, the existing file TEST.DAT;2 on device USERD in directory SMITH is to be opened on logical unit 4. Neither the default file specification (FOR004.DAT) nor the Fortran logical name FOR004 is used. The value of the FILE specifier can be a character constant, variable, or expression.

HP Fortran provides the following possible ways of specifying all or part of a file specification (directory and file name), such as DISK2:[PROJECT.DATA]:

• The FILE specifier in an OPEN statement typically specifies only a file name (such as TESTDATA) or contains both a directory and file name

(such as DISK2:[PROJECT.DATA]TESTDATA).

• The DEFAULTFILE specifier (an HP extension) in an OPEN statement typically specifies a device and/or directory without a file name or a device and/or directory with a file name (such as

DISK2:[PROJECT.DATA]TESTDATA).

• If you used an implied OPEN or if the FILE specifier in an OPEN statement did not specify a file name, you can use a logical name to specify a file name or a device and/or directory that contains both a directory and file name (see Section 6.6.1).

In the following interactive example, the file name is supplied by the user and the DEFAULTFILE specifier supplies the default values for the file specification string. The file to be opened is in device and directory

DISK4:[PROJ] and is merged with the file name typed by the user into the variable DOC:

CHARACTER(LEN=40) DOC

WRITE (6,*) ’Type file name ’

READ (5,*) DOC

OPEN (UNIT=2, FILE=DOC, DEFAULTFILE=’DISK4:[PROJ]’,STATUS=’OLD’)

The DEFAULTFILE specification overrides your process default device and directory.

You can also specify a logical name as the value of the FILE specifier, if the logical name is associated with a file specification. If the logical name

LOGNAM is defined to be the file specification USERD:[SMITH]TEST.DAT, the logical name can then be used in an OPEN statement, as follows:

OPEN (UNIT=19, FILE=’LOGNAM’, STATUS=’OLD’)

HP Fortran Input/Output 6–21

When an I/O statement refers to logical unit 19, the system uses the file specification associated with logical name LOGNAM.

If the value specified for the FILE specifier has no associated file specification, it is regarded as a true file name rather than as a logical name. Suppose

LOGNAM had not been previously associated with the file specification by using an ASSIGN or DEFINE command. The OPEN statement would indicate that a file named LOGNAM.DAT is located on the default device, in the default directory.

For an example program that reads a typed file name, uses the typed name to open a file, and handles such errors as the ‘‘file not found’’ error, see

Example 7–1.

For a detailed description of OpenVMS file specifications, see the Guide to

OpenVMS File Applications.

For More Information:

• On a list of HP Fortran I/O statements, see Table 6–1.

• On record I/O, see Section 6.9.

• On HP Fortran I/O statements and specifier values, including defaults, see

Table 6–1.

• On statement syntax, see the HP Fortran for OpenVMS Language

Reference Manual.

• On the ERR and IOSTAT specifiers, see Chapter 7.

• On closing files, see Section 6.8.

6.6.3 OPEN Statement Specifiers

The OPEN statement connects a unit number with an external file and allows you to explicitly specify file attributes and run-time options using OPEN statement specifiers. Once you open a file, you should close it before opening it again unless it is a preconnected file.

If you open a unit number that was opened previously (without being closed), one of the following occurs:

• If you specify a file specification that does not match the one specified for the original open, the HP Fortran run-time system closes the original file and then reopens the specified file.

This resets the current record position for the second file.

6–22 HP Fortran Input/Output

• If you specify a file specification that does match the one specified for the original open, the file is reconnected without the internal equivalent of the

CLOSE and OPEN.

This lets you change one or more OPEN statement run-time specifiers while maintaining the record position context.

You can use the INQUIRE statement (see Section 6.7) to obtain information about a whether or not a file is opened by your program.

Especially when creating a new file using the OPEN statement, examine the defaults (see the description of the OPEN statement in the HP Fortran for

OpenVMS Language Reference Manual) or explicitly specify file attributes with the appropriate OPEN statement specifiers.

The OPEN statement functions and their specifiers are:

• Identify File and Unit

\ UNIT specifies the logical unit number.

\ FILE (or NAME

) and DEFAULTFILE

1 name of an external file.

specify the directory and/or file

\ STATUS or TYPE

1 indicates whether to create a new file, overwrite an existing file, open an existing file, or use a scratch file.

\ STATUS or DISPOSE

1 specifies the file existence status after CLOSE.

• File and Record Characteristics

\ ORGANIZATION

1 indexed).

indicates the file organization (sequential, relative, or

\ RECORDTYPE

1 indicates which record type to use.

\ FORM indicates whether records are formatted or unformatted. See

Section 6.5.4 and Section 6.4.

\ CARRIAGECONTROL

1 indicates the terminal control type.

\ KEY

1 indicates (when creating an indexed file) the key number, its type, and its location.

\ NOSPANBLOCKS

1 boundaries.

indicates that the records should not span block

\ RECL or RECORDSIZE

1 specifies the record size. See Section 6.5.4.

• Special File Open Routine

1 This specifier is an HP Fortran extension.

HP Fortran Input/Output 6–23

\ USEROPEN

1 names the routine that will open the file to establish special context that changes the effect of subsequent HP Fortran I/O statements

(see Chapter 11).

• File Access, Processing, and Position

\ ACCESS indicates the access mode (direct, keyed, or sequential). See

Section 6.9.2.

\ ACTION or READONLY

1 indicates whether statements will be used to only read records, only write records, or read and write records. See

Section 6.9.3.

\ POSITION indicates whether to position the file at the beginning of file, before the end-of-file record, or leave it as is (unchanged). See Section 6.9.4.

\ SHARED

1 indicates that other users can access the same file and activates record locking. See Section 6.9.3.

\ MAXREC

1 specifies the maximum record number for direct access.

\ ASSOCIATEVARIABLE

1 number for direct access.

specifies the variable containing next record

• File Allocation

\ INITIALSIZE

1 file.

indicates the allocation unit (in blocks) when creating a

\ EXTENDSIZE

1 indicates the allocation unit (in blocks) when allocation additional file space.

• Record Transfer Characteristics

\ BLANK indicates whether to ignore blanks in numeric fields.

\ DELIM specifies the delimiter character for character constants in list-directed or namelist output.

\ PAD, when reading formatted records, indicates whether padding characters should be added if the item list and format specification require more data than the record contains.

\ BLOCKSIZE

1 specifies the block physical I/O buffer size.

\ BUFFERCOUNT

1 specifies the number of physical I/O buffers.

\ CONVERT

Chapter 9.

specifies the format of unformatted numeric data. See

• Error Handling Capabilities

\ ERR specifies a label to branch to if an error occurs. See Chapter 7.

6–24 HP Fortran Input/Output

• \ IOSTAT specifies the integer variable to receive the error (IOSTAT) number if an error occurs. See Chapter 7.

• File Close Action

\ DISPOSE

1 identifies the action to take when the file is closed.

For More Information:

• On specifier syntax and complete information, see the HP Fortran for

OpenVMS Language Reference Manual.

• On the FORM specifier, see Section 6.4.

• On file organizations, see Section 6.5.1.

• On available record types, see Section 6.5.3.

• On the CARRIAGECONTROL specifier, see Section 6.5.4.

• On the RECL (record length) specifier, see Section 6.5.4.

• On shared access to files, see Section 6.9.3.

• On the ERR and IOSTAT specifiers, see Chapter 7.

• On obtaining file information using the INQUIRE statement, see

Section 6.7.

• On closing files, see Section 6.8.

• Record I/O transfer, see Section 6.9.6.

• Record advancement, see Section 6.9.5.

• Record positioning, see Section 6.9.4.

• On I/O performance considerations, see Section 5.5.

6.7 Obtaining File Information: The INQUIRE Statement

The INQUIRE statement returns information about a file and has three forms:

• Inquiry by unit

• Inquiry by file name

• Inquiry by output item list

HP Fortran Input/Output 6–25

6.7.1 Inquiry by Unit

An inquiry by unit is usually done for an opened (connected) file. An inquiry by unit causes the HP Fortran RTL to check whether the specified unit is connected or not. One of the following occurs:

• If the unit is connected:

The EXIST and OPENED specifier variables indicate a true value.

The file specification is returned in the NAME specifier variable (if the file is named).

Other information requested on the previously connected file is returned.

Default values are usually returned for the INQUIRE specifiers also associated with the OPEN statement (see Section 6.6.3)

The RECL value unit for connected formatted files is always 1-byte units. For unformatted files, the RECL unit is 4-byte units, unless you specify the /ASSUME=BYTERECL qualifier to request 1-byte units (see

Section 2.3.7).

• If the unit is not connected:

The OPENED specifier indicates a false value.

The unit NUMBER specifier variable is returned as a value of –1.

Any other information returned will be undefined or default values for the various specifiers.

For example, the following INQUIRE statement shows whether unit 3 has a file connected (OPENED specifier) in logical variable I_OPENED, the name

(case sensitive) in character variable I_NAME, and whether the file is opened for READ, WRITE, or READWRITE access in character variable I_ACTION:

INQUIRE (3, OPENED=I_OPENED, NAME=I_NAME, ACTION=I_ACTION)

6.7.2 Inquiry by File Name

An inquiry by name causes the HP Fortran RTL to scan its list of open files for a matching file name. One of the following occurs:

• If a match occurs:

The EXIST and OPENED specifier variables indicate a true value.

The full file specification is returned in the NAME specifier variable.

The UNIT number is returned in the NUMBER specifier variable.

6–26 HP Fortran Input/Output

Other information requested on the previously connected file is returned.

Default values are usually returned for the INQUIRE specifiers also associated with the OPEN statement (see Section 6.6.3).

Section 2.3.7).

• If no match occurs:

The OPENED specifier variable indicates a false value.

The unit NUMBER specifier variable is returned as a value of –1.

The EXIST specifier variable indicates (true or false) whether the named file exists on the device or not.

If the file does exist, the NAME specifier variable contains the full file specification.

Any other information returned will be file characteristics maintained in the file header or default values for the various specifiers, based on any information specified when calling INQUIRE.

The following INQUIRE statement returns whether the file named LOG_FILE is a file connected in logical variable I_OPEN, whether the file exists in logical variable I_EXIST, and the unit number in integer variable I_NUMBER.

INQUIRE (FILE=’log_file’, OPENED=I_OPEN, EXIST=I_EXIST, NUMBER=I_NUMBER)

6.7.3 Inquiry by Output Item List

Unlike inquiry by unit or inquiry by name, inquiry by output item list does not attempt to access any external file. It returns the length of a record for a list of variables that would be used for unformatted WRITE, READ, and REWRITE statements (REWRITE is an HP Fortran extension).

The following INQUIRE statement returns the maximum record length of the variable list in integer variable I_RECLENGTH. This variable is then used to specify the RECL value in the OPEN statement:

INQUIRE (IOLENGTH=I_RECLENGTH) A, B, H

OPEN (FILE=’test.dat’, FORM=’UNFORMATTED’, RECL=I_RECLENGTH, UNIT=9)

For an unformatted file, the RECL value is returned using 4-byte units, unless you specify the /ASSUME=BYTERECL qualifier to request 1-byte units.

HP Fortran Input/Output 6–27

For More Information:

• On the INQUIRE statement and its specifiers, see the HP Fortran for

OpenVMS Language Reference Manual.

• On record I/O, see Section 6.9.

• On OPEN statement specifiers, see Section 6.6.3.

• On the /ASSUME=BYTERECL qualifier, see Section 2.3.7.

6.8 Closing a File: The CLOSE Statement

Usually, any external file opened should be closed by the same program before it completes. The CLOSE statement disconnects the unit and its external file.

You must specify the unit number (UNIT specifier) to be closed.

You can also specify:

• Whether the file should be deleted or kept (STATUS specifier).

• Error handling information (ERR and IOSTAT specifiers).

To delete a file when closing it:

• In the OPEN statement, specify the ACTION keyword (such as

ACTION=’READ’). Avoid using the READONLY keyword, because a file opened using the READONLY keyword cannot be deleted when it is closed.

• In the CLOSE statement, specify the keyword STATUS=’DELETE’. (Other

STATUS keyword values include ’SUBMIT’ and ’PRINT’.)

If you opened an external file and did an inquire by unit, but do not like the default value for the ACCESS specifier, you can close the file and then reopen it, explicitly specifying the ACCESS desired.

There usually is no need to close preconnected units. Internal files are neither opened nor closed.

For More Information:

• On a list of HP Fortran I/O statements, see Table 6–1.

• On changing default I/O characteristics before using HP Fortran I/O statements, see Chapter 11.

• On OPEN statement specifiers, see Section 6.6.3.

• On statement syntax and specifier values (such as other STATUS values), see the HP Fortran for OpenVMS Language Reference Manual.

6–28 HP Fortran Input/Output

6.9 Record Operations

After you open a file or use a preconnected file, you can use the following statements:

• READ, WRITE and PRINT to perform record I/O.

• BACKSPACE, ENDFILE, REWIND to set record position within the file.

• ACCEPT, DELETE, REWRITE, TYPE, DEFINE FILE, and FIND to perform various operations. These statements are HP extensions.

These statements are described in Section 6.3 and the HP Fortran for

OpenVMS Language Reference Manual.

The record I/O statement must use the appropriate record I/O form (formatted, list-directed, namelist, or unformatted), as described in Section 6.4.

6.9.1 Record I/O Statement Specifiers

You can use the following specifiers with the READ and WRITE record I/O statements:

• UNIT specifies the unit number to or from which input or output will occur.

• END specifies a label to branch to if an error occurs; only applies to input statements like READ.

• ERR specifies a label to branch to if an error occurs.

• IOSTAT specifies an integer variable to contain the IOSTAT number if an error occurs.

• FMT specifies a label of a FORMAT statement.

• NML specifies the name of a NAMELIST group.

• For direct access, REC specifies a record number.

• For keyed access:

KEYID specifies the key of reference.

KEY, KEYNXT, KEYNXTNE, KEYLT, KEYEQ, KEYLE, and KEYGT specify the key value and key match characteristics.

When using nonadvancing I/O, use the ADVANCE, EOR, and SIZE specifiers, as described in Section 6.9.5.

When using the REWRITE statement (an HP Fortran extension), you can use the UNIT, FMT, ERR, and IOSTAT specifiers.

HP Fortran Input/Output 6–29

For More Information

• On specifier syntax and complete information, see the HP Fortran for

OpenVMS Language Reference Manual.

• On available record types, see Section 6.5.3.

• On the error-related record I/O specifiers ERR, END, and IOSTAT, see

Chapter 7.

• On the ADVANCE, EOR, and SIZE specifiers, see Section 6.9.5.

• On record positioning, see Section 6.9.4.

• On record I/O transfer, see Section 6.9.6.

• On record advancement, see Section 6.9.5.

6.9.2 Record Access Modes

Record access refers to how records will be read from or written to a file, regardless of its organization. Record access is specified each time you open a file; it can be different each time.

The type of record access permitted is determined by the combination of file organization and record type. Access mode is the method a program uses to retrieve and store records in a file. The access mode is specified as part of each

I/O statement.

HP Fortran supports three record access modes:

• Sequential access—transfers records sequentially to or from files

(sequential, relative, or indexed) or I/O devices such as terminals.

• Direct access—transfers records selected by record number to and from fixed-length sequential files or relative organization files.

• Keyed access—transfers records to and from indexed files, based on data values (keys) contained in the records, using the current key-of-reference.

Your choice of record access mode is affected by the organization of the file to be accessed. For example, the keyed access mode can be used only with indexed organization files.

Table 6–5 shows all of the valid combinations of access mode and file organization.

6–30 HP Fortran Input/Output

Table 6–5 Valid Combinations of File Organization and Record Access Mode

File Organization Sequential

Sequential

Relative

Indexed

Yes

Direct

Yes 1

Yes

Keyed

Yes

Fixed-length records only.

6.9.2.1 Sequential Access

If you select the sequential access mode for sequential or relative files, records are written to or read from the file starting at the beginning and continuing through the file, one record after another. For indexed files, sequential access can be used to read or write all records according to the direction of the key and the key values. Sequential access to indexed files can also be used with keyed access to read or write a group of records at a specified point in the file.

When you use sequential access for sequential and relative files, a particular record can be retrieved only after all of the records preceding it have been read.

Writing records by means of sequential access also varies according to the file organization:

• For sequential files, new records can be written only at the end of the file.

• For relative files, a new record can be written at any point, replacing the existing record in the specified cell. For example, if two records are read from a relative file and then a record is written, the new record occupies cell 3 of the file.

• For indexed files, records must be written in primary key order, and READ operations refer to the next record meeting the key selection criteria.

6.9.2.2 Direct Access

If you select direct access mode, you determine the order in which records are read or written. Each READ or WRITE statement must include the relative record number, indicating the record to be read or written.

You can access relative files directly. You can also access a sequential disk file directly if it contains fixed-length records. Because direct access uses cell numbers to find records, you can issue successive READ or WRITE statements requesting records that either precede or follow previously requested records.

The following statements read record 24, then read record 10.

HP Fortran Input/Output 6–31

READ (12,REC=24) I

READ (12,REC=10) J

6.9.2.3 Keyed Access

If you select keyed access mode, you determine the order in which records are read or written by means of character values or integer values called keys.

Each READ statement contains the key that locates the record. The key value in the I/O statement is compared with index entries until the record is located.

When you insert a new record, the values contained in the key fields of the record determine the record’s placement in the file; you do not have to indicate a key.

You can use keyed access only for indexed files.

Your program can mix keyed access and sequential access I/O statements on the same file. You can use keyed I/O statements to position the file to a particular record, then use sequential I/O statements to access records with either increasing or decreasing key values (depending on the key chosen).

For More Information

On using indexed files, see Chapter 12.

6.9.3 Shared File Use

With the RMS file-sharing capability, you can allow file access by more than one program at a time or by the same program on more than one logical unit.

There are two kinds of file sharing:

• Read sharing occurs when multiple programs are reading a file at the same time.

• Write sharing takes place when at least one program is writing a file and at least one other program is either reading or writing the same file.

All three file organizations—relative, indexed, and sequential—permit read and write access to shared files.

The extent to which file sharing can take place is determined by two factors: the type of device on which the file resides and the explicit information supplied by the user. These factors have the following effects:

• Device type—Sharing is possible only on disk files.

• Explicit file-sharing information supplied by accessing programs—Whether file sharing actually takes place depends on information provided to

OpenVMS RMS by each program accessing the file. In HP Fortran programs, this information is supplied by the ACTION specifier (or HP

6–32 HP Fortran Input/Output

extension READONLY specifier) and the SHARED specifier in the OPEN statement.

Read sharing is accomplished when the OPEN statement specifies the

ACTION=’READ’ (or READONLY) specifier by all programs accessing the file.

Write sharing is accomplished when the program specifies SHARED with either ACTION=’WRITE’ or ACTION=’READWRITE’ (the default is ACTION=’READWRITE’ unless you specify ACTION=’READ’ or

READONLY).

Programs that specify ACTION=’READ’ (or READONLY) or ’SHARED’ can access a file simultaneously, with the exception that a file opened for

ACTION=’READ’ (READONLY) cannot be accessed by a program that specifies SHARED.

Depending on the value specified by the ACTION (or READONLY) specifier in the OPEN statement, the file will be opened by your program for reading, writing, or both reading and writing records. This simply checks that the program itself executes the type of statements intended, unless the OPEN statement specifies the SHARED specifier.

To allow other users to access the same file once you have opened it, specify the OPEN statement SHARED specifier when you open the file. If you specify the SHARED specifier when opening a file that is already opened by another process, your program will be allowed to access the file.

If you omit the SHARED specifier when opening a file that is already opened by another process, your program will be denied access to the file. If you omit the SHARED specifier and are the first to open that files, file access might be denied to other users later requesting access to the file.

For performance reasons, when writing records to the file, avoid specifying the

SHARED qualifier when you are certain that no other processes will access that file. Similarly, unless you will be writing records when specifying the

SHARED qualifier, specify ACTION= ’ READ ’ .

When two or more programs are write sharing a file, each program should use one of the error-processing mechanisms described in Chapter 14.

Use of one of these controls, the RMS record-locking facility, prevents program failure due to a record-locking error.

The RMS record-locking facility, along with the logic of the program, prevents two processes from accessing the same record at the same time. Record locking ensures that a program can add, delete, or update a record without having to

HP Fortran Input/Output 6–33

check whether the same record is simultaneously being accessed by another process.

When a program opens a relative, sequential, or indexed file specifying

SHARED, RMS locks each record as it is accessed. When a record is locked, any program attempting to access it fails with a record-locked error. A subsequent I/O operation on the logical unit unlocks the previously accessed record, so no more than one record on a logical unit is ever locked.

In the case of a WRITE to a sequential or relative organization file opened for shared access, HP Fortran uses an RMS option that causes the record to be updated if it already exists in the file. This option has the side-effect of momentarily releasing the record lock, if any, and then relocking the target record. There is a small possibility that if another program is trying to access the same record at the same time, it may succeed in locking the record while it is unlocked by the first program, resulting in a record-locked error for the

WRITE statement.

Locked records can be explicitly unlocked by means of HP Fortran’s UNLOCK statement. The use of this statement minimizes the amount of time that a record is locked against access by other programs. The UNLOCK statement should be used in programs that retrieve records from a shared file but do not attempt to update them.

For More Information

• On the UNLOCK statement and its syntax, see the HP Fortran for

OpenVMS Language Reference Manual.

• On record locking for shared files, see the Guide to OpenVMS File

Applications.

• On how to handle record locking for indexed files, see Section 12.8.

• On specifier syntax and complete information, see the HP Fortran for

OpenVMS Language Reference Manual.

• On file sharing and record locking, see the Guide to OpenVMS File

Applications.

6–34 HP Fortran Input/Output

6.9.4 Specifying the Initial Record Position

When you open a disk file, you can use the OPEN statement’s POSITION specifier to request one of the following initial record positions within the file:

• The initial position before the first record (POSITION= ’ REWIND ’ ). A sequential access READ or WRITE statement will read or write the first record in the file.

• A point beyond the last record in the file (POSITION= ’ APPEND ’ ), just before the end-of-file record, if one exists. For a new file, this is the initial position before the first record (same as ’ REWIND ’ ). You might specify

’ APPEND ’ before you write records to an existing sequential file using sequential access.

• The current position (ASIS). This is usually used only to maintain the current record position when reconnecting a file. The second OPEN specifies the same unit number and specifies the same file name (or omits it), which leaves the file open, retaining the current record position.

However, if a second OPEN statement specifies a different file name for the same unit number, the file will be closed and then opened, causing a loss of current record position.

The following I/O statements allow you to change the current record position:

• REWIND sets the record position to the initial position before the first record. A sequential access READ or WRITE statement would read or write the first record in the file.

• BACKSPACE sets the record position to the previous record in a file. Using sequential access, if you wrote record 5, issued a BACKSPACE to that unit, and then read from that unit, you would read record 5.

• ENDFILE writes an end-of-file marker. This is typically done after writing records using sequential access just before you close the file.

Unless you use nonadvancing I/O (see Section 6.9.5), reading and writing records usually advances the current record position by one record. As discussed in Section 6.9.6, more than one record might be transferred using a single record I/O statement.

HP Fortran Input/Output 6–35

6.9.5 Advancing and Nonadvancing Record I/O

After you open a file, if you omit the ADVANCE specifier (or specify

ADVANCE= ’ YES ’ ) in READ and WRITE statements, advancing I/O (normal

FORTRAN-77 I/O) will be used for record access. When using advancing I/O:

• Record I/O statements transfer one entire record (or multiple records).

• Record I/O statements advance the current record position to a position before the next record.

You can request nonadvancing I/O for the file by specifying the ADVANCE=

’ NO ’ specifier in a READ and WRITE statement. You can use nonadvancing

I/O only for sequential access to external files using formatted I/O (not list-directed or namelist).

When you use nonadvancing I/O, the current record position does not change, and part of the record might be transferred, unlike advancing I/O where one entire record or records are always transferred.

You can alternate between advancing and nonadvancing I/O by specifying different values for the ADVANCE specifier ( ’ YES ’ and ’ NO ’ ) in the READ and WRITE record I/O statements.

When reading records with either advancing or nonadvancing I/O, you can use the END branch specifier to branch to a specified label when the end of the file is read.

Because nonadvancing I/O might not read an entire record, it also supports an EOR branch specifier to branch to a specified label when the end of the record is read. If you omit the EOR and the IOSTAT specifiers when using nonadvancing I/O, an error results when the end-of-record is read.

When using nonadvancing input, you can use the SIZE specifier to return the number of characters read. For example, in the following READ statement,

SIZE=X (where variable X is an integer) returns the number of characters read in X and an end-of-record condition causes a branch to label 700:

150 FORMAT (F10.2, F10.2, I6)

READ (UNIT=20, FMT=150, SIZE=X, ADVANCE=’NO’, EOR=700) A, F, I

6–36 HP Fortran Input/Output

6.9.6 Record Transfer

I/O statements transfer all data as records. The amount of data that a record can contain depends on the following circumstances:

• With formatted I/O (except for fixed-length records), the number of items in the I/O statement and its associated format specifier jointly determine the amount of data to be transferred.

• With namelist and list-directed output, the items listed in the NAMELIST statement or I/O statement list (in conjunction with the NAMELIST or list-directed formatting rules) determine the amount of data to be transferred.

• With unformatted I/O (except for fixed-length records), the I/O statement alone specifies the amount of data to be transferred.

• When you specify fixed-length records (RECORDTYPE= ’ FIXED ’ ), all records are the same size. If the size of an I/O record being written is less than the record length (RECL), extra bytes are added (padding).

Typically, the data transferred by an I/O statement is read from or written to a single record. It is possible, however, for a single I/O statement to transfer data from or to more than one record, depending on the form of I/O used.

Input Record Transfer

When using advancing I/O, if an input statement specifies fewer data fields

(less data) than the record contains, the remaining fields are ignored.

If an input statement specifies more data fields than the record contains, one of the following occurs:

• For formatted input using advancing I/O, if the file was opened with

PAD= ’ YES ’ , additional fields are read as spaces. If the file is opened with

PAD= ’ NO ’ , an error occurs (the input statement should not specify more data fields than the record contains).

For formatted input using nonadvancing I/O (ADVANCE= ’ NO ’ specifier), an end-of-record (EOR) condition is returned. If the file was opened with

PAD= ’ YES ’ , additional fields are read as spaces.

• For list-directed input, another record is read.

• For namelist input, another record is read.

• For unformatted input, an error occurs.

HP Fortran Input/Output 6–37

Output Record Transfer

If an output statement specifies fewer data fields than the record contains (less data than required to fill a record), the following occurs:

• With fixed-length records (RECORDTYPE= ’ FIXED ’ ), all records are the same size. If the size of an I/O record being written is less than the record length (RECL), extra bytes are added (padding) in the form of spaces (for a formatted record) or zeros (for an unformatted record).

• With other record types, the fields present are written and those omitted are not written (might result in a short record).

If the output statement specifies more data than the record can contain, an error occurs, as follows:

• With formatted or unformatted output using fixed-length records

If the items in the output statement and its associated format specifier result in a number of bytes that exceed the maximum record length

(RECL), an error occurs.

• With formatted or unformatted output not using fixed-length records

If the items in the output statement and its associated format specifier result in a number of bytes that exceed the maximum record length

(RECL), an error (OUTSTAOVE) occurs.

• For list-directed output and namelist output, if the data specified exceeds the maximum record length (RECL), another record is written.

For More Information:

• On HP Fortran I/O statements, see Table 6–1.

• On record I/O specifiers, see Section 6.9.1.

• On statement syntax and specifier values, see the HP Fortran for

OpenVMS Language Reference Manual.

• On improving HP Fortran I/O performance, see Section 5.5.

• On user-supplied OPEN Procedures (the USEROPEN specifier), see

Section 11.4.

6–38 HP Fortran Input/Output

6.10 Output Data Buffering and RMS Journaling

When an HP Fortran output statement is executed, the record data may not be written immediately to the file or device.

To enhance performance, HP Fortran uses the OpenVMS RMS ‘‘write-behind’’ and ‘‘multibuffering’’ features, which group records together in a memory buffer and delays the actual device write operation until the buffers are full or the file is closed. In most cases, this is desirable (for instance, to minimize disk I/O).

For those applications that depend on data being written to the physical device immediately, ‘‘write-behind’’ and ‘‘multibuffering’’ can result in incomplete data in the case of a power loss or other severe problem that prevents the data being written.

For applications that require guaranteed file consistency for disaster recovery or transactional integrity, the RMS Journaling product is recommended. RMS

Journaling provides three types of journaling:

• After-Image journaling, in which journaled transactions allow you to redo record operations.

• Before-Image journaling, in which journaled transactions allow you to undo record operations.

• Recovery Unit (RU) for transactional integrity (multiple operations treated as one transaction)

Both After-Image and Before-Image journaling can be used without modifying the application.

Other applications that do not need the degree of safety provided by RMS journaling can use RMS features to cause data to be written to the file or device more frequently. The simplest method is to use the SYS$FLUSH system service to cause RMS to perform all pending writes immediately to disk. This also has the effect of updating the file’s end-of-file pointer so that all of the data written up to that point becomes accessible. An application might choose to call SYS$FLUSH at an interval of every hundred records, for example. The more often SYS$FLUSH is called, the more often the file is updated, but the more performance is affected.

When calling SYS$FLUSH, the RMS Record Access Block (RAB) for the file must be passed as an argument. For files opened by HP Fortran (or Compaq

Fortran 77), the FOR$RAB intrinsic function may be used to obtain the RAB.

For example:

HP Fortran Input/Output 6–39

INTEGER (KIND=4) :: FOR$RAB, IUNIT

IREC_COUNT = 0

DO WHILE (....)

WRITE (IUNIT) DATA

IREC_COUNT = IREC_COUNT + 1

IF (IREC_COUNT .EQ. 100) THEN

CALL SYS$FLUSH(%VAL(FOR$RAB(IUNIT)))

IREC_COUNT = 0

END IF

END DO

For More Information:

• On RMS Journaling, see the RMS Journaling for OpenVMS Manual.

• On SYS$FLUSH and other RMS features, see Chapter 11, the Guide

to OpenVMS File Applications, and the OpenVMS Record Management

Services Reference Manual.

• On using the FOR$RAB intrinsic function, see Section 11.2.3.

• On improving HP Fortran I/O performance, see Section 5.5.

6–40 HP Fortran Input/Output

Run-Time Errors

This chapter describes:

• Section 7.1, Run-Time Error Overview

• Section 7.2, HP Fortran RTL Default Error Processing

• Section 7.3, Handling Errors

• Section 7.4, List of Run-Time Messages

7.1 Run-Time Error Overview

During execution, your program may encounter errors or exception conditions.

These conditions can result from errors that occur during I/O operations, from invalid input data, from argument errors in calls to the mathematical library, from arithmetic errors, or from system-detected errors.

The HP Fortran Run-Time Library (RTL) provides default processing for error conditions, generates appropriate messages, and takes action to recover from errors whenever possible. However, you can explicitly supplement or override default actions by using the following methods:

• To transfer control to error-handling code within the program, use the error

(ERR), end-of-record (EOR), and end-of-file (END) branch specifiers in I/O statements.

• To identify Fortran-specific errors based on the value of IOSTAT, use the

I/O status specifier (IOSTAT) in I/O statements.

• To tailor error processing to the special requirements of your applications, use the OpenVMS condition-handling facility (including user-written condition handlers). (For information on user-written condition handlers, see Chapter 14.)

Run-Time Errors 7–1

7.2 HP Fortran RTL Default Error Processing

The HP Fortran RTL contains condition handlers that process a number of errors that may occur during HP Fortran program execution. A default action is defined for each Fortran-specific error recognized by the HP Fortran RTL.

The default actions described throughout this chapter occur unless overridden by explicit error-processing methods.

Unless you specify the /SYNCHRONOUS_EXCEPTIONS (Alpha only) qualifier when you compile the program, error reporting of exceptions may be inexact; the exception may not be reported until a few instructions after the one that caused the exception. This makes continuation from an exception trap not feasible.

The way in which the HP Fortran RTL actually processes errors depends on several factors:

• The severity of the error

• Whether an I/O error-handling specifier or a condition handler was used

The following FORTRAN command qualifiers are related to handling errors and exceptions:

• The /CHECK=BOUNDS, /CHECK=OVERFLOW, and /CHECK=UNDERFLOW qualifiers generate extra code to catch certain conditions. For example, the /CHECK=OVERFLOW qualifier generates extra code to catch integer overflow conditions.

• The /CHECK=ARG_INFO (I64 only) qualifier controls whether run-time checking of the actual argument list occurs.

• The /CHECK=FP_MODE (I64 only) qualifier controls whether run-time checking of the current state of the processor’s floating-point status register

(FPSR) occurs.

• The /CHECK=NOFORMAT, /CHECK=NOOUTPUT_CONVERSION, and

/CHECK=NOPOWER qualifiers reduce the severity level of the associated run-time error to allow program continuation.

• The /CHECK=NOFP_EXCEPTIONS qualifier and the /CHECK=UNDERFLOW qualifier control the handling and reporting of floating-point arithmetic exceptions at run time.

• The /SYNCHRONOUS_EXCEPTIONS (Alpha only) qualifier (and certain

/IEEE_MODE keywords) influence the reporting of floating-point arithmetic exceptions at run time.

7–2 Run-Time Errors

• The /WARNINGS qualifier controls compile-time warning messages, which in some circumstances can help determine the cause of a run-time error.

For More Information:

• On the FORTRAN command qualifier /CHECK, see Section 2.3.11.

• On other /CHECK qualifier keywords, see Section 2.3.11.

• On the FORTRAN qualifiers that control compile-time warning messages, see Section 2.3.51.

• On IEEE floating-point data types and exceptional values, see Section 2.3.24.

• On FORTRAN command qualifiers and their categories, see Table 2–1.

• On HP Fortran intrinsic data types and their ranges, see Chapter 8.

7.2.1 Run-Time Message Format

The general form of HP Fortran run-time messages follows:

%FOR-severity-mnemonic, message-text

The contents of the fields in run-time messages follow:

FOR severity

The percent sign identifies the line as a message.

The facility code for Compaq Fortran 77 and HP Fortran.

A single character that determines message severity. The types of run-time messages are: Fatal (F), Error (E), and Informational (I).

mnemonic A 6- to 9-character name that uniquely identifies that message.

message_text Explains the event or reason why the message appears.

For example, the following message has a severity of Fatal, a mnemonic of

ADJARRDIM, and message text of ‘‘adjustable array dimension error’’:

%FOR-F-ADJARRDIM, adjustable array dimension error

7.2.2 Run-Time Message Severity Levels

In order of greatest to least severity, the classes of run-time diagnostic messages are as follows:

Run-Time Errors 7–3

Severity

Code

Description

Fatal (severe)

This must be corrected. The program cannot complete execution and is terminated when the error is encountered, unless for I/O statements the program uses the END, EOR, or ERR branch specifiers to transfer control, perhaps to a routine that uses the IOSTAT specifier (see Section 7.3.1 and

Section 7.3.2). You can also continue from certain fatal-level messages by using a condition handler.

Error

This should be corrected. The program may continue execution, but the output from this execution may be incorrect.

Informational

This should be investigated. The program continues executing, but output from this execution may be incorrect.

The severity depends on the source of the message. In some cases, certain

FORTRAN command qualifiers can change the severity level or control whether messages are displayed (such as the /CHECK and /IEEE_MODE keywords).

7.3 Handling Errors

Whenever possible, the HP Fortran RTL does certain error handling, such as generating appropriate messages and taking necessary action to recover from errors.

When no recovery method is specified for a statement and a fatal-level error occurs, a message appears and the program terminates. To prevent program termination, you must include either an appropriate I/O error-handling specifier (see Section 7.3) or a condition handler that performs an unwind (see

Chapter 14). The I/O error-handling specifier or condition handler might also handle error-level messages.

You can explicitly supplement or override default actions by using the following

HP Fortran methods:

• To transfer control to error-handling code within the program, use the ERR,

EOR, and END branch specifiers in I/O statements (see Section 7.3.1).

• The ERR, EOR, and END branch specifiers transfer control to a part of your program designed to handle specific errors. The error-handling code associated with the ERR branch usually handles multiple types of errors.

7–4 Run-Time Errors

To identify Fortran-specific I/O errors based on the value of HP Fortran

RTL error codes, use the I/O status specifier (IOSTAT) in I/O statements

(or call the ERRSNS subroutine) (see Section 7.3.2).

When a fatal error occurs during program execution, the HP Fortran RTL default action is to print an error message and terminate the program. You can establish an OpenVMS condition handler that performs an unwind for certain fatal errors.

These error-processing methods are complementary; you can use all of them within the same program. However, before attempting to write a condition handler, you should be familiar with the OpenVMS condition-handling facility

(CHF) and with the condition-handling description in Chapter 14.

Using the END, EOR, or ERR branch specifiers in I/O statements prevent signaling (display) of errors, including secondary return values for file system errors, such as RMS errors. Using these specifiers prevent the transfer of control to a condition handler.

There are certain file system errors where no handler (condition handler or vector exception handler) exists. To obtain the secondary file system errors in these cases, remove the END, EOR, and ERR specifiers, recompile, relink, and rerun the program.

You do not need to remove the ERR or IOSTAT specifiers if you use a vectored exception handler (established using SYS$SETEXV), which will receive control instead of the ERR and IOSTAT specifiers. The ERRSNS subroutine allows you to obtain secondary return values for file system errors (see the HP Fortran for

OpenVMS Language Reference Manual).

7.3.1 Using the ERR, EOR, and END Branch Specifiers

When an error, end-of-record, or end-of-file condition occurs during program execution, the HP Fortran RTL default action is to display a message and terminate execution of the program.

You can use the ERR, EOR, and END specifiers in I/O statements to override this default by transferring control to a specified point in the program. To override this default action, there are three branch specifiers you can use in

I/O statements to transfer control to a specified point in the program:

• The END branch specifier handles an end-of-file condition.

• The EOR branch specifier handles an end-of-record condition for nonadvancing reads.

Run-Time Errors 7–5

• The ERR branch specifier handles all error conditions. Note that end-offile and end-of-record are not considered error conditions by the Fortran language standard.

If an END, EOR, or ERR branch specifier is present, and the corresponding condition occurs, no message is displayed and execution continues at the statement designated in the appropriate specifier.

For example, consider the following READ statement:

READ (8, 50, END=400) X,Y,Z

If an end-of-file condition occurs during execution of this statement, the contents of variables X, Y, and Z become undefined, and control is transferred to the statement at label 400. You can also add an ERR specifier to transfer control if an error condition occurs. Note that an end-of-file or end-of-record condition does not cause an ERR specifier branch to be taken.

When using nonadvancing I/O, use the EOR specifier to handle the end-ofrecord condition. For example:

150 FORMAT (F10.2, F10.2, I6)

READ (UNIT=20, FMT=150, SIZE=X, ADVANCE=’NO’, EOR=700) A, F, I

You can also specify ERR as a keyword to such I/O statements as OPEN,

CLOSE, or INQUIRE statement. For example:

OPEN (UNIT=10, FILE=’FILNAM’, STATUS=’OLD’, ERR=999)

If an error is detected during execution of this OPEN statement, control transfers to statement 999.

For More Information:

• On the IOSTAT specifier, see Section 7.3.2).

• On detailed descriptions of errors processed by the HP Fortran RTL, see

Table C–1 or online FORTRAN HELP.

• On user-written condition handlers, see Chapter 14.

7.3.2 Using the IOSTAT Specifier

You can use the IOSTAT specifier to continue program execution after an I/O error and to return information about I/O operations. It can supplement or replace the END, EOR, and ERR transfers. Execution of an I/O statement containing the IOSTAT specifier suppresses printing of an error message and causes the specified integer variable, array element, or scalar field reference to be defined as one of the following:

• A value of –2 if an end-of-record condition occurs (nonadvancing reads).

7–6 Run-Time Errors

• A value of –1 if an end-of-file condition occurs.

• A value of 0 if neither an error condition nor an end-of-file condition occurs.

• A positive integer value if an error condition occurs (this value is one of the

Fortran-specific IOSTAT numbers listed in Table 7–1).

Following execution of the I/O statement and assignment of an IOSTAT value, control transfers to the END, EOR, or ERR statement label, if any. If there is no control transfer, normal execution continues.

Your program can include the $FORIOSDEF library module from the

FORSYSDEF library (automatically searched during compilation) to obtain symbolic definitions for the values of IOSTAT.

The values of the IOSTAT symbols from the $FORIOSDEF library module are not the same as the values of the Fortran condition symbols from the

$FORDEF library module.

The symbolic names in the $FORIOSDEF library module have a form similar to the Fortran condition symbols:

Fortran Condition Symbol

($FORDEF)

FOR$_mnemonic

IOSTAT Symbolic Name ($FORIOSDEF)

FOR$IOS_mnemonic

Example 7–1 uses the ERR and IOSTAT specifiers to handle an OPEN statement error (in the FILE specifier). Condition symbols are included from the $FORIOSDEF library module (in FORSYSDEF).

Example 7–1 Handling OPEN Statement File Name Errors

CHARACTER(LEN=40) :: FILNM

INCLUDE ’($FORIOSDEF)’

! Typed file specification

! Include condition symbol definitions

DO I=1,4

FILNM = ’’

WRITE (6,*) ’Type file name ’

READ (5,*) FILNM

! Allow four tries

OPEN (UNIT=1, FILE=FILNM, STATUS=’OLD’, IOSTAT=IERR, ERR=100)

WRITE (6,*) ’Opening file: ’, FILNM

! Process records

(continued on next page)

Run-Time Errors 7–7

Example 7–1 (Cont.) Handling OPEN Statement File Name Errors

CLOSE (UNIT=1)

STOP

100 IF (IERR .EQ. FOR$IOS_FILNOTFOU) THEN

WRITE (6,*) ’File: ’, FILNM, ’ does not exist ’

ELSE IF (IERR .EQ. FOR$IOS_FILNAMSPE) THEN

WRITE (6,*) ’File: ’, FILNM, ’ was bad, enter new file name’

ELSE

PRINT *, ’Unrecoverable error, code =’, IERR

STOP

END IF

END DO

! After four attempts or a Ctrl/Z on the READ statement, allow program restart

WRITE (6,*) ’File not found. Type DIRECTORY to find file and run again’

END PROGRAM

For More Information:

• On user-written condition handlers, see Chapter 14.

• On the END, EOR, or ERR branch specifiers, see Section 7.3.1.

• On detailed descriptions of errors processed by the HP Fortran RTL, see

Table C–1 or online FORTRAN HELP.

• On the ERRSNS subroutine, see the HP Fortran for OpenVMS Language

Reference Manual.

• On including library modules from text libraries, see Section 10.8.1.

7.4 List of Run-Time Messages

Table 7–1 lists the Fortran-specific errors processed by the HP Fortran RTL.

For each error, the table shows the Fortran-specific message mnemonic

(follows either FOR$_ or FOR$IOS_ for condition symbols), the Fortran-specific message number, the severity (fatal, error, or informational), the message text.

For more detailed descriptions of errors processed by the HP Fortran RTL, see

Table C–1.

7–8 Run-Time Errors

Table 7–1 Summary of Run-Time Errors

Mnemonic Number

Severity Message Text

NOTFORSPE 2

BUG_CHECK

SYNERRNAM

TOOMANVAL

INVREFVAR

REWERR

DUPFILSPE

INPRECTOO

BACERR

ENDDURREA

RECNUMOUT

OPEDEFREQ

TOOMANREC

CLOERR

FILNOTFOU

OPEFAI

MIXFILACC

INVLOGUNI

ENDFILERR

UNIALROPE

SEGRECFOR

ATTACCNON

INCRECLEN

ERRDURWRI

F not a Fortran-specific error internal consistency check failure syntax error in NAMELIST input too many values for NAMELIST variable invalid reference to variable in NAMELIST input

REWIND error duplicate file specifications input record too long

BACKSPACE error end-of-file during read record number outside range

OPEN or DEFINE FILE required too many records in I/O statement

CLOSE error file not found open failure mixed file access modes invalid logical unit number

ENDFILE error unit already open segmented record format error attempt to access non-existent record inconsistent record length error during write

Although most error numbers are returned as IOSTAT values, the following are not: 1, 24 (END specifier),

41, 58, 70–75, 77, 80-89, 95, 140–150, 151, 153, 173, 175–177, 179, 266, 268 (EOR specifier), 297, 298, 299,

300. You can use condition symbols (FOR$_mnemonic or FOR$IOS_mnemonic) to obtain the number (see

Section 7.3.2). Some of these error numbers are returned as STAT= values in either the ALLOCATE (41, 151,

179) or DEALLOCATE (41, 153, 173) Fortran statement.

The FOR$_NOTFORSPE error (number 1) indicates an error not reportable through any other message. If you call ERRSNS, an error of this kind returns a value of 1. Use the fifth argument of the call to ERRSNS

(condval) to obtain the unique system condition value that identifies the error.

(continued on next page)

Run-Time Errors 7–9

Table 7–1 (Cont.) Summary of Run-Time Errors

Mnemonic Number

Severity Message Text

ERRDURREA

RECIO_OPE

INSVIRMEM

NO_SUCDEV

FILNAMSPE

INCRECTYP

KEYVALERR

INCOPECLO

WRIREAFIL

INVARGFOR

INVKEYSPE

INCKEYCHG

INCFILORG

SPERECLOC

NO_CURREC

REWRITERR

DELERR

UNLERR

FINERR

FMYSYN

LISIO_SYN

INFFORLOO

FORVARMIS

F or I

F error during read recursive I/O operation insufficient virtual memory no such device file name specification error inconsistent record type keyword value error in OPEN statement inconsistent OPEN/CLOSE parameters write to READONLY file invalid argument to Fortran Run-Time Library invalid key specification inconsistent key change or duplicate key inconsistent file organization specified record locked no current record

REWRITE error

DELETE error

UNLOCK error

FIND error format syntax error at or near xxx list-directed I/O syntax error infinite format loop format/variable-type mismatch

Although most error numbers are returned as IOSTAT values, the following are not: 1, 24 (END specifier),

41, 58, 70–75, 77, 80-89, 95, 140–150, 151, 153, 173, 175–177, 179, 266, 268 (EOR specifier), 297, 298, 299,

300. You can use condition symbols (FOR$_mnemonic or FOR$IOS_mnemonic) to obtain the number (see

Section 7.3.2). Some of these error numbers are returned as STAT= values in either the ALLOCATE (41, 151,

179) or DEALLOCATE (41, 153, 173) Fortran statement.

For error numbers 59, 61, 63, 64, and 68, the ERR transfer is taken after completion of the I/O statement.

The resulting file status and record position are the same as if no error had occurred. Other I/O errors take the ERR transfer as soon as the error is detected, and file status and record position are undefined.

For errors 61 and 63, the severity depends on the /CHECK keywords in effect during compilation (see

Section 2.3.11). If no ERR address is defined for error number 63, the program continues and the entire overflowed field is filled with asterisks to indicate the error in the output record.

(continued on next page)

7–10 Run-Time Errors

Table 7–1 (Cont.) Summary of Run-Time Errors

Mnemonic Number

Severity Message Text

SYNERRFOR

OUTCONERR

3 ; 4

INPCONERR 3

FLTINV

OUTSTAOVE

INPSTAREQ

VFEVALERR 3

INTOVF

INTDIV

FLTOVF

FLTDIV

FLTUND

SUBRNG

WRONUMARG

INVARGMAT

UNDEXP

LOGZERNEG 5

SQUROONEG

SIGLOSMAT 5

FLOOVEMAT 5

FLOUNDMAT

E or I

F syntax error in format output conversion error input conversion error floating invalid output statement overflows record input statement requires too much data variable format expression value error integer overflow integer divide by zero floating overflow floating divide by zero floating underflow subscript out of range wrong number of arguments invalid argument to math library undefined exponentiation logarithm of zero or negative value square root of negative value significance lost in math library floating overflow in math library floating underflow in math library

Although most error numbers are returned as IOSTAT values, the following are not: 1, 24 (END specifier),

41, 58, 70–75, 77, 80-89, 95, 140–150, 151, 153, 173, 175–177, 179, 266, 268 (EOR specifier), 297, 298, 299,

300. You can use condition symbols (FOR$_mnemonic or FOR$IOS_mnemonic) to obtain the number (see

Section 7.3.2). Some of these error numbers are returned as STAT= values in either the ALLOCATE (41, 151,

179) or DEALLOCATE (41, 153, 173) Fortran statement.

For error numbers 59, 61, 63, 64, and 68, the ERR transfer is taken after completion of the I/O statement.

For errors 61 and 63, the severity depends on the /CHECK keywords in effect during compilation (see

Section 2.3.11). If no ERR address is defined for error number 63, the program continues and the entire overflowed field is filled with asterisks to indicate the error in the output record.

Function return values for error numbers 82, 83, 84, 87, 88, and 89 can be modified by means of user-written condition handlers. (See Chapter 14 for information about user-written condition handlers.)

(continued on next page)

Run-Time Errors 7–11

Table 7–1 (Cont.) Summary of Run-Time Errors

Mnemonic

ADJARRDIM 6

Number

Severity

Message Text adjustable array dimension error

INVMATKEY

FLOCONFAI

FLTINE

ROPRAND

ASSERTERR

NULPTRERR

STKOVF

STRLENERR

SUBSTRERR

RANGEERR

INVREALLOC

RESACQFAI

145

146

147

148

149

140

144

150

151

152

INVDEALLOC 153

INVDEALLOC2 173

SHORTDATEARG 175

SHORTTIMEARG 176

SHORTZONEARG 177

DIV

ARRSIZEOVF

UNFIO_FMT

178

179

256

F invalid key match specifier for key direction floating point conversion failed floating inexact reserved operand assertion error null pointer error stack overflow string length error substring error range error allocatable array is already allocated unresolved contention for HP Fortran RTL global resource allocatable array is not allocated

A pointer passed to DEALLOCATE points to an array that cannot be deallocated

DATE argument to DATE_AND_TIME is too short

(LEN=n), required LEN=8

TIME argument to DATE_AND_TIME is too short

(LEN=n), required LEN=10

ZONE argument to DATE_AND_TIME is too short

(LEN=n), required LEN=5 divide by zero cannot allocate array — overflow on array size calculation unformatted I/O to unit open for formatted transfers

Although most error numbers are returned as IOSTAT values, the following are not: 1, 24 (END specifier),

41, 58, 70–75, 77, 80-89, 95, 140–150, 151, 153, 173, 175–177, 179, 266, 268 (EOR specifier), 297, 298, 299,

300. You can use condition symbols (FOR$_mnemonic or FOR$IOS_mnemonic) to obtain the number (see

Section 7.3.2). Some of these error numbers are returned as STAT= values in either the ALLOCATE (41, 151,

179) or DEALLOCATE (41, 153, 173) Fortran statement.

If error number 93 (FOR$_ADJARRDIM) occurs and a user-written condition handler causes execution to continue, any reference to the array in question may cause an access violation.

(continued on next page)

7–12 Run-Time Errors

Table 7–1 (Cont.) Summary of Run-Time Errors

Mnemonic Number

Severity Message Text

FMTIO_UNF

DIRIO_KEY

SEQIO_DIR

KEYIO_DIR

OPERREQDIS

OPEREQSEQ

ENDRECDUR

FLOINEEXC

FLOINCEXC

FLOOVREXC

FLODIV0EXC

FLOUNDEXC

268

296

297

298

299

300

257

258

259

260

264

265

F formatted I/O to unit open for unformatted transfers direct-access I/O to unit open for keyed access sequential-access I/O to unit open for direct access keyed-access I/O to unit open for direct access operation requires file to be on disk or tape operation requires sequential file organization and access end of record during read

nn floating inexact traps

nn floating invalid traps

nn floating overflow traps

nn divide-by-zero traps

nn floating underflow traps

Although most error numbers are returned as IOSTAT values, the following are not: 1, 24 (END specifier),

41, 58, 70–75, 77, 80-89, 95, 140–150, 151, 153, 173, 175–177, 179, 266, 268 (EOR specifier), 297, 298, 299,

300. You can use condition symbols (FOR$_mnemonic or FOR$IOS_mnemonic) to obtain the number (see

Section 7.3.2). Some of these error numbers are returned as STAT= values in either the ALLOCATE (41, 151,

179) or DEALLOCATE (41, 153, 173) Fortran statement.

The message mnemonic shown in the first column is part of the condition status code symbols signaled by the HP Fortran RTL I/O support routines.

You can define these symbolic values in your program by including the library module $FORDEF or $FORIOSDEF from the system-supplied default library

FORSYSDEF.TLB:

• The symbolic values defined in library module $FORDEF have the form

FOR$_mnemonic.

• The condition symbols defined in $FORIOSDEF have the form FOR$IOS_

mnemonic.

If you will be using the IOSTAT specifier for error handling, you should include the $FORIOSDEF library module (instead of $FORDEF) from the

FORSYSDEF.TLB library (see Section 7.3.2).

The standard HP Fortran error numbers that are generally compatible with other versions of HP Fortran are shown in the second column. Most of these error values are returned to IOSTAT variables when an I/O error is detected.

Run-Time Errors 7–13

The codes in the third column indicate the severity of the error conditions (see

Section 7.2.2).

For more detailed descriptions of errors processed by the HP Fortran RTL, see

Table C–1 or type the following DCL command to obtain a list of mnemonics

(such as ADJARRDIM):

$ HELP FORTRAN ERROR RUN_TIME

For More Information:

• On user-written condition handlers, see Chapter 14.

• On the END, EOR, or ERR branch specifiers, see Section 7.3.1.

• On the IOSTAT specifier, see Section 7.3.2.

• On detailed descriptions of errors processed by the HP Fortran RTL, see

Table C–1 or online FORTRAN HELP.

• On the ERRSNS subroutine, see the HP Fortran for OpenVMS Language

Reference Manual.

• On the Alpha architecture, see the Alpha Architecture Reference Manual.

• On locating exceptions within the debugger, see Section 4.6.

7–14 Run-Time Errors

Data Types and Representation

This chapter describes:

• Section 8.1, Summary of Data Types and Characteristics

• Section 8.2, Integer Data Representations

• Section 8.3, Logical Data Representations

• Section 8.4, Native Floating-Point Representations and IEEE Exceptional

Values

• Section 8.5, Character Representation

• Section 8.6, Hollerith Representation

Note

In figures in this chapter, the symbol :A specifies the address of the byte containing bit 0, which is the starting address of the represented data element.

HP Fortran expects numeric data to be in native little endian order, in which the least-significant, rightmost bit (bit 0) or byte has a lower address than the most-significant, leftmost bit (or byte).

For More Information:

• On using nonnative big endian and VAX floating-point formats, see

Chapter 9.

• On HP Fortran I/O, see Chapter 6.

Data Types and Representation 8–1

8.1 Summary of Data Types and Characteristics

Table 8–1 lists the intrinsic data types provided by HP Fortran, the storage required, and valid numeric ranges.

Table 8–1 HP Fortran Intrinsic Data Types, Storage, and Numeric Ranges

Data Type Bytes Description

1 (8 bits) BYTE

(INTEGER*1)

INTEGER

INTEGER (KIND=1)

INTEGER*1

INTEGER (KIND=2)

INTEGER*2

INTEGER (KIND=4)

INTEGER*4

INTEGER (KIND=8)

INTEGER*8

LOGICAL

1, 2, 4, or 8

1 (8 bits)

2 (16 bits)

4 (32 bits)

8 (64 bits)

1, 2, 4, or 8

1 (8 bits)

A BYTE declaration is a signed integer data type equivalent to INTEGER*1 or INTEGER (KIND=1).

Signed integer whose size is controlled by a kind type parameter or, if a kind type parameter (or size specifier) is omitted, certain FORTRAN command qualifiers (see

Section 8.2.1).

Signed integer value from –128 to 127 (–2**7 to 2**7–1).

Unsigned values from 0 to 255 (2**8-1)

Signed integer value from –32,768 to 32,767 (–2**15 to

2**15–1). Unsigned values from 0 to 65535 (2**16-1) 1 .

Signed integer value from –2,147,483,648 to

2,147,483,647 (–2**31 to 2**31–1). Unsigned values from

0 to 4,294,967,295 (2**32-1) 1 .

Signed integer value from –9,223,372,036,854,775,808 to

9,223,372,036,854,775,807 (–2**63 to 2**63–1).

Logical value whose size is controlled by a kind type parameter or, if a kind type parameter (or size specifier) is omitted, certain FORTRAN command qualifiers (see

Section 8.3).

Logical values .TRUE. or .FALSE.

LOGICAL (KIND=1)

LOGICAL*1

LOGICAL (KIND=2)

LOGICAL*2

LOGICAL (KIND=4)

LOGICAL*4

LOGICAL (KIND=8)

LOGICAL*8

2 (16 bits)

4 (32 bits)

8 (64 bits)

Logical values .TRUE. or .FALSE.

This range is allowed for assignment to variables of this type, but the data type is treated as signed in arithmetic operations.

Logical data type ranges correspond to their comparable integer data type ranges. For example, in LOGICAL

(KIND=2) L, the range for L is the same as the range for INTEGER (KIND=2) integers.

(continued on next page)

8–2 Data Types and Representation

Table 8–1 (Cont.) HP Fortran Intrinsic Data Types, Storage, and Numeric Ranges

Data Type Bytes Description

REAL

REAL (KIND=4)

REAL*4

4 or 8

4 (32 bits)

Real floating-point numbers whose size is controlled by a kind type parameter or, if a kind type parameter (or size specifier) is omitted, by using the FORTRAN command

/REAL_SIZE qualifier. To control the floating-point format used in memory, use the FORTRAN command

/FLOAT qualifier.

Single-precision real floating-point values in IEEE S_float or VAX F_float formats.

IEEE S_float normalized values range from 1.17549435E–

38 to 3.40282347E38. Values between 1.17549429E–38 and 1.40129846E–45 are denormalized 3 .

VAX F_float values range from 0.293873588E–38 to

1.7014117E38.

DOUBLE PRECISION

REAL (KIND=8)

REAL*8

REAL (KIND=16)

REAL*16

8 (64 bits) Double-precision real floating-point values in IEEE T_ float, VAX G_float, or VAX D_float formats.

IEEE T_float normalized values range from

2.2250738585072013D–308 to 1.7976931348623158D308.

Values between 2.2250738585072008D–308 and

4.94065645841246544D–324 are denormalized 3 .

VAX G_float values range from 0.5562684646268004D–

308 to 0.89884656743115785407D308.

VAX D_float values range from 0.2938735877055719D–38 to 1.70141183460469229D38.

You can change the data size of DOUBLE PRECISION declarations from REAL (KIND=8) to REAL (KIND=16) with the FORTRAN command /DOUBLE_SIZE qualifier.

16 (128 bits) Extended-precision real floating-point values in IEEElike X_float format ranging from

6.4751751194380251109244389582276465524996Q-4966 to

1.189731495357231765085759326628007016196477Q4932.

The smallest normalized number is

3.362103143112093506262677817321753Q-4932.

You cannot write a constant for a denormalized number. For more information on floating-point underflow, see Section 2.3.24.

(continued on next page)

Data Types and Representation 8–3

Table 8–1 (Cont.) HP Fortran Intrinsic Data Types, Storage, and Numeric Ranges

Data Type

COMPLEX

(KIND=4)

COMPLEX*8

DOUBLE COMPLEX

COMPLEX

(KIND=8)

COMPLEX*16

COMPLEX

(KIND=16)

COMPLEX*32

Bytes Description

8, 16, or 32

8 (64 bits)

Complex floating-point numbers whose size is controlled by a kind type parameter or, if a kind type parameter

(or size specifier) is omitted, the FORTRAN command

/REAL_SIZE qualifier. To control the floating-point format used in memory, use the FORTRAN command

/FLOAT qualifier.

Single-precision complex floating-point values in a pair of floating-point parts: real and imaginary. Use the IEEE

S_float or VAX F_float format.

IEEE S_float real and imaginary parts range from

1.17549435E–38 to 3.40282347E38. Values between

1.17549429E–38 and 1.40129846E–45 are denormalized 3 .

VAX F_float real and imaginary parts range from

0.293873588E–38 to 1.7014117E38.

16 (128 bits) Double-precision complex floating-point values in a pair of parts: real and imaginary. Use the IEEE T_float, VAX

G_float, or VAX D_float format.

IEEE T_float format real and imaginary parts each range from 2.2250738585072013D-308 to

1.7976931348623158D308. Values between

2.2250738585072008D–308 and

4.94065645841246544D–324 are denormalized 3 .

VAX G_float format real and imaginary parts each range from 0.5562684646268004D–308 to

0.89884656743115785407D308.

VAX D_float format real and imaginary parts each range from 0.2938735877055719D–38 to

1.70141183460469229D38.

32 (256 bits) Extended-precision complex floating-point values in a pair of IEEE X_float format parts: real and imaginary.

The real and imaginary parts each range from

6.4751751194380251109244389582276465524996Q-4966 to

1.189731495357231765085759326628007016196477Q4932.

You cannot write a constant for a denormalized number. For more information on floating-point underflow, see Section 2.3.24.

(continued on next page)

8–4 Data Types and Representation

Table 8–1 (Cont.) HP Fortran Intrinsic Data Types, Storage, and Numeric Ranges

Data Type

CHARACTER

HOLLERITH

Bytes

1 byte (8 bits) per character

Description

Character data represented by character code convention. Character declarations can be in the form CHARACTER(LEN=n), CHARACTER(n), or

CHARACTER*n, where n is the number of bytes or n can be (*) to indicate passed-length format.

Hollerith constants.

1 byte (8 bits) per

Hollerith character

In addition to the intrinsic numeric data types, you can define nondecimal

(binary, octal, or hexadecimal) constants as explained in the HP Fortran for

OpenVMS Language Reference Manual.

8.2 Integer Data Representations

Integer data lengths can be one, two, four, or eight bytes in length.

Integer data is signed with the sign bit being 0 (zero) for positive numbers and

1 for negative numbers.

To improve performance, avoid using 2-byte or 1-byte integer declarations (see

Chapter 5).

8.2.1 Integer Declarations and FORTRAN Command Qualifiers

The default size used for an INTEGER data declaration without a kind parameter (or size specifier) is INTEGER (KIND=4) (same as INTEGER*4), unless you do one of the following:

• Explicitly declare the length of an INTEGER by using a kind parameter, such as INTEGER (KIND=8). HP Fortran provides intrinsic INTEGER kinds of 1, 2, 4, and 8. Each INTEGER kind number corresponds to the number of bytes used by that intrinsic representation.

To obtain the kind of a variable, use the KIND intrinsic function. You can also use a size specifier, such as INTEGER*4, but be aware this is an extension to the Fortran 90 standard.

• Use the FORTRAN command /INTEGER_SIZE=nn qualifier to control the size of all default (without a kind parameter or size specifier) INTEGER and LOGICAL declarations (see Section 2.3.26).

Data Types and Representation 8–5

**8.2.2 INTEGER (KIND=1) or INTEGER*1 Representation**

Intrinsic INTEGER (KIND=1) or INTEGER*1 signed values range from –128 to 127 and are stored in a two’s complement representation. For example:

+22 = 16(hex)

-7 = F9(hex)

INTEGER (KIND=1) or INTEGER*1 values are stored in one byte, as shown in Figure 8–1.

Figure 8–1 INTEGER (KIND=1) or INTEGER*1 Representation

BINARY NUMBER

ZK−9814−GE

**8.2.3 INTEGER (KIND=2) or INTEGER*2 Representation**

Intrinsic INTEGER (KIND=2) or INTEGER*2 signed values range from

–32,768 to 32,767 and are stored in a two’s complement representation. For example:

+22 = 0016(hex)

-7 = FFF9(hex)

INTEGER (KIND=2) or INTEGER*2 values are stored in two contiguous bytes, as shown in Figure 8–2.

Figure 8–2 INTEGER (KIND=2) or INTEGER*2 Representation

BINARY NUMBER

ZK−0798−GE

**8.2.4 INTEGER (KIND=4) or INTEGER*4 Representation**

Intrinsic INTEGER (KIND=4) or INTEGER*4 signed values range from

–2,147,483,648 to 2,147,483,647 and are stored in a two’s complement representation. INTEGER (KIND=4) or INTEGER*4 values are stored in four contiguous bytes, as shown in Figure 8–3.

8–6 Data Types and Representation

Figure 8–3 INTEGER (KIND=4) or INTEGER*4 Representation

31 30

BINARY NUMBER

ZK−0799−GE

**8.2.5 INTEGER (KIND=8) or INTEGER*8 Representation**

Intrinsic INTEGER (KIND=8) or INTEGER*8 signed values range from

–9,223,372,036,854,775,808 to 9,223,372,036,854,775,807 and are stored in a two’s complement representation. INTEGER*8 or INTEGER (KIND=8) values are stored in eight contiguous bytes, as shown in Figure 8–4.

Figure 8–4 INTEGER (KIND=8) or INTEGER*8 Representation

63 62

ZK−5299A−GE

For More Information:

• On defining constants and assigning values to variables, see the HP

Fortran for OpenVMS Language Reference Manual.

• On intrinsic functions related to the various data types, such as KIND and SELECTED_INT_KIND, see the HP Fortran for OpenVMS Language

Reference Manual.

• On the FORTRAN command qualifiers that control the size of default

INTEGER declarations, see Section 2.3.26.

8.3 Logical Data Representations

Logical data can be one, two, four, or eight bytes in length.

The default size used for a LOGICAL data declaration without a kind parameter (or size specifier) is LOGICAL (KIND=4) (same as LOGICAL*4), unless you do one of the following:

• Explicitly declare the length of a LOGICAL declaration by using a kind parameter, such as LOGICAL (KIND=4). HP Fortran provides intrinsic

Data Types and Representation 8–7

LOGICAL kinds of 1, 2, 4, and 8. Each LOGICAL kind number corresponds to number of bytes used by that intrinsic representation.

You can also use a size specifier, such as LOGICAL*4, but be aware this is an extension to the Fortran 90 standard.

• Use the FORTRAN command /INTEGER_SIZE=nn qualifier to control the size of default (without a kind parameter or size specifier) LOGICAL and

INTEGER declarations (see Section 2.3.26).

To improve performance, avoid using 2-byte or 1-byte logical declarations (see

Chapter 5).

Intrinsic LOGICAL*1 or LOGICAL (KIND=1) values are stored in a single byte.

Logical (intrinsic) values can also be stored in the following sizes of contiguous bytes starting on an arbitrary byte boundary:

• Two bytes (LOGICAL (KIND=2) or LOGICAL*2)

• Four bytes (LOGICAL (KIND=4) or LOGICAL*4)

• Eight bytes (LOGICAL (KIND=8) or LOGICAL*8)

The low-order bit determines whether the logical value is true or false. Logical variables can also be interpreted as integer data (an extension to the Fortran

90 standard). For example, in addition to having logical values .TRUE. and

.FALSE., LOGICAL*1 data can also have values in the range –128 to 127.

LOGICAL*1, LOGICAL*2, LOGICAL*4, and LOGICAL*8 data representations appear in Figure 8–5.

8–8 Data Types and Representation

Figure 8–5 LOGICAL Representations n

TRUE: UNDEFINED BITS

1 0

1 :A

FALSE: n

UNDEFINED BITS

1 0

0 :A

Key: n = 7, 15, 31, or 63 depending on LOGICAL declaration size

ZK−5300A−GE

For More Information:

• On defining constants and assigning values to variables, see the HP

Fortran for OpenVMS Language Reference Manual.

• On intrinsic functions related to the various data types, see the HP Fortran

for OpenVMS Language Reference Manual.

• On the FORTRAN command qualifiers that control the size of default

LOGICAL declarations, see Section 2.3.26.

8.4 Native Floating-Point Representations and IEEE

Exceptional Values

Floating-point numbers are stored on OpenVMS systems in one of the following

IEEE or VAX little endian binary floating-point formats, as follows:

• REAL (KIND=4) or REAL*4 declarations are stored in little endian IEEE

S_float format or VAX F_float format.

• REAL (KIND=8) or REAL*8 declarations are stored in little endian IEEE

T_float format, VAX G_float format, or VAX D_float format.

• REAL (KIND=16) or REAL*16 declarations always are stored in little endian Alpha IEEE-like X_float format.

COMPLEX numbers use a pair of little endian REAL values to denote the real and imaginary parts of the data, as follows:

• COMPLEX (KIND=4) or COMPLEX*8 declarations are stored in IEEE

S_float or VAX F_float format using two REAL (KIND=4) or REAL*4 values.

Data Types and Representation 8–9

• COMPLEX (KIND=8) or COMPLEX*16 declarations are stored in IEEE

T_float, VAX G_float, or VAX D_float format using two REAL (KIND=8) or

REAL*8 values.

• COMPLEX (KIND=16) or COMPLEX*32 declarations are stored in IEEE

X_float format using two REAL (KIND=16) or REAL*16 values.

To specify the floating-point format used in memory, use the FORTRAN command /FLOAT qualifier. If you do not specify the /FLOAT qualifier, the following formats are used:

• VAX F_float for REAL (KIND=4) and COMPLEX (KIND=4) data

• VAX G_float for REAL (KIND=8) and COMPLEX (KIND=8) data

• X_float for REAL (KIND=16)

To change the default size for REAL and COMPLEX declarations, use the

FORTRAN command /REAL_SIZE qualifier.

To change the default size for DOUBLE PRECISION declarations, use the

FORTRAN command /DOUBLE_SIZE qualifier.

All floating-point formats represent fractions using sign-magnitude notation, with the binary radix point to the left of the most significant bit for F_floating,

D_floating, and G_floating, and to the right for S_floating and T_floating.

Fractions are assumed to be normalized, and therefore the most significant bit is not stored. This is called ‘‘hidden bit normalization’’.

With IEEE data, the hidden bit is assumed to be 1 unless the exponent is 0. If the exponent equals 0, then the value represented is denormalized (subnormal) or plus or minus 0 (zero).

With VAX data, the hidden bit is assumed to be 1.

For an explanation of the representation of NaN, Infinity, and related IEEE exceptional values, see Section 8.4.8.

8.4.1 REAL, COMPLEX, and DOUBLE PRECISION Declarations and

FORTRAN Qualifiers

The default size for REAL, COMPLEX, and DOUBLE PRECISION data declarations are as follows:

• For REAL data declarations without a kind parameter (or size specifier), the default size is REAL (KIND=4) (same as REAL*4). To change the default REAL (and COMPLEX) size to (KIND=8), use the FORTRAN command /REAL_SIZE qualifier (see Section 2.3.37).

8–10 Data Types and Representation

• For COMPLEX data declarations without a kind parameter (or size specifier), the default data size is COMPLEX (KIND=4) (same as

COMPLEX*8). To change the default COMPLEX (and REAL) size to

(KIND=8), use the FORTRAN command /REAL_SIZE qualifier (see

Section 2.3.37).

• For a DOUBLE PRECISION data declarations, the default size is REAL

(KIND=8) (same as REAL*8). To change the default DOUBLE PRECISION size to REAL (KIND=16), use the FORTRAN command /DOUBLE_SIZE qualifier (see Section 2.3.17).

You can explicitly declare the length of a REAL or a COMPLEX declaration using a kind parameter or specify DOUBLE PRECISION or DOUBLE

COMPLEX.

Intrinsic REAL kinds are 4 (single precision) and 8 (double precision); intrinsic

COMPLEX kinds are also 4 (single precision) and 8 (double precision). For example, REAL (KIND=4) requests single-precision floating-point data.

You can also use a size specifier, such as REAL*4, but be aware this is an extension to the Fortran 90 standard.

**8.4.2 REAL (KIND=4) or REAL*4 Representations**

REAL (KIND=4) or REAL*4 data can be in IEEE S_float or VAX F_float formats. This is the default data size for REAL declarations.

8.4.2.1 IEEE S_float Representation

Intrinsic REAL (KIND=4) or REAL*4 (single precision REAL) data occupies four contiguous bytes stored in IEEE S_float format. Bits are labeled from the right, 0 through 31, as shown in Figure 8–6.

Figure 8–6 IEEE S_float REAL (KIND=4) or REAL*4 Representation

31 30

EXPONENT

23 22

FRACTION

ZK−9815−GE

The form of REAL (KIND=4) or REAL*4 data is sign magnitude, with:

• Bit 31 the sign bit (0 for positive numbers, 1 for negative numbers)

• Bits 30:23 a binary exponent in excess 127 notation

Data Types and Representation 8–11

• Bits 22:0 a normalized 24-bit fraction including the redundant mostsignificant fraction bit not represented.

The value of data is in the approximate range: 1.17549435E–38 (normalized) to 3.40282347E38. The IEEE denormalized limit is 1.40129846E–45.

The precision is approximately one part in 2**23, typically seven decimal digits.

8.4.2.2 VAX F_float Representation

Intrinsic REAL (KIND=4) or REAL*4 F_float data occupies four contiguous bytes. Bits are labeled from the right, 0 through 31, as shown in Figure 8–7.

Figure 8–7 VAX F_float REAL (KIND=4) or REAL*4 Representation

FRACTION

15 14

EXPONENT

FRACTION

ZK−5301A−GE

The form of REAL (KIND=4) or REAL*4 F_float data is sign magnitude, where:

• Bit 15 is the sign bit (0 for positive numbers, 1 for negative numbers).

• Bits 14:7 are a binary exponent in excess 128 notation (binary exponents from –127 to 127 are represented by binary 1 to 255).

• Bits 6:0 and 31:16 are a normalized 24-bit fraction with the redundant most significant fraction bit not represented.

The value of data is in the approximate range: 0.293873588E–38 to

1.7014117E38.

The precision is approximately one part in 2**23, typically seven decimal digits.

**8.4.3 REAL (KIND=8) or REAL*8 Representations**

REAL (KIND=8) or REAL*8 data can be in IEEE T_float, VAX G_float, or VAX

D_float formats.

8–12 Data Types and Representation

8.4.3.1 IEEE T_float Representation

Intrinsic REAL (KIND=8) or REAL*8 (same as DOUBLE PRECISION) data occupies eight contiguous bytes stored in IEEE T_float format. Bits are labeled from the right, 0 through 63, as shown in Figure 8–8.

Figure 8–8 IEEE T_float REAL (KIND=8) or REAL*8 Representation

63 62

EXPONENT

52 51

FRACTION

ZK−9816−GE

The form of REAL (KIND=8) or REAL*8 data is sign magnitude, with:

• Bit 63 the sign bit (0 for positive numbers, 1 for negative numbers)

• Bits 62:52 a binary exponent in excess 1023 notation

• Bits 51:0 a normalized 53-bit fraction including the redundant mostsignificant fraction bit not represented.

The value of data is in the approximate range: 2.2250738585072013D-308

(normalized) to 1.7976931348623158D308. The IEEE denormalized limit is

4.94065645841246544D-324.

The precision is approximately one part in 2**52, typically 15 decimal digits.

8.4.3.2 VAX G_float Representation

Intrinsic REAL (KIND=8) or REAL*8 (same as DOUBLE PRECISION) G_float data occupies eight contiguous bytes. The bits are labeled from the right, 0 through 63, as shown in Figure 8–9.

Figure 8–9 VAX G_float REAL (KIND=8) or REAL*8 Representation

FRACTION

EXPONENT

FRAC−

TION

ZK−5302A−GE

The form of REAL (KIND=8) or REAL*8 G_float data is sign magnitude, where:

• Bit 15 is the sign bit (0 for positive numbers, 1 for negative numbers).

Data Types and Representation 8–13

• Bits 14:4 are a binary exponent in excess 1024 notation (binary exponents from –1023 to 1023 are represented by the binary 1 to 2047).

• Bits 3:0 and 63:16 are a normalized 53-bit fraction with the redundant most significant fraction bit not represented.

The value of data is in the approximate range: 0.5562684646268004D–308 to

0.89884656743115785407D308.

The precision of G_float data is approximately one part in 2**52, typically 15 decimal digits.

8.4.3.3 VAX D_float Representation

Intrinsic REAL (KIND=8) or REAL*8 (same as DOUBLE PRECISION) D_float data occupies eight contiguous bytes. Bits are labeled from the right,

0 through 63, as shown in Figure 8–10.

Figure 8–10 VAX D_float REAL (KIND=8) or REAL*8 Representation

FRACTION

15 14

EXPONENT

FRACTION

ZK−5303A−GE

The form of REAL (KIND=8) or REAL*8 D_float data is identical to an F_float real number, except for an additional 32 low-significance fraction bits. The exponent conventions and approximate range of values are the similar to those for F_float.

The value of data is in the approximate range: 0.2938735877055719D–38 to

1.70141183460469229D38.

The precision is approximately one part in 2**55, typically 16 decimal digits.

Calculations with D_float data on Alpha systems use G_float precision (53-bit instead of 56-bit fraction).

For information about how D_float and G_float calculations are done on I64 systems, see Appendix A.

8–14 Data Types and Representation

**8.4.4 REAL (KIND=16) or REAL*16 X_float Representation**

REAL*16 data occupies 16 contiguous bytes stored in X_float format. Bits are labeled from the right, 0 through 127, as shown in Figure 8–11.

Figure 8–11 X_float REAL (KIND=16) Floating-Point Data Representation

127 126

EXPONENT

112 111

FRACTION

ZK−7420A−GE

The form of REAL (KIND=16) data is sign magnitude, with:

• Bit 127 the sign bit (0 for positive numbers, 1 for negative numbers)

• Bits 126:112 a binary exponent in excess 16383 notation

• Bits 111:0 a normalized 113-bit fraction including the redundant mostsignificant fraction bit not represented.

The value of data is in the approximate range:

6.4751751194380251109244389582276465524996Q-4966 to

1.189731495357231765085759326628007016196477Q4932. The smallest normalized number is 3.362103143112093506262677817321753Q-4932.

In contrast to other floating-point formats, there is little if any performance penalty from using denormalized extended-precision numbers. This is because accessing denormalized REAL (KIND=16) numbers does not result in an arithmetic trap (the extended-precision format is emulated in software).

The precision is approximately one part in 2**112 or typically 33 decimal digits.

**8.4.5 COMPLEX (KIND=4) or COMPLEX*8 Representations**

COMPLEX (KIND=4) or COMPLEX*4 data can be in IEEE S_float or VAX

F_float formats. This is the default data size for COMPLEX declarations.

Intrinsic COMPLEX (KIND=4) or COMPLEX*8 (single-precision COMPLEX) data is eight contiguous bytes containing a pair of REAL (KIND=4) or REAL*4 values stored in IEEE S_float format or VAX F_float format.

The low-order four bytes contain REAL (KIND=4) data that represents the real part of the complex number. The high-order four bytes contain REAL

(KIND=4) data that represents the imaginary part of the complex number,

Data Types and Representation 8–15

The limits (and underflow characteristics for S_float numbers) for REAL

(KIND=4) or REAL*4 apply to the two separate real and imaginary parts of a COMPLEX (KIND=4) or COMPLEX*8 number. Like REAL (KIND=4) numbers, the sign bit representation is 0 (zero) for positive numbers and 1 for negative numbers.

Figure 8–12 shows the IEEE S_float representation of COMPLEX

(KIND=4) or COMPLEX*8 numbers.

Figure 8–12 IEEE S_float COMPLEX (KIND=4) or COMPLEX*8 Representation

REAL

PART

IMAGINARY

PART

31 30

EXPONENT

23 22

FRACTION

EXPONENT FRACTION

Figure 8–13 shows the VAX F_float representation of COMPLEX

(KIND=4) or COMPLEX*8 numbers.

Figure 8–13 VAX F_float COMPLEX (KIND=4) or COMPLEX*8 Representation

:A+4

ZK−9817−GE

REAL

PART

IMAGINARY

PART

FRACTION

15 14

EXPONENT

FRACTION

:A+4

ZK−5304A−GE

**8.4.6 COMPLEX (KIND=8) or COMPLEX*16 Representations**

COMPLEX (KIND=8) or COMPLEX*16 data can be in IEEE T_float, VAX

G_float, or VAX D_float formats.

Intrinsic COMPLEX (KIND=8) or COMPLEX*16 (same as DOUBLE

COMPLEX) data is 16 contiguous bytes containing a pair of REAL*8 values stored in IEEE T_float format, VAX G_float, or VAX D_float formats.

The low-order eight bytes contain REAL (KIND=8) data that represents the real part of the complex data. The high-order eight bytes contain REAL

(KIND=8) data that represents the imaginary part of the complex data.

8–16 Data Types and Representation

Like REAL (KIND=8) or REAL*8 numbers, the sign bit representation is

0 (zero) for positive numbers and 1 for negative numbers. The limits (and underflow characteristics for T_float numbers) apply to the two separate real and imaginary parts of a COMPLEX (KIND=8) or COMPLEX*16 number.

Figure 8–14 shows the IEEE T_float COMPLEX (KIND=8) or COMPLEX*16 representation.

Figure 8–14 IEEE T_float COMPLEX (KIND=8) or COMPLEX*16 Representation

REAL

PART

IMAGINARY

PART

63 62

EXPONENT

52 51

FRACTION

:A+8

ZK−9818−GE

Figure 8–15 (G_float) and Figure 8–16 (D_float) show the representation of the

VAX COMPLEX (KIND=8) or COMPLEX*16 numbers.

Figure 8–15 VAX G_float COMPLEX (KIND=8) or COMPLEX*16 Representation

REAL

PART

IMAGINARY

PART

FRACTION

15 14

EXPONENT

FRAC−

TION

FRAC−

TION

:A+8

ZK−5305A−GE

Data Types and Representation 8–17

Figure 8–16 VAX D_float COMPLEX (KIND=8) or COMPLEX*16 Representation

REAL

PART

IMAGINARY

PART

FRACTION

15 14

EXPONENT

FRACTION

:A+8

ZK−5306A−GE

**8.4.7 COMPLEX (KIND=16) or COMPLEX*32 Representation**

Intrinsic COMPLEX (KIND=16) or COMPLEX*32 (extended precision) data is

32 contiguous bytes containing a pair of REAL*16 values stored in IEEE-style

X_float.

The low-order 16 bytes contain REAL (KIND=16) data that represents the real part of the complex data. The high-order 16 bytes contain REAL (KIND=16) data that represents the imaginary part of the complex data, as shown in

Figure 8–17.

Figure 8–17 COMPLEX (KIND=16) or COMPLEX*32 Representation

REAL

PART

IMAGINARY

PART

127 126

EXPONENT

112 111

FRACTION

:A+16

LJ−06690

The limits and underflow characteristics for REAL (KIND=16) apply to the two separate real and imaginary parts of a COMPLEX (KIND=16) or COMPLEX*32 number. Like REAL (KIND=16) numbers, the sign bit representation is 0 (zero) for positive numbers and 1 for negative numbers.

8–18 Data Types and Representation

For More Information:

• On converting unformatted data, see Chapter 9.

• On defining constants and assigning values to variables, see the HP

Fortran for OpenVMS Language Reference Manual.

• On intrinsic functions related to the various data types, such as

SELECTED_REAL_KIND, see the HP Fortran for OpenVMS Language

Reference Manual.

• On OpenVMS VAX floating-point data types (provided for those converting

OpenVMS data), see Section B.8.

• On the FORTRAN command qualifiers that control the size of REAL and

COMPLEX declarations (without a kind parameter or size specifier), see

Section 2.3.37.

• On the FORTRAN command qualifiers that control the size of DOUBLE

PRECISION declarations, see Section 2.3.17.

• On IEEE binary floating-point, see the IEEE Standard for Binary Floating-

Point Arithmetic (ANSI/IEEE Standard 754-1985).

8.4.8 Exceptional IEEE Floating-Point Representations

Exceptional values usually result from a computation and include plus infinity, minus infinity, NaN, and denormalized numbers. Exceptional values and the representation of zero are associated only with IEEE S_float, T_float, and X_float formats (/FLOAT=IEEE_FLOAT qualifier), not with VAX floatingpoint formats. (VAX floating-point representation of minus (–) zero causes a reserved operand fault on VAX systems.)

Floating-point numbers can be one of the following:

• Finite number—A floating-point number that represents a valid number

(bit pattern) within the normalized ranges of a particular data type, including –max to –min,—zero, +zero, +min to +max.

For any native floating-point data type, the values of min or max are listed in Section 8.4.2 (single precision), Section 8.4.3 (double precision), and

Section 8.4.4 (extended precision).

For native VAX floating-point data types, finite numbers do not include reserved operand or dirty zero values.

Special bit patterns that are not finite numbers represent exceptional values.

Data Types and Representation 8–19

• Infinity—An IEEE floating-point bit pattern that represents plus or minus infinity. HP Fortran identifies infinity values with the letters ‘‘Infinity’’ or asterisks ( ****** ) in output statements (depends on field width) or certain hexadecimal values (fraction of 0 and exponent of all 1 values).

• Not-a-Number (NaN)—An IEEE floating-point bit pattern that represents something other than a number. HP Fortran identifies NaN values with the letters ‘‘NaN’’ in output statements. A NaN can be a signaling NaN or a quiet NaN:

A quiet NaN might occur as a result of a calculation, such as 0./0. It has an exponent of all 1 values and initial fraction bit of 1.

A signaling NaN must be set intentionally (does not result from calculations) and has an exponent of all 1 values and initial fraction bit of 0 (with one or more other fraction bits of 1).

• Denormal—Identifies an IEEE floating-point bit pattern that represents a number whose value falls between zero and the smallest finite (normalized) number for that data type. The exponent field contains all zeros.

For negative numbers, denormalized numbers range from the next representable value larger than minus zero to the representable value that is one bit less than the smallest finite (normalized) negative number. For positive numbers, denormalized numbers range from the next representable value larger than positive zero to the representable value that is one bit less than the smallest finite (normalized) positive number.

• Zero—Can be the value +0 (all zero bits, also called true zero) or -0 (all zero bits except the sign bit, such as Z ’ 8000000000000000 ’ ).

A NaN or infinity value might result from a calculation that contains a divide by zero, overflow, or invalid data.

A denormalized number occurs when the result of a calculation falls within the denormalized range for that data type (subnormal value).

To control floating-point exception handling at run time for the main program, use the appropriate /IEEE_MODE qualifier keyword. For example, if an exceptional value is used in a calculation, an unrecoverable exception can occur unless you specify the appropriate /IEEE_MODE qualifier keyword.

Denormalized numbers can be processed as is, set equal to zero with program continuation or a program stop, and generate warning messages

(see Section 2.3.24).

8–20 Data Types and Representation

Table 8–2 lists the hexadecimal (hex) values of the IEEE exceptional floatingpoint numbers for S_float (single precision), T_float (double precision), and

X_float (extended precision) formats:

Table 8–2 IEEE Exceptional Floating-Point Numbers

Exceptional Number Hex Value

S_float Representation

Infinity (+)

Infinity (-)

Zero (+0)

Zero (-0)

Quiet NaN (+)

Signaling NaN (+)

’ 7F800000 ’

’ FF800000 ’

Z ’ 00000000 ’

Z ’ 80000000 ’

From Z ’ 7FC00000 ’ to Z ’ 7FFFFFFF ’

From Z ’ 7F800001 ’ to Z ’ 7FBFFFFF ’

T_float Representation

Infinity (+)

Infinity (-)

Zero (+0)

Zero (-0)

Quiet NaN (+)

Signaling NaN (+)

X_float Representation

Infinity (+)

Infinity (-)

Zero (+0)

Zero (-0)

Quiet NaN (+)

Signaling NaN (+)

From Z

’ 7FF0000000000000 ’

’ FFF0000000000000 ’

’ 0000000000000000 ’

’ 8000000000000000 ’

’ 7FF8000000000000 ’ to Z ’ 7FFFFFFFFFFFFFFF ’

’ 7FF0000000000001 ’ to Z ’ 7FF7FFFFFFFFFFFF ’

’ 7FFF0000000000000000000000000000 ’

’ FFFF0000000000000000000000000000 ’

’ 000000000000000000000000000000000 ’

’ 800000000000000000000000000000000 ’

From Z to Z

From Z

’ 7FFF80000000000000000000000000000 ’

’ 7FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF ’

’ 7FFF00000000000000000000000000001 ’ to Z ’ 7FFF7FFFFFFFFFFFFFFFFFFFFFFFFFFFF ’

HP Fortran supports IEEE exception handling, allowing you to test for infinity by using a comparison of floating-point data (such as generating positive infinity by using a calculation such as x=1.0/0 and comparing x to the calculated number).

Data Types and Representation 8–21

The appropriate FORTRAN command /IEEE_MODE qualifier keyword allows program continuation when a calculation results in a divide by zero, overflow, or invalid data arithmetic exception, generating an exceptional value (a NaN or Infinity (+ or –)).

To test for a NaN when HP Fortran allows continuation for arithmetic exception, you can use the ISNAN intrinsic function. Example 8–1 shows how to use the ISNAN intrinsic function to test whether a REAL*8 (DOUBLE

PRECISION) value contains a NaN.

Example 8–1 Testing for a NaN Value

DOUBLE PRECISION A, B, F

A = 0.

B = 0.

Perform calculations with variables A and B

f contains the value to check against a particular NaN

F = A / B

IF (ISNAN(F)) THEN

WRITE (6,*) ’--> Variable F contains a NaN value <--’

ENDIF

Inform user that f has the hardware quiet NaN value

Perform calculations with variable F (or stop program early)

END

To allow continuation when a NaN (or other exceptional value) is encountered in a calculation, this program might be compiled with /FLOAT=IEEE_FLOAT and /IEEE_MODE=UNDERFLOW_TO_ZERO (or /IEEE_MODE=DENORM_

RESULTS) qualifiers:

$ FORTRAN/FLOAT=IEEE_FLOAT/IEEE_MODE=UNDERFLOW_TO_ZERO ISNAN

$ LINK ISNAN

$ RUN ISNAN

--> Variable F contains a NaN value <--

To enable additional run-time message reporting with traceback information

(source line correlation), use the FORTRAN command qualifier /CHECK=FP_

EXCEPTIONS.

The FP_CLASS intrinsic function is also available to check for exceptional values (see the HP Fortran for OpenVMS Language Reference Manual).

8–22 Data Types and Representation

For More Information:

• On using the FORTRAN command /IEEE_MODE qualifier keywords to control arithmetic exception handling, see Section 2.3.24.

• On floating-point architecture, see the Intel Itanium Architecture Software

Developer’s Manual, Volume 1: Application Architecture.

• On Alpha exceptional values, see the Alpha Architecture Reference Manual.

• On IEEE binary floating-point exception handling, see the IEEE Standard

for Binary Floating-Point Arithmetic (ANSI/IEEE Standard 754-1985).

8.5 Character Representation

A character string is a contiguous sequence of bytes in memory, as shown in

Figure 8–18.

Figure 8–18 CHARACTER Data Representation

CHAR 1 :A

CHAR L :A+L−1

ZK−0809−GE

A character string is specified by two attributes: the address A of the first byte of the string, and the length L of the string in bytes. The length L of a string is in the range 1 through 65,535.

For More Information:

• On defining constants and assigning values to variables, using substring expressions and concatenation, see the HP Fortran for OpenVMS Language

Reference Manual.

• On intrinsic functions related to the various data types, see the HP Fortran

for OpenVMS Language Reference Manual.

Data Types and Representation 8–23

8.6 Hollerith Representation

Hollerith constants are stored internally, one character per byte. When

Hollerith constants contain the ASCII representation of characters, they resemble the storage of character data (see Figure 8–18).

When Hollerith constants store numeric data, they usually have a length of one, two, four, or eight bytes and resemble the corresponding numeric data type.

For More Information:

• On defining constants and assigning values to variables, see the HP

Fortran for OpenVMS Language Reference Manual.

• On intrinsic functions related to the various data types, see the HP Fortran

for OpenVMS Language Reference Manual.

8–24 Data Types and Representation

Converting Unformatted Numeric Data

This chapter describes:

• Section 9.1, Overview of Converting Unformatted Numeric Data

• Section 9.2, Endian Order of Numeric Formats

• Section 9.3, Native and Supported Nonnative Numeric Formats

• Section 9.4, Limitations of Numeric Conversion

• Section 9.5, Methods of Specifying the Unformatted Numeric Format

• Section 9.6, Additional Information on Nonnative Data

9.1 Overview of Converting Unformatted Numeric Data

You specify the floating-point format in memory with the /FLOAT qualifier. HP

Fortran supports the following little endian floating-point formats in memory

(default is /FLOAT=G_FLOAT):

Floating-Point

Size

KIND=4

KIND=8

KIND=16

/FLOAT=IEEE_FLOAT

S_float

T_float

X_float

/FLOAT=D_FLOAT

F_float

D_float

X_float

/FLOAT=G_FLOAT

F_float

G_float

X_float

If your program needs to read or write unformatted data files containing a floating-point format that differs from the format in memory for that data size, you can request that the unformatted data be converted.

For example, if your program primarily uses IEEE little endian floating-point data, specify /FLOAT=IEEE_FLOAT to specify use of the S_float, T_float, and X_float formats in memory. If your program needs to read a data file containing a different format (VAX or big endian), you need to specify which

Converting Unformatted Numeric Data 9–1

VAX or big endian floating-point format to use for conversion into the native

IEEE memory format for that file.

Converting unformatted data is generally faster than converting formatted data and is less likely to lose precision for floating-point numbers.

9.2 Endian Order of Numeric Formats

Data storage in different computers use a convention of either little endian or big endian storage. The storage convention generally applies to numeric values that span multiple bytes, as follows:

• Little endian storage occurs when:

The least significant bit (LSB) value is in the byte with the lowest address.

The most significant bit (MSB) value is in the byte with the highest address.

The address of the numeric value is the byte containing the LSB.

Subsequent bytes with higher addresses contain more significant bits.

• Big endian storage occurs when:

The least significant bit (LSB) value is in the byte with the highest address.

The most significant bit (MSB) value is in the byte with the lowest address.

The address of the numeric value is the byte containing the MSB.

Subsequent bytes with higher addresses contain less significant bits.

Figure 9–1 shows the difference between the two byte-ordering schemes.

9–2 Converting Unformatted Numeric Data

Figure 9–1 Little and Big Endian Storage of an INTEGER Value

Little Endian

Byte Order

0 0 0 1 0 0 1 1 0 0 0 1 0 0 0 1 0 0 0 1 0 0 0 1 1 1 0 1 0 0 0 1

1003 1002 1001 1000

Big Endian

Byte Order

0 0 0 1 0 0 1 1 0 0 0 1 0 0 0 1 0 0 0 1 0 0 0 1 1 1 0 1 0 0 0 1

1000 1001 1002 1003

ZK−6654A−GE

Moving data files between big endian and little endian computers requires that the data be converted.

9.3 Native and Supported Nonnative Numeric Formats

HP Fortran provides the capability for programs to read and write unformatted data (originally written using unformatted I/O statements) in several nonnative floating-point formats and in big endian INTEGER or floating-point format.

When reading a nonnative unformatted format, the nonnative format on disk must be converted to native format in memory. Similarly, native data in memory can be written to a nonnative unformatted format. If a converted nonnative value is outside the range of the native data type, a run-time message appears (listed in Section 7.2).

Supported native and nonnative floating-point formats include:

• Standard IEEE little endian floating-point formats

1 and little endian integers. This format is found on HP OpenVMS I64 systems, HP OpenVMS

Alpha systems, HP Tru64 UNIX systems, and Microsoft Windows operating systems (for IBM-compatible PC systems).

1 IEEE floating-point formats are defined in the IEEE Standard for Binary

Floating-Point Arithmetic, ANSI/IEEE Standard 754-1985, Institute of Electrical and

Electronics Engineers, August 1985.

Converting Unformatted Numeric Data 9–3

• Standard IEEE big endian floating-point formats

1 and big endian integers found on most Sun systems, HP-UX systems, and IBM RISC System/6000 systems.

• VAX little endian floating-point formats and little endian integers supported by Compaq Fortran 77 and HP Fortran for OpenVMS I64 and Alpha systems and Compaq Fortran 77 for OpenVMS VAX systems.

(OpenVMS VAX systems use a different 16-byte REAL format.)

• Big endian proprietary floating-point formats and big endian integers associated with CRAY (CRAY systems).

• Big endian proprietary floating-point formats and big endian integers associated with IBM (the IBM’s System\ 370 and similar systems).

The native memory format uses little endian integers and little endian floating-point formats, as follows:

• INTEGER and LOGICAL declarations of one, two, four, or eight bytes

(intrinsic kinds 1, 2, 4, and 8). You can specify the integer data length by using an explicit data declaration (kind parameter or size specifier).

All INTEGER and LOGICAL declarations without a kind parameter or size specifier will be four bytes in length. To request an 8-byte size for all

INTEGER and LOGICAL declarations without a kind parameter or size specifier, use a FORTRAN command qualifier (see Section 8.2.1).

• The following floating-point sizes and formats are available:

Single-precision 4-byte REAL and 8-byte COMPLEX declarations

(KIND=4) in either IEEE S_float or VAX F_float formats. This is the default size for all REAL or COMPLEX declarations without a kind parameter or size specifier.

Double-precision 8-byte REAL and 16-byte COMPLEX declarations

(KIND=8) in IEEE T_float, VAX G_float, or VAX D_float formats. This is the default size for all DOUBLE PRECISION declarations.

Extended-precision 16-byte REAL declarations and 32-byte COMPLEX declarations (KIND=16) in IEEE-like X_float format.

You can specify the real or complex data length by using an explicit data declaration (kind parameter or size specifier). You can change the default size for REAL, COMPLEX, and DOUBLE PRECISION declarations by using FORTRAN command qualifiers (/REAL_SIZE or /DOUBLE_SIZE).

9–4 Converting Unformatted Numeric Data

Table 9–1 lists the keywords for the supported unformatted file data formats.

Use the appropriate keyword after the /CONVERT qualifier (such as

/CONVERT=CRAY) or as an logical name value (see Section 9.5).

Table 9–1 Unformatted Numeric Formats, Keywords, and Supported Data

Types

Recognized

Keyword Description

BIG_ENDIAN

CRAY

IBM

FDX

FGX

Big endian integer data of the appropriate INTEGER size (one, two, or four bytes) and big endian IEEE floating-point formats for REAL and COMPLEX single- and double-precision numbers.

INTEGER (KIND=1) or INTEGER*1 data is the same for little endian and big endian.

Big endian integer data of the appropriate INTEGER size (one, two, four, or eight bytes) and big endian CRAY proprietary floating-point format for REAL and COMPLEX single- and double-precision numbers.

Big endian integer data of the appropriate INTEGER size (one, two, or four bytes) and big endian IBM proprietary floating-point format for REAL and COMPLEX single- and double-precision numbers.

Native little endian integers of the appropriate INTEGER size

(one, two, four, or eight bytes) and the following native little endian proprietary floating-point formats:

F_float for REAL (KIND=4) and COMPLEX (KIND=4)

D_float for REAL (KIND=8) and COMPLEX (KIND=8)

IEEE-like X_float for REAL (KIND=16) and COMPLEX

(KIND=16)

For information on these native OpenVMS formats, see Table 8–1 and Section 8.4.

Native little endian integers of the appropriate INTEGER size

(one, two, four, or eight bytes) and the following native little endian proprietary floating-point formats:

F_float for REAL (KIND=4) and COMPLEX (KIND=4)

G_float for REAL (KIND=8) and COMPLEX (KIND=8)

IEEE-like X_float for REAL (KIND=16) and COMPLEX

(KIND=16)

For information on these native OpenVMS formats, see Table 8–1 and Section 8.4.

(continued on next page)

Converting Unformatted Numeric Data 9–5

Table 9–1 (Cont.) Unformatted Numeric Formats, Keywords, and Supported

Data Types

Recognized

Keyword Description

LITTLE_ENDIAN

NATIVE

VAXD

VAXG

Little endian integers of the appropriate INTEGER size (one, two, four, or eight bytes) and the following native little endian

IEEE floating-point formats:

S_float for REAL (KIND=4) and COMPLEX (KIND=4)

T_float for REAL (KIND=8) and COMPLEX (KIND=8)

IEEE-like X_float for REAL (KIND=16) and COMPLEX

(KIND=16)

For information on these native OpenVMS formats, see Table 8–1 and Section 8.4.

No conversion occurs between memory and disk. This is the default for unformatted files.

Native little endian integers of the appropriate INTEGER size

(one, two, four, or eight bytes) and the following little endian

VAX proprietary floating-point formats:

F_float for REAL (KIND=4) and COMPLEX (KIND=4)

D_float for REAL (KIND=8) and COMPLEX (KIND=8)

H_float for REAL (KIND=16)

For information on the F_float and D_float formats, see Table 8–1 and Section 8.4. For information on the H_float format (available only on VAX systems), see Section B.8.

Native little endian integers of the appropriate INTEGER size

(one, two, four, or eight bytes) and the following little endian

VAX proprietary floating-point formats:

F_float format for REAL (KIND=4) and COMPLEX

(KIND=4)

G_float format for REAL (KIND=8) and COMPLEX

(KIND=8)

H_float format for REAL (KIND=16)

For information on the F_float and D_float formats, see Table 8–1 and Section 8.4. For information on the H_float format (available only on VAX systems), see Section B.8.

While this solution is not expected to fulfill all floating-point conversion needs, it provides the capability to read and write various types of unformatted nonnative floating-point data.

9–6 Converting Unformatted Numeric Data

For More Information:

• On ranges and the format of native IEEE floating-point data types, see

Table 8–1 and Section 8.4.

• On ranges and the format of VAX floating-point data types, see Section B.8.

• On specifying the size of INTEGER declarations (without a kind) using an

FORTRAN command qualifier, see Section 8.2.1.

• On specifying the size of LOGICAL declarations (without a kind) using an

FORTRAN command qualifier, see Section 8.3.

• On specifying the size of REAL or COMPLEX declarations (without a kind) using an FORTRAN command qualifier, see Section 8.4.1.

• On data declarations and other HP Fortran language information, see the

HP Fortran for OpenVMS Language Reference Manual.

9.4 Limitations of Numeric Conversion

The HP Fortran floating-point conversion solution is not expected to fulfill all floating-point conversion needs.

Data (variables) in record structures (specified in a STRUCTURE statement) and data components of derived types (TYPE statement) are not converted.

When variables are later examined as separate fields by the program, they will remain in the binary format they were stored in on disk, unless the program is modified.

If a program reads an I/O record containing multiple floating-point fields into an integer array (instead of their respective variables), the fields will not be converted. When they are later examined as separate fields by the program, they will remain in the binary format they were stored in on disk, unless the program is modified. To convert floating-point formats for individual fields, consider using the CVT$CONVERT_FLOAT routine (see Example B–1).

With EQUIVALENCE statements, the data type of the variable named in the

I/O statement is used.

9.5 Methods of Specifying the Unformatted Numeric Format

The methods you can use to specify the type of numeric floating-point format are as follows:

• Set a logical name for a specific unit number before the file is opened. The logical name is named FOR$CONVERTnnn, where nnn is the unit number.

Converting Unformatted Numeric Data 9–7

• Set a logical name for a specific file name extension before the file is opened. The logical name is named FOR$CONVERT.ext (or

FOR$CONVERT_ext), where ext is the file name extension (suffix).

• Add the CONVERT specifier to the OPEN statement for a specific unit number.

• Compiling the program with an OPTIONS statement that specifies the

/CONVERT=keyword qualifier. This method affects all unit numbers using unformatted data specified by the program.

• Compiling the program with the FORTRAN command /CONVERT=keyword qualifier. This method affects all unit numbers using unformatted data specified by the program.

If you specify more than one method, the order of precedence when you open a file with unformatted data is:

Check for a logical name for a specific unit number

Check for a FOR$CONVERT.ext logical name and then for a

FOR$CONVERT_ext logical name (if the former logical name is not found)

Check for the OPEN statement CONVERT specifier

Check whether an OPTIONS statement with a /CONVERT=(keyword) qualifier was present when the program was compiled

Check whether the FORTRAN command /CONVERT=(keyword) qualifier was used when the program was compiled

If none of these methods are specified, no conversion occurs between disk and memory. Data should therefore be in the native memory format (little endian integer and little endian IEEE or VAX format) or otherwise translated by the application program.

Any keyword listed in Table 9–1 can be used with any of these methods.

9.5.1 Logical Name FOR$CONVERTnnn Method

You can use the logical name method to specify multiple formats in a single program, usually one format for each unit number. You specify the numeric format at run time by setting the appropriate logical name before you open that unit number. For unit numbers that contain fewer than three digits, use leading zeros.

9–8 Converting Unformatted Numeric Data

For example, to specify the numeric format for unit 9, set logical name

FOR$CONVERT009 to the appropriate value (such as BIG_ENDIAN) before you run the program. For unit 125, set the logical name FOR$CONVERT125 before you run the program.

When you open the file, the logical name is always used, since this method takes precedence over the FORTRAN command qualifier methods. For instance, you might use this method to specify that different unformatted numeric formats for different unit numbers (perhaps in a command procedure that sets the logical name before running the program).

For example, assume you have a previously compiled program that reads numeric data from unit 28 and writes it to unit 29 using unformatted I/O statements. You want the program to read nonnative big endian (IEEE floating-point) format from unit 28 and write that data in native little endian format to unit 29.

In this case, the data is converted from big endian IEEE format to native little endian IEEE memory format (S_float and T_float) when read from unit 28, and then written without conversion in native little endian IEEE format to unit 29.

The FORTRAN command qualifier /FLOAT specifies the IEEE floating-point format in memory and the LINK command creates the executable program:

$ FORTRAN/FLOAT=IEEE_FLOAT CONV_IEEE

$ LINK CONV_IEEE

Without requiring source code modification of recompilation of this program, the following DCL command sequence sets the appropriate logical name and then runs the program CONV_IEEE.EXE:

$ DEFINE FOR$CONVERT028 BIG_ENDIAN

$ DEFINE FOR$CONVERT029 NATIVE

$ RUN CONV_IEEE

Figure 9–2 shows the data formats used on disk and in memory when the example file conv_ieee.exe is run after the logical names are set with DCL commands.

Converting Unformatted Numeric Data 9–9

Figure 9–2 Sample Unformatted File Conversion

Native Memory Formats

Little Endian Integers and

Little Endian IEEE S_float,

T_float, and X_float Formats

Unit 28: Read

Big Endian IEEE and Convert to

Native Formats

Unformatted Data Files on Disk

Unit 29: Do Not Convert;

Write Native Memory Formats

(Little Endian IEEE)

ZK−6655A−GE

For information on the DCL commands you can use to define and deassign logical names, see Appendix D.

9.5.2 Logical Name FOR$CONVERT.ext (and FOR$CONVERT_ext)

Method

You can use this method to specify formats in a single program, usually one format for each specified file name extension (suffix). You specify the numeric format at run time by setting the appropriate logical name before an implicit or explicit OPEN statement to one or more unformatted files.

For example, assume you have a previously compiled program that reads floating-point numeric data from one file and writes to another file using unformatted I/O statements. You want the program to read nonnative big endian (IEEE floating-point) format from a file with a .dat file extension suffix and write that data in native little endian format to a file with a suffix of .data.

You would DEFINE FOR$CONVERT.DAT BIG_ENDIAN.

In this case, the data is converted from big endian IEEE format to native little endian IEEE memory format when read from file.dat, and then written without conversion in native little endian IEEE format to the file with a suffix of .data, assuming that logical names FOR$CONVERT.DATA and FOR$CONVERTnnn

(for that unit number) are not defined.

9–10 Converting Unformatted Numeric Data

The FOR$CONVERTnnn method takes precedence over this method. When the appropriate logical name is set when you open the file, the FOR$CONVERT.ext logical name is used if a FOR$CONVERTnnn logical name is not set for the unit number.

The FOR$CONVERTnnn and FOR$CONVERT.ext (or FOR$CONVERT_ext) logical name methods take precedence over the other methods. For instance, you might use this method to specify that a unit number will use a particular format instead of the format specified in the program (perhaps for a one-time file conversion).

See Example 9–1.

Example 9–1 Example Showing the Use of the FOR$CONVERT.ext Method

Source program: program p integer i real r open( file=’convert_in.txt’, unit=10) open( file=’convert_out.big’, unit=11, form="unformatted") open( file=’convert_out.dat’, unit=12, form="unformatted") do i = 1, 10 read(10,*) r ! In text type *,r write(11) r write(12) r enddo close(10) close(11) close(12) end

! In BIG_ENDIAN

! In NATIVE

Assume the following data in the file convert_in.txt

(continued on next page)

Converting Unformatted Numeric Data 9–11

ÀA

àA

Example 9–1 (Cont.) Example Showing the Use of the FOR$CONVERT.ext

Method

Define the following symbols:

$ def for$convert.big big_endian

$ def for$convert.dat native

Then after you run the compiled source program, you get the following output:

1.000000

2.000000

3.000000

4.000000

5.000000

6.000000

7.000000

8.000000

9.000000

10.00000

And the following data in the big endian output file convert_out.big

@À

@à

And the following data in the native output file convert_out.dat

9–12 Converting Unformatted Numeric Data

9.5.3 OPEN Statement CONVERT=’keyword’ Method

You can use the OPEN statement method to specify multiple formats in a single program, usually one format for each specified unit number. This method requires an explicit file OPEN statement to specify the numeric format of the file for that unit number.

This method takes precedence over the /CONVERT=keyword method (see

Section 9.5.5), but has a lower precedence than the logical name method.

The following source code shows an OPEN statement coded for unformatted

VAXD numeric data (read from unit 15), and an OPEN statement coded for unformatted native little endian format (written to unit 20). The absence of the CONVERT specifier (in the second OPEN statement) or logical name

FOR$CONVERT020 indicates native little endian data for unit 20:

OPEN (CONVERT=’VAXD’, FILE=’graph3.dat’, FORM=’UNFORMATTED’, UNIT=15)

OPEN (FILE=’graph3_ieee.dat’, FORM=’UNFORMATTED’, UNIT=20)

A hard-coded OPEN statement CONVERT specifier keyword value cannot be changed after compile time. However, to allow selection of a particular format at run time, you can equate the CONVERT specifier to a variable and provide the user with a menu that allows selection of the appropriate format (menu choice sets the variable) before the OPEN occurs.

You can also select a particular format for a unit number at run time by using the logical name method (see Section 9.5.1), which takes precedence over the

OPEN statement CONVERT specifier method.

You can issue an INQUIRE statement (by unit number) to an opened file to obtain the current CONVERT method in use.

**9.5.4 OPTIONS Statement /CONVERT=keyword Method**

You can only specify one numeric file format for all unit numbers using this method, unless you also use the logical name or OPEN statement CONVERT specifier method.

You specify the numeric format at compile time and must compile all routines under the same OPTIONS statement CONVERT=keyword qualifier. You could use one source program and compile it using different FORTRAN commands to create multiple executable programs that each read a certain format.

Converting Unformatted Numeric Data 9–13

The logical name or OPEN CONVERT specifier methods take precedence over this method. For instance, you might use the logical name or OPEN

CONVERT specifier method to specify each unit number that will use a format other than that specified using the FORTRAN command qualifier method. This method takes precedence over the FORTRAN command /CONVERT qualifier method.

You can use OPTIONS statements to specify the appropriate floatingpoint formats (in memory and in unformatted files) instead of using the corresponding FORTRAN command qualifiers. For example, to use G_float as both the memory format and as the unformatted file format, specify the following OPTIONS statements:

OPTIONS /FLOAT=G_FLOAT

OPTIONS /CONVERT=NATIVE

Because this method affects all unit numbers, you cannot read data in one format and write it in another format using the FORTRAN/CONVERT=keyword method alone, unless you use it in combination with the logical name method or the OPEN statement CONVERT keyword method to specify a different format for a particular unit number.

For More Information:

On the OPTIONS statement, see the HP Fortran for OpenVMS Language

Reference Manual.

**9.5.5 FORTRAN Command /CONVERT=keyword Qualifier Method**

You can specify only one numeric format for all unit numbers by using the FORTRAN command qualifier method, unless you also use the logical name method or CONVERT specifier method. You specify the numeric format at compile time and must compile all routines under the same

/CONVERT=keyword qualifier (or the equivalent OPTIONS statement).

If needed, you can use one source program and compile it using different

FORTRAN commands to create multiple executable programs that each read a certain format.

The other methods take precedence over this method. For instance, you might use the logical name or OPEN CONVERT specifier method to specify each unit number that will use a format other than that specified using the FORTRAN command qualifier method.

For example, the following DCL commands compile program FILE.F90 to use VAX D_float and F_float data. Data is converted between the file format and the little endian memory format (little endian integers, S_float and

T_float little endian IEEE floating-point format). The created file, VAXD_

CONVERT.EXE, is then run:

9–14 Converting Unformatted Numeric Data

$ FORTRAN/FLOAT=IEEE_FLOAT

/CONVERT=VAXD/OBJECT=VAXD_CONVERT.OBJ FILE.F90

$ LINK VAXD_CONVERT

$ RUN VAXD_CONVERT

Because this method affects all unit numbers, you cannot read or write data in different formats if you only use the FORTRAN /CONVERT=keyword method.

To specify a different format for a particular unit number, use the FORTRAN

/CONVERT=keyword method in combination with the logical name method or the OPEN statement CONVERT specifier method.

9.6 Additional Information on Nonnative Data

The following notes apply to porting nonnative data:

• When porting source code along with the unformatted data, vendors might use different units for specifying the record length (RECL specifier, see

Section 2.3.7) of unformatted files. While formatted files are specified in units of characters (bytes), unformatted files are specified in longword units (unless /ASSUME=BYTERECL is specified) for Compaq Fortran 77,

HP Fortran, and some other vendors. The Fortran 90 standard, in Section

9.3.4.5, states: ‘‘If the file is being connected for unformatted input/output, the length is measured in processor-dependent units.’’

• Certain vendors apply different OPEN statement defaults to determine the record type. The default record type (RECORDTYPE) with HP Fortran depends on the values for the ACCESS and FORM specifiers for the

OPEN statement, as described in the HP Fortran for OpenVMS Language

Reference Manual.

• Certain vendors use a different identifier for the logical data types, such as hex FF instead of 01 to denote ‘‘true.’’

• Source code being ported might be coded specifically for big endian use.

For More Information:

• On OPEN statement specifiers, see the HP Fortran for OpenVMS Language

Reference Manual.

• On HP Fortran file characteristics, see Section 6.5.

• On HP Fortran record types, see Section 6.5.3.

American National Standard Fortran 90, ANSI X3.198-1991, and International

Standards Organization standard ISO/IEC 1539:1991

Converting Unformatted Numeric Data 9–15

Using HP Fortran in the Common

Language Environment

This chapter describes:

• Section 10.1, Overview

• Section 10.2, HP Fortran Procedures and Argument Passing

• Section 10.3, Argument-Passing Mechanisms and Built-In Functions

• Section 10.4, Using the cDEC$ ALIAS and cDEC$ ATTRIBUTES Directives

• Section 10.5, OpenVMS Procedure-Calling Standard

• Section 10.6, OpenVMS System Routines

• Section 10.7, Calling Routines: General Considerations

• Section 10.8, Calling OpenVMS System Services

• Section 10.9, Calling Between Compaq Fortran 77 and HP Fortran

• Section 10.10, Calling Between HP Fortran and HP C

10.1 Overview

HP Fortran provides you with a variety of mechanisms for gaining access to procedures and system services external to your HP Fortran programs. By including CALL statements or function references in your source program, you can use procedures such as mathematical functions, OpenVMS system services, and routines written in such languages as Compaq Fortran 77 and HP C.

The HP Fortran compiler operates within the OpenVMS common language environment, which defines certain calling procedures and guidelines.

These guidelines allow you to use HP Fortran to call OpenVMS system or library routines and routines written in different languages (usually called mixed-language programming).

Using HP Fortran in the Common Language Environment 10–1

This chapter provides information on the OpenVMS procedure-calling standard and how to access OpenVMS system services.

For More Information:

About calling and using the RMS (Record Management Services) system services, see Chapter 11.

10.2 HP Fortran Procedures and Argument Passing

The bounds of the main program are usually defined by using PROGRAM and END or END PROGRAM statements. Within the main program, you can define entities related to calling a function or subroutine, including modules and interface blocks.

A function or subroutine is considered a subprogram. A subprogram can accept one or more data values passed from the calling routine; the values are called arguments.

There are two types of arguments:

• Actual arguments are specified in the subprogram call.

• Dummy arguments are variables within the function or subroutine that receive the values (from the actual arguments).

The following methods define the interface between procedures:

• Declare and name a function with a FUNCTION statement and terminate the function definition with an END FUNCTION statement. Set the value of the data to be returned to the calling routine by using the function name as a variable in an assignment statement (or by specifying RESULT in a

FUNCTION statement).

Reference a function by using its name in an expression.

• Declare and name a subroutine with a SUBROUTINE statement and terminate the subroutine definition with an END SUBROUTINE statement. No value is returned by a subroutine.

Reference a subroutine by using its name in a CALL statement (or use a defined assignment statement).

• For an external subprogram, depending on the type of arguments or function return values, you may need to declare an explicit interface to the arguments and function return value by using an interface block.

Declare and name an interface block with an INTERFACE statement and terminate the interface block definition with an END INTERFACE statement. The interface body that appears between these two statements consists of function or subroutine specification statements.

10–2 Using HP Fortran in the Common Language Environment

• You can make data, specifications, definitions, procedure interfaces, or procedures globally available to the appropriate parts of your program by using a module (use association).

Declare a module with a MODULE statement and terminate the module definition with an END MODULE statement. Include the definitions and other information contained within the module in appropriate parts of your program with a USE statement. A module can contain interface blocks, function and subroutine declarations, data declarations, and other information.

For More Information:

On the HP Fortran language, including statement functions and defined assignment statements not described in this manual, see the HP Fortran for

OpenVMS Language Reference Manual.

10.2.1 Explicit and Implicit Interfaces

An explicit interface occurs when the properties of the subprogram interface are known within the scope of the function or subroutine reference. For example, the function reference or CALL statement occurs at a point where the function or subroutine definition is known through host or use association.

Intrinsic procedures also have an explicit interface.

An implicit interface occurs when the properties of the subprogram interface are not known within the scope of the function or subroutine reference. In this case, the procedure data interface is unknown to the compiler. For example, external routines (EXTERNAL statement) that have not been defined in an interface block have an implicit interface.

In most cases, you can use a procedure interface block to make an implicit interface an explicit one. An explicit interface provides the following advantages over an implicit interface:

• Better compile-time argument checking and fewer run-time errors

• In some cases, faster run-time performance

• Ease of locating problems in source files since the features help to make the interface self-documenting

• Allows use of some language features that require an explicit interface, such as array function return values.

• When passing certain types of arguments between HP Fortran and non-

Fortran languages, an explicit interface may be needed. For example, detailed information about an assumed-shape array argument can be obtained from the passed array descriptor. The array descriptor is

Using HP Fortran in the Common Language Environment 10–3

generated when an appropriate explicit interface is used for certain types of array arguments.

For More Information:

On HP Fortran array descriptors, see Section 10.2.7.

10.2.2 Types of HP Fortran Subprograms

There are three major types of subprograms:

• A subprogram might be local to a single program unit (known only within its host). Since the subprogram definition and all its references are contained within the same program unit, it is called an internal

subprogram.

An internal subprogram has an explicit interface.

• A subprogram needed in multiple program units should be placed within a module. To create a module subprogram within a module, add a CONTAINS statement followed by the subprogram code. A module subprogram can also contain internal subprograms.

A module subprogram has an explicit interface in those program units that reference the module with a USE statement (unless it is declared

PRIVATE).

• External subprograms are needed in multiple program units but cannot be placed in a module. This makes their procedure interface unknown in the program unit in which the reference occurs. Examples of external subprograms include general-purpose library routines in standard libraries and subprograms written in other languages, like C or Ada.

Unless an external subprogram has an associated interface block, it has an implicit interface. To provide an explicit interface for an external subprogram, create a procedure interface block (see Section 10.2.3).

For subprograms with no explicit interface, declare the subprogram name as external using the EXTERNAL statement within the program unit where the external subprogram reference occurs. This allows the linker to resolve the reference.

An external subprogram must not contain PUBLIC or PRIVATE statements.

10–4 Using HP Fortran in the Common Language Environment

10.2.3 Using Procedure Interface Blocks

Procedure interface blocks allow you to specify an explicit interface for a subprogram as well as to define generic procedure names. This section limits discussion to those interface blocks used to provide an explicit subprogram interface. For complete information on interface blocks, see the HP Fortran for

OpenVMS Language Reference Manual.

The components of a procedure interface block follow:

• Begin a procedure interface block with an INTERFACE statement. Unless you are defining a generic procedure name, user-defined operator, or user-defined assignment, only the word INTERFACE is needed.

• To provide the interface body, copy the procedure specification statements from the actual subprogram, including:

The FUNCTION or SUBROUTINE statements.

The interface body. For a procedure interface block, this includes specification (declaration) statements for the dummy arguments and a function return value (omit data assignment, FORMAT, ENTRY, DATA, and related statements).

The interface body can include USE statements to obtain definitions.

The END FUNCTION or END SUBROUTINE statements.

• Terminate the interface block with an END INTERFACE statement.

• To make the procedure interface block available to multiple program units, you can do one of the following:

Place the procedure interface block in a module. Reference the module with a USE statement in each program unit that references the subprogram (use association).

Place the procedure interface block in each program unit that references the subprogram.

For an example of a module that contains a procedure interface block, see

Section 1.4.

Using HP Fortran in the Common Language Environment 10–5

10.2.4 Passing Arguments and Function Return Values

HP Fortran uses the same argument-passing conventions as Compaq Fortran

77 on OpenVMS Alpha systems for non-pointer scalar variables and explicitshape and assumed-size arrays.

When calling HP Fortran subprograms, be aware that HP Fortran expects to receive arguments the same way it passes them.

The main points about argument passing and function return values are as follows:

• Arguments are generally passed by reference (arguments contain an address).

An argument contains the address of the data being passed, not the data itself (unless explicitly specified otherwise, such as with the cDEC$

ATTRIBUTES directive or the %VAL built-in function).

Assumed-shape arrays and deferred-shape arrays are passed by array descriptor.

Character data is passed by character descriptor.

Arguments omitted by adding an extra comma ( , ) are passed as a zero by immediate value (see Section 10.8.4). Such arguments include OPTIONAL arguments that are not passed.

Any argument specified using the %DESCR built-in function is also passed by descriptor (see Section 10.3).

• Function return data is usually passed by immediate value (function return contains a value). Certain types of data (such as array-valued functions) are passed by other means.

The value being returned from a function call usually contains the actual

data, not the address of the data.

• Character variables, explicit-shape character arrays, and assumed-size character arrays are passed by a character descriptor (except for character constant actual arguments when /BY_REF_CALL is used).

Dummy arguments for character data can use an assumed length.

When passing character arguments to a C routine as strings, the character argument is not automatically null-terminated by the compiler. To nullterminate a string from HP Fortran, use the CHAR intrinsic function

(described in the HP Fortran for OpenVMS Language Reference Manual).

1 For compatibility with older Compaq Fortran 77 OpenVMS VAX programs, character constant actual arguments (string literals) can be passed by reference if the HP

Fortran program was compiled with the /BY_REF_CALL qualifier (see Section 2.3.9).

10–6 Using HP Fortran in the Common Language Environment

The arguments passed from a calling routine must match the dummy arguments declared in the called function or subroutine (or other procedure), as follows:

• Arguments must be in the same order, unless argument keywords are used.

Arguments are kept in the same position as they are specified by the user.

The exception to same position placement is the use of argument keywords to associate dummy and actual arguments.

• Each corresponding argument or function return value must at least match in data type, kind, and rank, as follows:

The primary HP Fortran intrinsic data types are character, integer, logical, real, and complex.

To convert data from one data type to another, use the appropriate intrinsic procedures described in the HP Fortran for OpenVMS

Language Reference Manual.

Also, certain attributes of a data item may have to match. For example, if a dummy argument has the POINTER attribute, its corresponding actual argument must also have the POINTER attribute

(see Section 10.2.6).

You can use the kind parameter to specify the length of each numeric intrinsic type, such as INTEGER (KIND=8). For character lengths, use the LEN specifier, perhaps with an assumed length for dummy character arguments (LEN=*).

The rank (number of dimensions) of the actual argument is usually the same (or less than) the rank of the dummy argument, unless an assumed-size dummy array is used.

When using an explicit interface, the rank of the actual argument must be the same as the rank of the dummy argument.

For example, when passing a scalar actual argument to a scalar dummy argument (no more than one array element or a nonarray variable), the rank of both is 0.

Other rules which apply to passing arrays and pointers are described in Section 10.2.5, Section 10.2.6, and in the HP Fortran for OpenVMS

Language Reference Manual.

• The means by which the argument is passed and received (passing mechanism) must match.

By default, HP Fortran arguments are passed by reference. (See

Table 10–1 for information about passing arguments with the C property.)

Using HP Fortran in the Common Language Environment 10–7

When calling functions or other routines that are intended to be called from another language (such as C), be aware that these languages may require data to be passed by other means, such as by value.

Most HP Fortran function return values are passed by value. Certain types of data (such as array-valued functions) are passed by other means.

In most cases, you can change the passing mechanism of actual arguments by using the following HP extensions: cDEC$ ATTRIBUTES directive (see Section 10.4.2)

Built-in functions (see Section 10.3)

• To explicitly specify the procedure (argument or function return) interface, provide an explicit interface.

You can use interface blocks and modules to specify INTENT and other attributes of actual or dummy arguments.

For More Information:

• On passing arguments, function return values, and the contents of registers on OpenVMS systems, see the HP OpenVMS Calling Standard.

• On intrinsic data types, see Chapter 8 and the HP Fortran for OpenVMS

Language Reference Manual.

• On intrinsic procedures and attributes available for array use, see the HP

Fortran for OpenVMS Language Reference Manual.

• On explicit interfaces and when they are required, see the HP Fortran for

OpenVMS Language Reference Manual.

• On an HP Fortran example program that uses an external subprogram and a module that contains a procedure interface block, see Example 1–3.

10.2.5 Passing Arrays as Arguments

Certain arguments or function return values require the use of an explicit interface, including assumed-shape dummy arguments, pointer dummy arguments, and function return values that are arrays. This is discussed in the HP Fortran for OpenVMS Language Reference Manual.

When passing arrays as arguments, the rank and the extents (number of elements in a dimension) should agree, so the arrays have the same shape and are conformable. If you use an assumed-shape array, the rank is specified and extents of the dummy array argument are taken from the actual array argument.

10–8 Using HP Fortran in the Common Language Environment

If the rank and extent (shape) do not agree, the arrays are not conformable.

The assignment of elements from the actual array to the noncomformable

(assumed-size or explicit-shape) dummy array is done by using array element sequence association.

Certain combinations of actual and dummy array arguments are disallowed.

For More Information:

• On the types of arrays and passing array arguments, see the HP Fortran

for OpenVMS Language Reference Manual.

• On explicit interfaces and when they are required, see the HP Fortran for

OpenVMS Language Reference Manual.

• On array descriptors, see Section 10.2.7.

10.2.6 Passing Pointers as Arguments

Previous sections have discussed the case where the actual and dummy arguments have neither the POINTER attribute nor the TARGET attribute.

The argument passing rules of like type, kind, and rank (for conformable arrays) or array element sequence association (for noncomformable arrays) apply when:

• Both actual and dummy arguments have the POINTER attribute (and must be conformable)

• Dummy arguments have the TARGET attribute

• Both actual and dummy arguments have neither attribute

If you specify an actual argument of type POINTER and a dummy argument of type POINTER, the dummy argument receives the correct pointer value if you specify (in the code containing the actual argument) an appropriate explicit interface that defines the dummy argument with the POINTER attribute and follows certain rules.

However, if you specify an actual argument of type POINTER and do not specify an appropriate explicit interface (such as an interface block), it is passed as actual (target) data.

For More Information:

On using pointers and pointer arguments, see the HP Fortran for OpenVMS

Language Reference Manual.

Using HP Fortran in the Common Language Environment 10–9

10.2.7 HP Fortran Array Descriptor Format

When using an explicit interface (by association or procedure interface block),

HP Fortran will generate a descriptor for the following types of dummy argument data structures:

• Pointers to arrays (array pointers)

• Assumed-shape arrays

To allow calling between Compaq Fortran 77 and HP Fortran, certain data structure arguments also supported by Compaq Fortran 77 do not use a descriptor, even when an appropriate explicit interface is provided. For example, since explicit-shape and assumed-size arrays are supported by both

Compaq Fortran 77 and HP Fortran, an array descriptor is not used.

When calling between HP Fortran and a non-Fortran language (such as C), you can specify an appropriate explicit interface or use an implicit interface.

However, for cases where the called routine needs the information in the array descriptor, declare the routine with an assumed-shape argument and an explicit interface.

The array descriptor used by HP Fortran is the OpenVMS Noncontiguous

Array Descriptor as described in the HP OpenVMS Calling Standard. In the

DSC$B_AFLAGS byte, bit DSC$V_FL_UNALLOC specifies whether storage has or has not been set for this array. If this bit is set, the array has not yet been allocated.

For example, for 32-bit address access, consider the following array declaration:

INTEGER,TARGET :: A(10,10)

INTEGER,POINTER :: P(:,:)

P => A(9:1:-2,1:9:3)

CALL F(P)

The descriptor for actual argument P (using 32-bit addresses) would contain the following values:

• length (DSC$W_LENGTH) contains 4.

• dtype (DSC$B_DTYPE) contains DSC$K_DTYPE_L.

• class (DSC$B_CLASS) contains DSC$K_CLASS_NCA.

• pointer (DSC$A_POINTER) contains the address of A (9,1).

• scale (DSC$B_SCALE) contains 0.

10–10 Using HP Fortran in the Common Language Environment

• digits (DSC$B_DIGITS) contains 0.

• aflags (DSC$B_AFLAGS) contains 0, since A is allocated, the

V_FL_UNALLOC bit is clear.

• dimen (DSC$B_DIMEN) contains 2.

• arsize (DSC$L_ARSIZE) contains 60.

• DSC$A_A0 contains the address of A(0,0).

• DSC$L_Si contains the stride of dimension i.

• DSC$L_Li contains the lower bound of dimension i.

• DSC$L_Ui contains the upper bound of dimension i.

For information about the Noncontiguous Array Descriptor when 64-bit addressing is requested (cDEC$ ATTRIBUTES ADDRESS64 directive), see the

HP OpenVMS Calling Standard.

10.3 Argument-Passing Mechanisms and Built-In Functions

The OpenVMS procedure-calling standard defines three mechanisms by which arguments are passed to procedures:

• By immediate value: The argument list entry contains the value.

• By reference: The argument list entry contains the address of the value.

• By descriptor: The argument list entry contains the address of a descriptor of the value.

By default, HP Fortran uses the reference and descriptor mechanisms to pass arguments, depending on each argument’s data type:

• The reference mechanism is used to pass all actual arguments that are numeric: logical, integer, real, and complex.

• The descriptor mechanism is used to pass all actual arguments that are character, Fortran 90 pointers, assumed-shape arrays, and deferred-shape arrays (except for character constant actual arguments when the HP

Fortran program was compiled with /BY_REF_CALL).

When an HP Fortran program needs to call a routine written in a different language (or in some cases a Fortran 90 subprogram), there may be a need to use a form other the HP Fortran default mechanisms. For example, OpenVMS system services may require that certain numeric arguments be passed by immediate value instead of by reference.

Using HP Fortran in the Common Language Environment 10–11

For cases where you cannot use the default passing mechanisms, HP Fortran provides three built-in functions for passing arguments. It also provides a built-in function for computing addresses for use in argument lists. These built-in functions are:

• %VAL, %REF, %DESCR: Argument list built-in functions

• %LOC: General usage built-in function

Except for the %LOC built-in function, which can be used in any arithmetic expression, these functions can appear only as unparenthesized arguments in argument lists. The three argument list built-in functions and %LOC built-in function are rarely used to call a procedure written in HP Fortran.

The use of these functions in system service calls is described in Section 10.8.4.

The sections that follow describe their use in general.

Instead of using the HP Fortran built-in functions, you can use the cDEC$

ATTRIBUTES directive to change the HP Fortran default passing mechanisms

(see Section 10.4.2).

10.3.1 Passing Arguments by Descriptor—%DESCR Function

The %DESCR function passes its argument by descriptor. It has the following form:

%DESCR(arg)

The argument generated by the compiler is the address of a descriptor of the argument (arg). The argument value can be any Fortran 90 expression. The argument value must not be a derived type, record name, record array name, or record array element. The compiler can generate OpenVMS descriptors for all Fortran data types.

In HP Fortran, the descriptor mechanism is the default for passing character arguments, Fortran 90 pointers, assumed-shape arrays, and deferred-shape arrays. This is because the subprogram may need to know the length or other information about the character, pointer, or array argument. HP Fortran always generates code to refer to character dummy arguments through the addresses in their character descriptors.

For More Information:

On HP Fortran array descriptors, see Section 10.2.7.

10–12 Using HP Fortran in the Common Language Environment

10.3.2 Passing Addresses—%LOC Function

The %LOC built-in function computes the address of a storage element as an INTEGER (KIND=8) (64-bit) value. With 64-bit addressing (cDEC$

ATTRIBUTE ADDRESS64 directive specified), all 64-bits are used. With

32-bit addressing (cDEC$ ATTRIBUTE ADDRESS64 directive omitted), only the lower 32 bits are used. You can then use this value in an arithmetic expression. It has the following form:

%LOC(arg)

The %LOC function is particularly useful for certain system services or non-

Fortran procedures that may require argument data structures containing the addresses of storage elements. In such cases, the data structures should be declared volatile to protect them from possible optimizations.

For More Information:

• On declaring volatile data structures, see the HP Fortran for OpenVMS

Language Reference Manual.

• On optimization and declaring volatile data, see Section 5.7.3.

• On an example that uses the %LOC function, see Example 10–4.

10.3.3 Passing Arguments by Immediate Value—%VAL Function

The %VAL function passes the argument list entry as a 64-bit immediate value.

It has the following form:

%VAL(arg)

The argument-list entry generated by the compiler is the value of the argument

(arg). The argument value can be a constant, variable, array element, or expression of type INTEGER, LOGICAL, REAL (KIND=4), REAL (KIND=8),

COMPLEX (KIND=4), or COMPLEX (KIND=8).

If a COMPLEX (KIND=4) or COMPLEX (KIND=8) argument is passed by value, two REAL arguments (one contains the real part; the other the imaginary part) are passed by immediate value. If a COMPLEX parameter to a routine is specified as received by value (or given the C attribute), two

REAL parameters are received and stored in the real and imaginary parts of the COMPLEX parameter specified.

If the value is a byte, word, or longword, it is sign-extended to a quadword

(eight bytes).

To produce a zero-extended value rather than a sign-extended value, use the

ZEXT intrinsic function.

Using HP Fortran in the Common Language Environment 10–13

For More Information:

• On intrinsic procedures, see the HP Fortran for OpenVMS Language

Reference Manual.

• On an example of passing integer data by value (using %VAL) and by reference (default) to a C function, see Section 10.10.7.

• On the ZEXT intrinsic function, see HP Fortran for OpenVMS Language

Reference Manual.

• On the %VAL built-in function, see the HP Fortran for OpenVMS Language

Reference Manual.

10.3.4 Passing Arguments by Reference—%REF Function

The %REF function passes the argument by reference. It has the following form:

%REF(arg)

The argument-list entry generated by the compiler will contain the address of the argument (arg). The argument value can be a record name, a procedure name, or a numeric or character expression, array, character array section, or array element. In HP Fortran, passing by reference is the default mechanism for numeric values, so the %REF call is usually not needed.

10.3.5 Examples of Argument Passing Built-in Functions

The following examples demonstrate the use of the argument list built-in functions.

In this example, the first constant is passed by reference. The second constant is passed by immediate value:

CALL SUB(2,%VAL(2))

In this example, the first character variable is passed by character descriptor. The second character variable is passed by reference:

CHARACTER(LEN=10) A,B

CALL SUB(A,%REF(B))

In this example, the first array is passed by reference. The second array is passed by descriptor:

INTEGER IARY(20), JARY(20)

CALL SUB(IARY,%DESCR(JARY))

10–14 Using HP Fortran in the Common Language Environment

10.4 Using the cDEC$ ALIAS and cDEC$ ATTRIBUTES

Directives

This section provides reference information about the following directives:

• The cDEC$ ALIAS (or !DEC$ ALIAS or *DEC$ ALIAS) directive allows you to specify a name for an external subprogram that differs from the name used by the calling subprogram.

• The cDEC$ ATTRIBUTES (or !DEC$ ATTRIBUTES or *DEC$

ATTRIBUTES) directive allows you to specify the properties for external data objects and procedures. This includes using C language rules, specifying how an argument is passed (passing mechanism), and specifying an alias for an external routine.

10.4.1 The cDEC$ ALIAS Directive

HP Fortran now supports the cDEC$ ALIAS directive in the same manner as

Compaq Fortran 77. Use this directive to specify that the external name of an external subprogram is different from the name by which the calling procedure references it.

The syntax is: cDEC$ ALIAS internal-name, external-name

The internal-name is the name of the subprogram as used in the current program unit.

The external-name is either a quoted character constant (delimited by single quotation marks) or a symbolic name.

If external-name is a character constant, the value of that constant is used as the external name for the specified internal name. The character constant is used as it appears, with no modifications for case. The default for the HP

Fortran compiler is to force the name into uppercase.

If external-name is a symbolic name, the symbolic name (in uppercase) is used as the external name for the specified internal name. Any other declaration of the specified symbolic name is ignored for the purposes of the ALIAS directive.

For example, in the following program (free source form):

Using HP Fortran in the Common Language Environment 10–15

PROGRAM ALIAS_EXAMPLE

!DEC$ ALIAS ROUT1, ’ROUT1A’

!DEC$ ALIAS ROUT2, ’routine2_’

!DEC$ ALIAS ROUT3, rout3A

CALL ROUT1

CALL ROUT2

CALL ROUT3

END PROGRAM ALIAS_EXAMPLE

The three calls are to external routines named ROUT1A, routine2_, and

ROUT3A. Use single quotation marks (character constant) to specify a casesensitive name.

This feature can be useful when porting code to systems where different routine naming conventions are in use. By adding or removing the cDEC$

ALIAS directive, you can specify an alternate routine name without recoding the application.

10.4.2 The cDEC$ ATTRIBUTES Directive

Use the cDEC$ ATTRIBUTES directive to specify properties for data objects and procedures. These properties let you specify how data is passed and the rules for invoking procedures. The cDEC$ ATTRIBUTES directive is intended to simplify mixed-language calls with HP Fortran routines written in C or

Assembler.

The cDEC$ ATTRIBUTES directive takes the following form: cDEC$ ATTRIBUTES att [,att]... :: object [,object]...

In this form: c

Is the letter or character (c, C, *, !) that introduces the directive (see HP

Fortran for OpenVMS Language Reference Manual. ) att

Is one of the keywords listed in the HP Fortran for OpenVMS Language

Reference Manual. For example, C, ALIAS, REFERENCE, VALUE,

EXTERN, VARYING, and ADDRESS64 object

Is the name of a data object used as an argument or procedure. Only one object is allowed when using the C and ALIAS properties.

The HP Fortran for OpenVMS Language Reference Manual explains the valid combinations of properties with the various types of objects.

10–16 Using HP Fortran in the Common Language Environment

The ATTRIBUTES properties are described in the following sections:

• C Property, Section 10.4.2.1

• ALIAS Property, Section 10.4.2.2

• REFERENCE and VALUE Properties, Section 10.4.2.3

• EXTERN and VARYING Properties, Section 10.4.2.4

• ADDRESS64 Property, Section 10.4.2.5

10.4.2.1 C Property

The C property provides a convenient way for HP Fortran to interact with routines written in C.

When applied to a subprogram, the C property defines the subprogram as having a specific set of calling conventions.

The C property affects how arguments are passed, as described in Table 10–1.

Table 10–1 C Property and Argument Passing

Argument Variable Type

Scalar (includes derived types)

Fortran Default

Passed by reference

Scalar, with VALUE specified

Scalar, with REFERENCE specified

String

String, with VALUE specified

String, with REFERENCE specified

Arrays, including pointers to arrays

Passed by value

Passed by reference

Passed by character descriptor

Error

Passed by reference

Always passed by reference

C Property Specified for Routine

Passed by value (large derived type variables may be passed by reference)

Passed by value

Passed by reference

Passes the first character of the string, padded to a full integer

Passed by reference

Always passed by reference

Using HP Fortran in the Common Language Environment 10–17

If C is specified for a subprogram, arguments (except for arrays and characters) are passed by value. Subprograms using standard Fortran conventions pass arguments by reference.

Character arguments are passed as follows:

• If C is specified without REFERENCE for the arguments, the first character of the string is passed (padded with zeros out to INTEGER*4 length).

• If C is specified with REFERENCE for the argument (or if only

REFERENCE is specified), the starting address of the string is passed with no descriptor.

Example 10–1 shows HP Fortran code that calls the C function PNST by using the cDEC$ ATTRIBUTES C directive and C language passing conventions.

Example 10–1 Calling C Functions and Passing Integer Arguments

! Using !DEC$ ATTRIBUTES to pass argument to C. File: pass_int_cdec.f90

interface subroutine pnst(i)

!DEC$ ATTRIBUTES C :: pnst integer i end subroutine end interface integer :: i i = 99 call pnst(i) print *,"99==",i end

! pass by value

Example 10–2 shows the C function called program shown in Example 10–1

PNST that is called by the example

Example 10–2 Calling C Functions and Passing Integer Arguments

/* get integer by value from Fortran. File: pass_int_cdec_c.c */ void pnst(int i) { printf("99==%d\n",i); i = 100;

}

10–18 Using HP Fortran in the Common Language Environment

The files (shown in Example 10–1 and Example 10–2) might be compiled, linked, and run as follows:

$ CC PASS_INT_CDEC_C.C

$ FORTRAN PASS_INT_CDEC.F90

$ LINK/EXECUTABLE=PASS_CDEC PASS_INT_CDEC, PASS_INT_CDEC_C

$ RUN PASS_CDEC

99==99

99== 99

10.4.2.2 ALIAS Property

You can specify the ALIAS property as cDEC$ ALIAS or as cDEC$

ATTRIBUTES ALIAS; they are equivalent, except that using cDEC$ ALIAS allows symbol names (see Section 10.4.1).

The ALIAS property allows you to specify that the external name of an external subprogram is different from the name by which the calling procedure references it (see Section 10.4.1).

10.4.2.3 REFERENCE and VALUE Properties

The following cDEC$ ATTRIBUTES properties specify how a dummy argument is to be passed:

• REFERENCE specifies a dummy argument’s memory location is to be passed, not the argument’s value.

• VALUE specifies a dummy argument’s value is to be passed, not the argument’s memory location.

Character values, substrings, and arrays cannot be passed by value. When

REFERENCE is specified for a character argument, the string is passed with no descriptor.

VALUE is the default if the C property is specified in the subprogram definition

(for scalar data only).

Consider the following free-form example, which passes an integer by value: interface subroutine foo (a)

!DEC$ ATTRIBUTES value :: a integer a end subroutine foo end interface

Using HP Fortran in the Common Language Environment 10–19

This subroutine can be invoked from HP Fortran using the name foo: integer i i = 1 call foo(i) end program

This is the actual subroutine code: subroutine foo (i)

!DEC$ ATTRIBUTES value :: i integer i i = i + 1

end subroutine foo

10.4.2.4 EXTERN and VARYING Properties

The EXTERN property specifies that a variable is allocated in another source file. EXTERN can be used in global variable declarations, but it must not be applied to dummy arguments.

You must use EXTERN when accessing variables declared in other languages.

The VARYING directive allows a variable number of calling arguments. If

VARYING is specified, the C property must also be specified.

When using the VARYING directive, either the first argument must be a number indicating how many arguments to process, or the last argument must be a special marker (such as 01 ) indicating it is the final argument. The sequence of the arguments, and types and kinds, must be compatible with the called procedure.

For More Information:

See the HP Fortran for OpenVMS Language Reference Manual.

10.4.2.5 ADDRESS64 Property

Specifies that the object has a 64-bit address. This property can be specified for any variable or dummy argument, including ALLOCATABLE and deferredshape arrays. However, variables with this property cannot be data-initialized.

It can also be specified for COMMON blocks or for variables in a COMMON block. If specified for a COMMON block variable, the COMMON block implicitly has the ADDRESS64 property.

ADDRESS64 is not compatible with the AUTOMATIC attribute.

10–20 Using HP Fortran in the Common Language Environment

For More Information:

• On requirements and the use of 64-bit virtual addresses, see the online release notes.

• On the memory layout of process and system memory, see the OpenVMS

Alpha Guide to 64-Bit Addressing and VLM Features.

• On passing arguments, argument types, function return values, and the contents of registers on OpenVMS systems, see the HP OpenVMS Calling

Standard.

• On HP Fortran intrinsic data types, see Chapter 8.

• On the HP Fortran language, see the HP Fortran for OpenVMS Language

Reference Manual.

• On the HP C language, see the HP C Language Reference Manual.

• On the CC command, see the HP C User’s Guide for OpenVMS Systems.

10.5 OpenVMS Procedure-Calling Standard

Programs compiled by the HP Fortran compiler conform to the standard defined for OpenVMS procedure calls (see the OpenVMS Programming

Interfaces: Calling a System Routine and HP OpenVMS Calling Standard).

This standard prescribes how registers and the system-maintained call stack can be used, how function values are returned, how arguments are passed, and how procedures receive and return control.

When writing routines that can be called from HP Fortran programs, you should give special consideration to the argument list descriptions in

Section 10.5.3.

10.5.1 Register and Stack Usage

For information about register and stack usage on I64, see the HP OpenVMS

Calling Standard.

10.5.1.1 Register and Stack Usage on Alpha

The Alpha architecture provides 32 general purpose integer registers (R0-R31) and 32 floating-point registers (F0-F31), each 64 bits in length. The OpenVMS

Programming Interfaces: Calling a System Routine defines the use of these registers, as listed in Table 10–2.

Using HP Fortran in the Common Language Environment 10–21

R26

R27

R28

R29

R30

R31

Table 10–2 OpenVMS Alpha Register Usage

Register Use

R2-R15

R16-R21

R22-R24

R25

F0, F1

F2-F9

F10-F15

F16-F21

F22-F30

F31

Function value return registers; also see F0, F1

Conventional scratch register

Conventional saved registers

Argument registers (one register per argument, additional arguments are placed on the stack)

Conventional scratch registers

Argument information (AI); contains argument count and argument type

Return address (RA) register

Procedure value (PV) register

Volatile scratch register

Frame pointer (FP)

Stack pointer (SP)

Read As Zero/Sink (RZ) register

Program counter (PC), a special register that addresses the instruction stream, which is not accessible as an integer register

Function value return registers (F1 is used for the imaginary part of COMPLEX)

Conventional saved registers

Conventional scratch registers

Argument registers (one per argument, additional arguments are placed on the stack)

Conventional scratch registers

Read As Zero/Sink (RZ) register

A stack is defined as a LIFO (last-in/first-out) temporary storage area that the system allocates for every user process.

Each time you call a routine, the system places information on the stack in the form of procedure context structures, as described in the HP OpenVMS Calling

Standard.

10–22 Using HP Fortran in the Common Language Environment

10.5.2 Return Values of Procedures

A procedure is an HP Fortran subprogram that performs one or more computations for other programs. Procedures can be either functions or subroutines. Both functions and subroutines can return values by storing them in variables specified in the argument list or in common blocks.

A function, unlike a subroutine, can also return a value to the calling program by assigning the value to the function’s name. The method that function procedures use to return values depends on the data type of the value, as summarized in Table 10–3.

Table 10–3 OpenVMS Alpha Function Return Values

Data Type n

Logical

Integer o

Return Method

REAL (KIND=4)

REAL (KIND=8)

REAL (KIND=16)

COMPLEX (KIND=4)

(COMPLEX*8)

COMPLEX (KIND=8)

(COMPLEX*16)

COMPLEX (KIND=16)

(COMPLEX*32)

F0 and F1

F0 (real part), F1 (imaginary part)

Character

Pointers

Assumed-shape arrays,

Deferred-shape arrays

In addition to the arguments, an entry is added to the beginning of the argument list. This additional entry contains the address of the character string descriptor. At run time, before the call, the calling program allocates enough storage to contain the result and places the storage address in the descriptor.

R0 contains the address of the array descriptor (see

Section 10.2.6).

R0 contains the address of the array descriptor (see

Section 10.2.5).

Using HP Fortran in the Common Language Environment 10–23

For More Information:

• On HP Fortran array descriptors, see Section 10.2.7.

• On defining and invoking subprograms, see the HP Fortran for OpenVMS

Language Reference Manual.

10.5.3 Argument Lists

Use an argument list to pass information to a routine and receive results.

The HP OpenVMS Calling Standard defines an argument list as an argument

item sequence, consisting of the first six arguments occupying six integer and six floating-point registers (R16-R21 and F16-F21), with additional arguments placed on the stack. The argument information is contained in R25 (AI register). The stack pointer is contained in R30. For more details on argument lists, see the HP OpenVMS Calling Standard.

Memory for HP Fortran argument lists and for OpenVMS Alpha descriptors is allocated dynamically on the stack.

OpenVMS Alpha descriptors are generated from the use of the %DESCR function or by passing CHARACTER data, Fortran 90 pointers, and certain types of arrays (see Section 10.2.7).

Omitted arguments—for example, CALL X(A, ,B)—are represented by an argument passed by value that has a value of zero. This is an HP extension to the Fortran 90 standard.

Fortran optional arguments (OPTIONAL attribute) are also represented by an argument passed by value that has a value of zero.

For More Information:

On using Fortran language standards to specify arguments, see the HP Fortran

for OpenVMS Language Reference Manual.

10.6 OpenVMS System Routines

System routines are OpenVMS routines that perform common tasks, such as finding the square root of a number or allocating virtual memory. You can call any system routine from your program, provided that HP Fortran supports the data structures required to call the routine (in a FORSYSDEF library module) or you define them yourself.

The system routines used most often are OpenVMS Run-Time Library routines and system services. System routines are documented in detail in the VMS

Run-Time Library Routines Volume and the HP OpenVMS System Services

Reference Manual.

10–24 Using HP Fortran in the Common Language Environment

10.6.1 OpenVMS Run-Time Library Routines

The OpenVMS Run-Time Library provides commonly-used routines that perform a wide variety of functions. These routines are grouped according to the types of tasks they perform, and each group has a prefix that identifies those routines as members of a particular OpenVMS Run-Time Library facility.

Table 10–4 lists all of the language-independent Run-Time Library facility prefixes and the types of tasks each facility performs.

Table 10–4 Run-Time Library Facilities

Facility Prefix Types of Tasks Performed

CVT$

DTK$

LIB$

Library routines that handle floating-point data conversion

DECtalk routines that are used to control HP’s DECtalk device

Library routines that:

Obtain records from devices

Manipulate strings

Convert data types for I/O

Allocate resources

Obtain system information

Signal exceptions

Establish condition handlers

Enable detection of hardware exceptions

Process cross-reference data

MATH$

OTS$

PPL$

SMG$

STR$

Mathematics routines that perform arithmetic, algebraic, and trigonometric calculations

General-purpose routines that perform such tasks as data type conversions as part of a compiler’s generated code

Parallel processing routines that help you implement concurrent programs on single-CPU and multiprocessor systems

Screen-management routines that are used in designing, composing, and keeping track of complex images on a video screen

String manipulation routines that perform such tasks as searching for substrings, concatenating strings, and prefixing and appending strings

10.6.2 OpenVMS System Services Routines

System services are system routines that perform a variety of tasks, such as controlling processes, communicating among processes, and coordinating I/O.

Using HP Fortran in the Common Language Environment 10–25

Unlike the OpenVMS Run-Time Library routines, which are divided into groups by facility, all system services share the same facility prefix (SYS$).

However, these services are logically divided into groups that perform similar tasks. Table 10–5 describes these groups.

Table 10–5 System Services

Group Types of Tasks Performed

AST

Change Mode

Condition Handling

Event Flag

Input/Output

Lock Management

Logical Names

Memory Management

Process Control

Process Information

Security

Timer and Time

Conversion

Allows processes to control the handling of ASTs

Changes the access mode of particular routines

Designates condition handlers for special purposes

Clears, sets, reads, and waits for event flags, and associates with event flag clusters

Performs I/O directly, without going through OpenVMS

RMS

Enables processes to coordinate access to shareable system resources

Provides methods of accessing and maintaining pairs of character string logical names and equivalence names

Increases or decreases available virtual memory, controls paging and swapping, and creates and accesses shareable files of code or data

Creates, deletes, and controls execution of processes

Returns information about processes

Enhances the security of OpenVMS systems

Schedules events, and obtains and formats binary time values

10.7 Calling Routines: General Considerations

The basic steps for calling routines are the same whether you are calling a routine written in HP Fortran, a routine written in some other OpenVMS language, a system service, or an HP Fortran RTL routine.

To call a subroutine, use the CALL statement.

To call a function, reference the function name in an expression or as an argument in another routine call.

10–26 Using HP Fortran in the Common Language Environment

In any case, you must specify the name of the routine being called and all nonoptional arguments required for that routine. Make sure the data types and passing mechanisms for the actual arguments you are passing coincide with those declared in the routine. (See Table 10–6 for information on OpenVMS data types or OpenVMS Programming Interfaces: Calling a System Routine for data types needed for mixed language programming.)

If you do not want to specify a value for a required parameter, you can pass a null argument by inserting a comma ( , ) as a placeholder in the argument list. If the routine requires any passing mechanism other than the default, you must specify the passing mechanism in the CALL statement or the function call.

Example 10–3 illustrates calling an OpenVMS RTL LIB$ routine. This example uses the LIB$GET_VM RTL routine and the Compaq Fortran 77

POINTER statement to allocate memory for an array, and uses HP extensions

(POINTER statement and LIB$ routine) to allocate virtual memory.

Example 10–3 Use of LIB$GET_VM and POINTER

! Program accepts an integer and displays square root values

INTEGER (KIND=4) N

READ (5,*) N

CALL MAT(N)

END

! Request typed integer value

! Subroutine MAT uses the typed integer value to display the square

! root values of numbers from 1 to N (the typed number)

SUBROUTINE MAT(N)

REAL I(1000)

INTEGER SIZE,STATUS

POINTER (P,I)

! Fixed 1000 dimension allows bounds checking

! Compaq Fortran 77 POINTER statement establishes

! P as the pointer and array variable I as the

! pointee. P will receive memory base address

! from LIB$GET_VM.

SIZE=SIZEOF(I(1)) * N ! Array I contains values calculated in loop below.

! Intrinsic SIZEOF returns size of memory

! to allocate.

STATUS = LIB$GET_VM(SIZE,P) ! Allocate memory

IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

(continued on next page)

Using HP Fortran in the Common Language Environment 10–27

Example 10–3 (Cont.) Use of LIB$GET_VM and POINTER

DO J=1,N

I(J) = SQRT(FLOAT(J)) ! Intrinsic FLOAT converts integer to REAL.

ENDDO

TYPE *, (I(J),J=1,N) ! Display calculated values

STATUS = LIB$FREE_VM(SIZE,P) ! Deallocate memory

IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

END SUBROUTINE MAT

The following commands show how to compile, link, and run the program and how it displays the square root of numbers from 1 to 4 during execution:

$ FORTRAN SQUARE_ROOT

$ LINK SQUARE_ROOT

$ RUN SQUARE_ROOT

1.000000

1.414214

1.732051

2.000000

The call to LIB$GET_VM as a function reference allocates memory and returns the starting address in variable P. The return status (variable STATUS) is tested to determine whether an error should be signaled using a subroutine call to LIB$SIGNAL, passing the value of the variable status (not its address) using the %VAL built-in function.

For More Information:

• On intrinsic procedures (such as FLOAT, SQRT, and SIZEOF) and the HP

Fortran language, see the HP Fortran for OpenVMS Language Reference

Manual.

• On the %VAL built-in function, see Section 10.3.3.

• On an example of memory allocation using Fortran 90 standard-conforming allocatable arrays, see the HP Fortran for OpenVMS Language Reference

Manual.

10.8 Calling OpenVMS System Services

You can invoke system services in an HP Fortran program with a function reference or a subroutine CALL statement that specifies the system service you want to use. To specify a system service, use the form:

SYS$service-name(arg,...,arg)

10–28 Using HP Fortran in the Common Language Environment

You pass arguments to the system services according to the requirements of the particular service you are calling; the service may require an immediate value, an address, the address of a descriptor, or the address of a data structure.

Section 10.8.4 describes the HP Fortran syntax rules for each of these cases.

See the HP OpenVMS System Services Reference Manual for a full definition of individual services.

The basic steps for calling system services are the same as those for calling any external routine. However, when calling system services (or Run-Time

Library routines), additional information is often required. The sections that follow describe these requirements.

10.8.1 Obtaining Values for System Symbols

OpenVMS uses symbolic names to identify the following values or codes for system services:

• Return status values are used for testing the success of system service calls.

• Condition values are used for error recovery procedures (see Chapter 14).

• Function codes are the symbolic values used as input arguments to system service calls.

The values chosen determine the specific action performed by the service.

The HP OpenVMS System Services Reference Manual describes the symbols that are used with each system service. The HP OpenVMS I/O User’s

Reference Manual describes the symbols that are used with I/O-related services.

The HP Fortran symbolic definition library FORSYSDEF contains HP Fortran source definitions for related groups of system symbols. Each related group of system symbols is stored in a separate text library module; for example, the library module $IODEF in FORSYSDEF contains PARAMETER statements that define the I/O function codes.

The library modules in FORSYSDEF correspond to the symbolic definition macros that OpenVMS MACRO programmers use to define system symbols.

The library modules have the same names as the macros and contain HP

Fortran source code, which is functionally equivalent to the MACRO source code. To determine whether you need to include other symbol definitions for the system service you want to use, refer to the documentation for that particular system service. If the documentation states that values are defined in a macro, you must include those symbol definitions in your program.

Using HP Fortran in the Common Language Environment 10–29

For example, the description for the flags argument in the SYS$MGBLSC (Map

Global Section) system service states that ‘‘Symbolic names for the flag bits are defined by the $SECDEF macro.’’ Therefore, when you call SYS$MGBLSC, you must include the definitions provided in the $SECDEF macro.

Library module $SYSSRVNAM in FORSYSDEF contains declarations for all system-service names. It contains the necessary INTEGER and EXTERNAL declarations for the system-service names. (The library module, once extracted from FORSYSDEF.TLB, also contains comments describing the arguments for each of the system services.) Also, library module $SSDEF contains systemservice return status codes and is generally required whenever you access any of the services.

The library modules in FORSYSDEF contain definitions for constants, bit masks, and data structures. See Section 10.8.4.4 for a description of how to create data structure arguments in HP Fortran. Refer to Appendix E for a list of library modules that are in FORSYSDEF.

You can access the library modules in the FORSYSDEF library with the

INCLUDE statement, using the following format:

INCLUDE ’(library-module-name)’

The notation library-module-name represents the name of a library module contained in FORSYSDEF. The library FORSYSDEF is searched if the specified library module was not found in a previously searched library.

10.8.2 Calling System Services by Function Reference

In most cases, you should check the return status after calling a system service. Therefore, you should invoke system services by function reference rather than by issuing a call to a subroutine.

For example:

INCLUDE ’($SSDEF)’

INCLUDE ’($SYSSRVNAM)’

INTEGER (KIND=2) CHANNEL

MBX_STATUS = SYS$CREMBX(,CHANNEL,,,,,’MAILBOX’)

IF (MBX_STATUS .NE. SS$_NORMAL) GO TO 100

In this example, the system service referenced is the Create Mailbox system service. An INTEGER (KIND=2) variable (CHANNEL) is declared to receive the channel number.

10–30 Using HP Fortran in the Common Language Environment

The function reference allows a return status value to be stored in the variable

MBX_STATUS, which can then be checked for correct completion on return.

If the function’s return status is not SS$_NORMAL, failure is indicated and control is transferred to statement 100. At that point, some form of error processing can be undertaken.

You can also test the return status of a system service as a logical value.

The status codes are defined so that when they are tested as logical values, successful codes have the value true and error codes have the value false. The last line in the preceding example could then be changed to the following:

IF (.NOT. MBX_STATUS) GO TO 100

Refer to the HP OpenVMS System Services Reference Manual for information concerning return status codes. The return status codes are included in the description of each system service.

10.8.3 Calling System Services as Subroutines

Subroutine calls to system services are made like other subroutine calls.

For example, to call the Create Mailbox system service, issue a call to

SYS$CREMBX, passing the appropriate arguments to it, as follows:

CALL SYS$CREMBX(,CHANNEL,,,,,’MAILBOX’)

This call corresponds to the function reference described in Section 10.8.2.

The main difference is that the status code returned by the system service is not tested. For this reason, you should avoid this method and use a function reference when calling system services whenever the service could fail for any reason.

10.8.4 Passing Arguments to System Services

The description of each system service in the HP OpenVMS System Services

Reference Manual specifies the argument-passing method for each argument.

Four methods are supported:

• By immediate value

• By address: this is the HP Fortran default and is termed ‘‘by reference’’

• By descriptor: this is the HP Fortran default for CHARACTER arguments,

Fortran 90 pointers, and certain types of arrays (see Section 10.2.7)

• By data structure

These methods are discussed separately in Section 10.8.4.1 through

Section 10.8.4.4.

Using HP Fortran in the Common Language Environment 10–31

You can determine the arguments required by a system service from the service description in the HP OpenVMS System Services Reference Manual.

Each system service description indicates the service name, the number of arguments required, and the positional dependency of each argument.

Table 10–6 lists the HP Fortran declarations that you can use to pass any of the standard OpenVMS data types as arguments. OpenVMS data types are defined in OpenVMS Programming Interfaces: Calling a System Routine.

Instead of using record structure declarations for most standard OpenVMS data types, you can consider using derived-type structures if you use the

SEQUENCE statement and are careful of alignment. However, RMS control block structures must be declared as record structures (STRUCTURE statement).

Table 10–6 HP Fortran Implementation of OpenVMS Data Types

OpenVMS Data Type HP Fortran Declaration access_bit_names access_mode address address_range arg_list ast_procedure boolean byte_signed byte_unsigned

INTEGER (KIND=4) (2,32) or

STRUCTURE /access_bit_names/

INTEGER (KIND=4) access_name_len

INTEGER (KIND=4) access_name_buf

END STRUCTURE !access_bit_names

RECORD /access_bit_names/ my_names(32)

BYTE or INTEGER (KIND=1)

INTEGER (KIND=4)

INTEGER (KIND=4) (2) or

STRUCTURE /address_range/

INTEGER (KIND=4) low_address

INTEGER (KIND=4) high_address

END STRUCTURE

INTEGER (KIND=4)( n )

EXTERNAL

LOGICAL (KIND=4)

BYTE or INTEGER (KIND=1)

Unsigned data types are not directly supported by HP Fortran. However, in most cases you can substitute the signed equivalent, provided you do not exceed the range of the signed data structure.

(continued on next page)

10–32 Using HP Fortran in the Common Language Environment

Table 10–6 (Cont.) HP Fortran Implementation of OpenVMS Data Types

OpenVMS Data Type channel char_string complex_number cond_value context date_time device_name ef_cluster_name ef_number exit_handler_block

HP Fortran Declaration

INTEGER (KIND=2)

CHARACTER (LEN=n)

COMPLEX (KIND=4) 3

COMPLEX (KIND=8) 3

INTEGER (KIND=4)

INTEGER (KIND=8)

CHARACTER (LEN=n)

INTEGER (KIND=4)

STRUCTURE /exhblock/

INTEGER (KIND=4) flink

INTEGER (KIND=4) exit_handler_addr

BYTE( 3 ) %FILL

BYTE arg_count

INTEGER (KIND=4) cond_value

! .

! .(optional arguments . . .

! . one argument per longword)

END STRUCTURE !cntrlblk

fab file_protection floating_point function_code identifier

RECORD /exhblock/ myexh_block

INCLUDE ’($FABDEF)’

RECORD /FABDEF/ myfab

INTEGER (KIND=4)

REAL (KIND=4)

REAL (KIND=8)

DOUBLE PRECISION

REAL (KIND=16) 3

INTEGER (KIND=4)

Where n can range from 1 to 65535.

The format used by floating-point (KIND=4) and (KIND=8) data in memory is determined by the

FORTRAN command qualifier /FLOAT.

(continued on next page)

Using HP Fortran in the Common Language Environment 10–33

Table 10–6 (Cont.) HP Fortran Implementation of OpenVMS Data Types

OpenVMS Data Type invo_context_blk invo_handle io_status_block

HP Fortran Declaration

INCLUDE ’($LIBICB)’

RECORD /INVO_CONTEXT_BLK/ invo_context_blk

INTEGER (KIND=4)

STRUCTURE /iosb/

INTEGER (KIND=2) iostat, ! return status

INTEGER (KIND=2) term_offset, ! Loc. of terminator

INTEGER (KIND=2) terminator, ! terminator value

INTEGER (KIND=2) term_size ! terminator size

END STRUCTURE item_list_2 item_list_3

RECORD /iosb/ my_iosb

STRUCTURE /itmlst/

UNION

MAP

INTEGER (KIND=2) buflen,code

INTEGER (KIND=4) bufadr

END MAP

MAP

INTEGER (KIND=4) end_list /0/

END MAP

END UNION

END STRUCTURE !itmlst

RECORD /itmlst/ my_itmlst_2( n )

(Allocate n records, where n is the number item codes plus an extra element for the end-of-list item.)

STRUCTURE /itmlst/

UNION

MAP

INTEGER (KIND=2) buflen,code

INTEGER (KIND=4) bufadr,retlenadr

END MAP

MAP

INTEGER (KIND=4) end_list /0/

END MAP

END UNION

END STRUCTURE !itmlst

RECORD /itmlst/ my_itmlst_3( n )

(Allocate n records where n is the number item codes plus an extra element for the end-of-list item.)

(continued on next page)

10–34 Using HP Fortran in the Common Language Environment

Table 10–6 (Cont.) HP Fortran Implementation of OpenVMS Data Types

OpenVMS Data Type item_list_pair

HP Fortran Declaration

STRUCTURE /itmlist_pair/

UNION

MAP

INTEGER (KIND=4) code

INTEGER (KIND=4) value

END MAP

MAP

INTEGER (KIND=4) end_list /0/

END MAP

END UNION

END STRUCTURE !itmlst_pair

item_quota_list lock_id lock_status_block lock_value_block logical_name longword_signed longword_unsigned

RECORD /itmlst_pair/ my_itmlst_pair( n )

(Allocate n records where n is the number item codes plus an extra element for the end-of-list item.)

STRUCTURE /item_quota_list/

MAP

BYTE quota_name

INTEGER (KIND=4) quota_value

END MAP

MAP

BYTE end_quota_list

END MAP

END STRUCTURE !item_quota_list

INTEGER (KIND=4)

STRUCTURE/lksb/

INTEGER (KIND=2) cond_value

INTEGER (KIND=2) unused

INTEGER (KIND=4) lock_id

BYTE(16)

END STRUCTURE !lksb

RECORD /lksb/ my_lksb

BYTE(16)

CHARACTER (LEN=n)

INTEGER (KIND=4)

Unsigned data types are not directly supported by HP Fortran. However, in most cases you can substitute the signed equivalent, provided you do not exceed the range of the signed data structure.

(continued on next page)

Using HP Fortran in the Common Language Environment 10–35

Table 10–6 (Cont.) HP Fortran Implementation of OpenVMS Data Types

OpenVMS Data Type mask_byte mask_longword mask_quadword mask_word mechanism_args null_arg octaword_signed octaword_unsigned page_protection procedure process_id process_name quadword_signed quadword_unsigned rights_holder

HP Fortran Declaration

INTEGER (KIND=1) ! (or BYTE)

INTEGER (KIND=4)

INTEGER (KIND=8)

INTEGER (KIND=2)

INCLUDE ’($CHFDEF)’

RECORD /CHFDEF2/ mechargs

! (For more information, see Section 14.6.)

%VAL( 0 ) ! (or an unspecified optional argument)

INTEGER (KIND=4)( 4 )

INTEGER (KIND=4)( 4 ) 1

INTEGER (KIND=4)

CHARACTER (LEN=n)

INTEGER (KIND=8)

STRUCTURE /rights_holder/

INTEGER (KIND=4) rights_id

INTEGER (KIND=4) rights_mask

END STRUCTURE !rights_holder

rights_id rab section_id section_name system_access_id time_name transaction_id

RECORD /rights_holder/ my_rights_holder

INTEGER (KIND=4)

INCLUDE ’($RABDEF)’

RECORD /RABDEF/ myrab

INTEGER (KIND=4)( 2 ) or INTEGER (KIND=8)

CHARACTER (LEN=n)

INTEGER (KIND=4)( 2 ) or INTEGER (KIND=8)

CHARACTER (LEN=23)

INTEGER (KIND=4)(4)

Unsigned data types are not directly supported by HP Fortran. However, in most cases you can substitute the signed equivalent, provided you do not exceed the range of the signed data structure.

(continued on next page)

10–36 Using HP Fortran in the Common Language Environment

Table 10–6 (Cont.) HP Fortran Implementation of OpenVMS Data Types

OpenVMS Data Type uic user_arg varying_arg vector_byte_signed vector_byte_unsigned vector_longword_signed vector_longword_unsigned vector_quadword_signed vector_quadword_unsigned vector_word_signed vector_word_unsigned word_signed word_unsigned

HP Fortran Declaration

INTEGER (KIND=4)

Any longword quantity

Any appropriate type

BYTE( n )

BYTE( n ) 1

INTEGER(KIND=4) ( n )

INTEGER(KIND=4) ( n ) 1

INTEGER(KIND=8) ( n )

INTEGER (KIND=8) ( n )

INTEGER (KIND=2) ( n )

INTEGER (KIND=2) ( n ) 1

Unsigned data types are not directly supported by HP Fortran. However, in most cases you can substitute the signed equivalent, provided you do not exceed the range of the signed data structure.

Many arguments to system services are optional. However, if you omit an optional argument, you must include a comma ( , ) to indicate the absence of that argument. For example, the SYS$TRNLNM system service takes five arguments. If you omit the first and the last two arguments, you must include commas to indicate their existence, as follows:

ISTAT = SYS$TRNLNM(,’LNM$FILE_DEV’,’LOGNAM’,,)

An invalid reference results if you specify the arguments as follows:

ISTAT = SYS$TRNLNM(’LOGNAM’,LENGTH,BUFFA)

This reference provides only three arguments, not the required five.

When you omit an optional argument by including an extra comma, the compiler supplies a default value of zero (passed by immediate value).

Using HP Fortran in the Common Language Environment 10–37

10.8.4.1 Immediate Value Arguments

Value arguments are typically used when the description of the system service specifies that the argument is a ‘‘number,’’ ‘‘mask,’’ ‘‘mode,’’ ‘‘value,’’ ‘‘code,’’ or ‘‘indicator.’’ You must use either the cDEC$ ATTRIBUTES VALUE (see

Section 10.4.2.3) or the %VAL built-in function (see Section 10.3.3) whenever this method is required.

Immediate value arguments are used for input arguments only.

10.8.4.2 Address Arguments

Use address arguments when the description of the system service specifies that the argument is ‘‘the address of.’’ (However, refer to Section 10.8.4.3 to determine what to do when ‘‘the address of a descriptor’’ is specified.) In HP

Fortran, this argument-passing method is called ‘‘by reference.’’

Because this method is the HP Fortran default for passing numeric arguments, you need to specify the cDEC$ ATTRIBUTES REFERENCE directive (see

Section 10.4.2.3) or the %REF built-in function only when the data type of the argument is character.

The argument description also gives the hardware data type required.

For arguments described as ‘‘address of an entry mask’’ or ‘‘address of a routine,’’ declare the argument value as an external procedure. For example, if a system service requires the address of a routine and you want to specify the routine HANDLER3, include the following statement in the declarations portion of your program:

EXTERNAL HANDLER3

This specification defines the address of the routine for use as an input argument.

Address arguments are used for both input and output:

• For input arguments that refer to byte, word, longword, or quadword values, you can specify either constants or variables. If you specify a variable, you must declare it to be equal to or longer than the data type required. Table 10–7 lists the variable data type requirements for both input and output arguments.

• For output arguments you must declare a variable of exactly the length required to avoid including extraneous data. If, for example, the system returns a byte value in a word-length variable, the leftmost eight bits of the variable are not overwritten on output. The variable, therefore, might not contain the data you expect.

10–38 Using HP Fortran in the Common Language Environment

To store output produced by system services, you must allocate sufficient space to contain the output. You make this allocation by declaring variables of the proper size. For an illustration, refer to the Translate Logical Name system service example in Section 10.8.4.3. This service returns the length of the equivalent name string as a 2-byte value.

If the output is a quadword value, you must declare a variable of the proper dimensions. For example, to use the Get Time system service

(SYS$GETTIM), which returns the time as a quadword binary value, declare the following:

INCLUDE ’($SYSSRVNAM)’

INTEGER (KIND=8) SYSTIM

ISTAT = SYS$GETTIM(SYSTIM)

The type declaration INTEGER (KIND=8) SYSTIM establishes a variable consisting of one quadword, which is then used to store the time value.

Table 10–7 Variable Data Type Requirements

OpenVMS Type Required

Byte

Word

Longword

Quadword

Indicator

Character string descriptor

Entry mask or routine

Input Argument Declaration

BYTE, INTEGER (KIND=1),

INTEGER (KIND=2), INTEGER

(KIND=4)

INTEGER (KIND=2), INTEGER

(KIND=4)

INTEGER (KIND=4)

INTEGER (KIND=8) or INTEGER

(KIND=4) (2) or properly dimensioned array

LOGICAL

CHARACTER (LEN=n)

EXTERNAL

Output Argument

Declaration

BYTE, INTEGER

(KIND=1)

INTEGER (KIND=2)

INTEGER (KIND=4)

INTEGER (KIND=8) or

INTEGER (KIND=4) (2) or properly dimensioned array

CHARACTER (LEN=n)

Using HP Fortran in the Common Language Environment 10–39

10.8.4.3 Descriptor Arguments

Descriptor arguments are used for input and output of character strings. Use a descriptor argument when the argument description specifies ‘‘address of a descriptor.’’ Because this method is the HP Fortran default for character arguments, you need to specify the %DESCR built-in function only when the data type of the argument is not character.

On input, a character constant, variable, array element, or expression is passed to the system service by descriptor. On output, two items are needed:

• The character variable or array element to hold the output string

• An INTEGER (KIND=2) variable that is set to the actual length of the output string

In the following example of the Translate Logical Name system service

(SYS$TRNLNM), the logical name LOGNAM is translated to its associated name or file specification. The output string and string length are stored in the variables EQV_BUFFER and W_NAMELEN, respectively:

INCLUDE ’($LNMDEF)’

INCLUDE ’($SYSSRVNAM)’

STRUCTURE /LIST/

INTEGER (KIND=2) BUF_LEN/255/

INTEGER (KIND=2) ITEM_CODE/LNM$_STRING/

INTEGER (KIND=4) TRANS_LOG

INTEGER (KIND=4) TRANS_LEN

INTEGER (KIND=4) END_ENTRY/0/

END STRUCTURE !LIST

CHARACTER (LEN=255) EQV_BUFFER

INTEGER (KIND=2) W_NAMELEN

RECORD/LIST/ ITEM_LIST

ITEM_LIST.TRANS_LOG = %LOC(EQV_BUFFER)

ITEM_LIST.TRANS_LEN = %LOC(W_NAMELEN)

ISTAT = SYS$TRNLNM(, ’LNM$FILE_DEV’, ’FOR$SRC’, ,ITEM_LIST)

IF (ISTAT) PRINT *, EQV_BUFFER(:W_NAMELEN)

END

10–40 Using HP Fortran in the Common Language Environment

10.8.4.4 Data Structure Arguments

Data structure arguments are used when the argument description specifies

‘‘address of a list,’’ ‘‘address of a control block,’’ or ‘‘address of a vector.’’ The data structures required for these arguments are constructed in HP Fortran with structure declaration blocks and the RECORD statement. The storage declared by a RECORD statement is allocated in exactly the order given in the structure declaration, with no space between adjacent items. For example, the item list required for the SYS$GETJPI (or SYS$GETJPIW) system service requires a sequence of items of two words and two longwords each. By declaring each item as part of a structure, you ensure that the fields and items are allocated contiguously:

STRUCTURE /GETJPI_STR/

INTEGER (KIND=2) BUFLEN, ITMCOD

INTEGER (KIND=4) BUFADR, RETLEN

END STRUCTURE

...

RECORD /GETJPI_STR/ LIST(5)

If a given field is provided as input to the system service, the calling program must fill the field before the system service is called. You can accomplish this with data initialization (for fields with values that are known at compile time) and with assignment statements (for fields that must be computed).

When the data structure description requires a field that must be filled with an address value, use the %LOC built-in function to generate the desired address

(see Section 10.3.2). When the description requires a field that must be filled with a symbolic value (system-service function code), you can define the value of the symbol by the method described in Section 10.8.1.

10.8.4.5 Examples of Passing Arguments

Example 10–4 shows a complete subroutine that uses a data structure argument to the SYS$GETJPIW system service.

Example 10–4 Subroutine Using a Data Structure Argument

Subroutine to obtain absolute and incremental values of process parameters:

CPU time, Buffered I/O count, Direct I/O count, Page faults.

SUBROUTINE PROCESS_INFO(ABS_VALUES, INCR_VALUES)

Declare the arguments and working storage

INTEGER (KIND=4) ABS_VALUES(4), INCR_VALUES(4), LCL_VALUES(4)

INTEGER (KIND=4) STATUS, I

(continued on next page)

Using HP Fortran in the Common Language Environment 10–41

Example 10–4 (Cont.) Subroutine Using a Data Structure Argument

Declare the SYS$GETJPIW item list data structure in a structure declaration

STRUCTURE /GETJPI_STR/

INTEGER (KIND=2) BUFLEN /4/, ITMCOD /0/

INTEGER (KIND=4) BUFADR, RETLEN /0/

END STRUCTURE

Create a record with the fields defined in the structure declaration

RECORD /GETJPI_STR/ LIST(5)

Declare the structure of an I/O Status Block

STRUCTURE /IOSB_STR/

INTEGER (KIND=4) STATUS, RESERVED

END STRUCTURE

Declare the I/O Status Block

RECORD /IOSB_STR/ IOSB

Assign all static values in the item list

LIST(1).ITMCOD = JPI$_CPUTIM

LIST(2).ITMCOD = JPI$_BUFIO

LIST(3).ITMCOD = JPI$_DIRIO

LIST(4).ITMCOD = JPI$_PAGEFLTS

Assign all item fields requiring addresses

LIST(1).BUFADR = %LOC(LCL_VALUES(1))

LIST(2).BUFADR = %LOC(LCL_VALUES(2))

LIST(3).BUFADR = %LOC(LCL_VALUES(3))

LIST(4).BUFADR = %LOC(LCL_VALUES(4))

STATUS = SYS$GETJPIW(,,,LIST,IOSB,,) ! Perform system service call

IF (STATUS) STATUS = IOSB.STATUS

IF (.NOT. STATUS) CALL EXIT (STATUS)

! Check completion status

Assign the new values to the arguments

DO I=1,4

INCR_VALUES(I) = LCL_VALUES(I) - ABS_VALUES(I)

ABS_VALUES(I) = LCL_VALUES(I)

END DO

RETURN

END SUBROUTINE PROCESS_INFO

10–42 Using HP Fortran in the Common Language Environment

Example 10–5 is an example of the typical use of an I/O system service. The program invokes SYS$QIOW to enable Ctrl/C trapping. When the program runs, it prints an informational message whenever it is interrupted by a

Ctrl/C, and then it continues execution.

Example 10–5 Ctrl/C Trapping Example

PROGRAM TRAPC

INCLUDE ’($SYSSRVNAM)’

INTEGER (KIND=2) TT_CHAN

COMMON TT_CHAN

CHARACTER (LEN=40) LINE

Assign the I/O channel.

If unsuccessful stop; otherwise

initialize the trap routine.

ISTAT = SYS$ASSIGN (’TT’,TT_CHAN,,)

IF (.NOT. ISTAT) CALL LIB$STOP(%VAL(ISTAT))

CALL ENABLE_CTRLC

Read a line of input and echo it !

10 READ (5,’(A)’,END=999) LINE

TYPE *, ’LINE READ: ’, LINE

GO TO 10

999 END

SUBROUTINE ENABLE_CTRLC

INTEGER (KIND=2) TT_CHAN

COMMON TT_CHAN

EXTERNAL CTRLC_ROUT

Include I/O symbols

INCLUDE ’($IODEF)’

INCLUDE ’($SYSSRVNAM)’

Enable Ctrl/C trapping and specify CTRLC_ROUT as routine to be called when Ctrl/C occurs

ISTAT = SYS$QIOW( ,%VAL(TT_CHAN), %VAL(IO$_SETMODE .OR. IO$M_CTRLCAST),&

,,,CTRLC_ROUT,,%VAL(3),,,)

IF (.NOT. ISTAT) CALL LIB$STOP(%VAL(ISTAT))

RETURN

END SUBROUTINE ENABLE_CTRLC

(continued on next page)

Using HP Fortran in the Common Language Environment 10–43

Example 10–5 (Cont.) Ctrl/C Trapping Example

SUBROUTINE CTRLC_ROUT

PRINT *, ’Ctrl/C pressed’

CALL ENABLE_CTRLC

RETURN

END SUBROUTINE CTRLC_ROUT

For more examples of calling system services and RTL routines, see

Appendix F and the HP Fortran Web site.

10.9 Calling Between Compaq Fortran 77 and HP Fortran

On OpenVMS Alpha systems, you can call a Compaq Fortran 77 subprogram from HP Fortran or call an HP Fortran subprogram from Compaq Fortran 77

(with very few exceptions). A Compaq Fortran 77 procedure and a HP Fortran procedure can also perform I/O to the same unit number.

10.9.1 Argument Passing and Function Return Values

The recommended rules for passing arguments and function return values between Compaq Fortran 77 and HP Fortran procedures are as follows:

• If possible, express the following HP Fortran features with the Compaq

Fortran 77 language:

Function references

CALL statements

Function definitions

Subroutine definitions

Avoid using HP Fortran language features not available in Compaq Fortran

77. Since HP Fortran is a superset of Compaq Fortran 77, specifying the procedure interface using the Compaq Fortran 77 language helps ensure that calls between the two languages will succeed.

• Not all data types in HP Fortran have equivalent Compaq Fortran 77 data types. The following HP Fortran features should not be used between

HP Fortran and Compaq Fortran 77 procedures, because they are not supported by Compaq Fortran 77:

Derived-type (user-defined) data, which has no equivalents in Compaq

Fortran 77.

10–44 Using HP Fortran in the Common Language Environment

HP Fortran record structures are supported by Compaq Fortran 77 and HP Fortran as an extension to the Fortran 90 standard. Thus, you can use Compaq Fortran 77 record structures in both HP Fortran and

Compaq Fortran 77.

HP Fortran data with the POINTER attribute, which has no equivalents in Compaq Fortran 77. The pointer data type supported by

Compaq Fortran 77 is not equivalent to Fortran 90 pointer data.

Because HP Fortran supports the pointer data type supported by

Compaq Fortran 77, you can use Compaq Fortran 77 pointer data types in both HP Fortran and Compaq Fortran 77. (In some cases, you can create Compaq Fortran 77 pointer data in an HP Fortran procedure using the %LOC function.)

HP Fortran arrays with the POINTER attribute are passed by array descriptor. A program written in Compaq Fortran 77 needs to interpret the array descriptor format generated by an HP Fortran array with the

POINTER attribute (see Section 10.2.7).

HP Fortran assumed-shape arrays.

HP Fortran assumed-shape arrays are passed by array descriptor. A program written in Compaq Fortran 77 needs to interpret the array descriptor format generated by an HP Fortran assumed-shape array

(see Section 10.2.7).

For more information on how HP Fortran handles arguments and function return values, see Section 10.2.4.

• Make sure the sizes of INTEGER, LOGICAL, REAL, and COMPLEX declarations match.

For example, HP Fortran declarations of REAL (KIND=4) and INTEGER

(KIND=4) match Compaq Fortran 77 declarations of REAL*4 and

INTEGER*4. For COMPLEX values, an HP Fortran declaration of

COMPLEX (KIND=4) matches a Compaq Fortran 77 declaration of

COMPLEX*8; COMPLEX (KIND=8) matches COMPLEX*16.

Your source programs may contain INTEGER, LOGICAL, REAL, or

COMPLEX declarations without a kind parameter (or size specifier).

In this case, when compiling the HP Fortran procedures (FORTRAN command) and Compaq Fortran 77 procedures (FORTRAN/OLDF77 command), either omit or specify the equivalent qualifiers for controlling the sizes of these declarations.

For more information on these qualifiers, see Section 2.3.26 for INTEGER and LOGICAL declarations, Section 2.3.37 for REAL and COMPLEX declarations, and Section 2.3.17 for DOUBLE PRECISION declarations.

Using HP Fortran in the Common Language Environment 10–45

• HP Fortran uses the same argument-passing conventions as Compaq

Fortran 77 on OpenVMS Alpha systems (see Section 10.2.4).

• You can return nearly all function return values from an HP Fortran function to a calling Compaq Fortran 77 routine, with the following exceptions:

You cannot return HP Fortran pointer data from HP Fortran to a

Compaq Fortran 77 calling routine.

You cannot return HP Fortran user-defined data types from an HP

Fortran function to a Compaq Fortran 77 calling routine.

Example 10–6 and Example 10–7 show passing an array from an HP Fortran program to a Compaq Fortran 77 subroutine that prints its value.

Example 10–6 shows the HP Fortran program (file ARRAY_TO_F77.F90).

It passes the same argument as a target and a pointer. In both cases, it is received by reference by the Compaq Fortran 77 subroutine as a target

(regular) argument. The interface block in Example 10–6 is not needed, but does allow data type checking.

Example 10–6 HP Fortran Program Calling a Compaq Fortran 77 Subroutine

! Pass arrays to f77 routine. File: ARRAY_TO_F77.F90

! This interface block is not required, but must agree

! with actual procedure. It can be used for type checking.

! Procedure interface block INTERFACE

SUBROUTINE MEG(A)

INTEGER :: A(3)

END SUBROUTINE

END INTERFACE

INTEGER, TARGET :: X(3)

INTEGER, POINTER :: XP(:)

X = (/ 1,2,3 /)

XP => X

CALL MEG(X)

CALL MEG(XP)

END

! Call f77 implicit interface subroutine twice.

10–46 Using HP Fortran in the Common Language Environment

Example 10–7 shows the Compaq Fortran 77 program called by the HP Fortran program (file ARRAY_F77.FOR).

Example 10–7 Compaq Fortran 77 Subroutine Called by an HP Fortran

Program

! Get array argument from F90. File: ARRAY_F77.FOR

SUBROUTINE MEG(A)

INTEGER A(3)

PRINT *,A

END

These files (shown in Example 10–6 and Example 10–7) might be compiled, linked, and run as follows:

$ FORTRAN ARRAY_TO_F77.F90

$ FORTRAN /OLD_F77 ARRAY_F77.FOR

$ LINK/EXECUTABLE=ARRAY_TO_F77 ARRAY_TO_F77, ARRAY_F77

$ RUN ARRAY_TO_F77

In Example 10–6, because array A is not defined as a pointer in the interface block, the HP Fortran pointer variable XP is passed as target data by reference

(address of the target data).

However, if the interface to the dummy argument had the POINTER attribute, the variable XP would be passed by descriptor. This descriptor would not work with the Compaq Fortran 77 program shown in Example 10–7.

For More Information:

• On how HP Fortran handles arguments and function return values, see

Section 10.2.4.

• On explicit interfaces, see the HP Fortran for OpenVMS Language

Reference Manual.

• On compatibility between the HP Fortran and Compaq Fortran 77 languages, see Appendix B.

• On use association, see the HP Fortran for OpenVMS Language Reference

Manual.

• On other aspects of the HP Fortran language, see the HP Fortran for

OpenVMS Language Reference Manual.

Using HP Fortran in the Common Language Environment 10–47

• On calling the Fortran 77 compiler with the /OLD_F77 compiler option, see

Section 2.3.34.

10.9.2 Using Data Items in Common Blocks

To make global data available across HP Fortran and Compaq Fortran 77 procedures, use common blocks.

Common blocks are supported by both HP Fortran and Compaq Fortran 77, but modules are not supported by Compaq Fortran 77. Some suggestions about using common blocks follow:

• Use the same COMMON statement to ensure that the data items match in order, type, and size.

If multiple HP Fortran procedures will use the same common block, declare the data in a module and reference that module with a USE statement where needed.

If Compaq Fortran 77 procedures use the same common block as the HP

Fortran procedures and the common block is declared in a module, consider modifying the Compaq Fortran 77 source code as follows:

Replace the common block declaration with the appropriate USE statement.

Recompile the Compaq Fortran 77 source code with the FORTRAN command (HP Fortran compiler).

• Specify the same alignment characteristics with the /ALIGNMENT qualifier when compiling both HP Fortran procedures (FORTRAN command) and Compaq Fortran 77 procedures (FORTRAN/OLDF77 command).

When compiling the source files with both the FORTRAN and

FORTRAN/OLDF77 commands, consistently use the /ALIGN=COMMONS qualifier. This naturally aligns data items in a common block and ensures consistent format of the common block.

• Make sure the sizes of INTEGER, LOGICAL, REAL, and COMPLEX declarations match.

For example, HP Fortran declarations of REAL (KIND=4) and INTEGER

(KIND=4) match Compaq Fortran 77 declarations of REAL*4 and

INTEGER*4. For COMPLEX values, an HP Fortran declaration of

COMPLEX (KIND=4) matches a Compaq Fortran 77 declaration of

COMPLEX*8; COMPLEX (KIND=8) matches COMPLEX*16.

10–48 Using HP Fortran in the Common Language Environment

Your source programs may contain INTEGER, LOGICAL, REAL, or

COMPLEX declarations without a kind parameter or size specifier. In this case, either omit or specify the same qualifiers that control the sizes of these declarations when compiling the procedures with multiple commands

(same rules as Section 10.9.1).

10.9.3 I/O to the Same Unit Number

HP Fortran and Compaq Fortran 77 share the same run-time system, so you can perform I/O to the same unit number by HP Fortran and Compaq Fortran

77 procedures. For instance, a HP Fortran main program can open the file, a Compaq Fortran 77 function can issue READ or WRITE statements to the same unit, and the HP Fortran main program can close the file.

For More Information:

• On the HP Fortran language, see the HP Fortran for OpenVMS Language

Reference Manual.

• On passing arguments, function return values, and the contents of registers on OpenVMS systems, see the HP OpenVMS Calling Standard.

• On HP Fortran intrinsic data types, see Chapter 8.

• On HP Fortran I/O, see Chapter 6.

10.10 Calling Between HP Fortran and HP C

Before creating a mixed-language program that contains procedures written in

HP Fortran and C, you need to know how to:

• Compile and link the program

• Use equivalent data arguments passed between the two languages

10.10.1 Compiling and Linking Files

Use the FORTRAN command to compile HP Fortran source files and CC to compile C source files. Link the object files using a LINK command.

For example, the following FORTRAN command compiles the HP Fortran main program EX1.F90 and the called C function UPEN.C:

$ FORTRAN EX1.F90

$ CC UPEN.C

The following LINK command creates the executable program:

$ LINK EX1, UPEN

Using HP Fortran in the Common Language Environment 10–49

10.10.2 Procedures and External Names

When designing a program that will use HP Fortran and C, be aware of the following general rules and available HP Fortran capabilities:

• The OpenVMS Linker only allows one main program. Declare either the

HP Fortran or the C program, but not both, as the main program.

In HP Fortran, you can declare a main program:

With the PROGRAM and END PROGRAM statements

With an END statement

To create a HP Fortran subprogram, declare the subprogram with such statements as FUNCTION and END FUNCTION or SUBROUTINE and

END SUBROUTINE.

In C, you need to use a main( ) declaration for a main program. To create a C function (subprogram), declare the appropriate function name and omit the main( ) declaration.

• External names in C and HP Fortran are usually converted to uppercase.

Because both HP Fortran and C make external names uppercase by default, external names should be uppercase unless requested otherwise.

Consistently use the CC qualifier /NAMES and the FORTRAN qualifier

/NAMES to control the way C and HP Fortran treat external names (see

Section 2.3.32).

• You can consider using the following HP Fortran facility provided to simplify the HP Fortran and C language interface.

You can use the cDEC$ ALIAS and cDEC$ ATTRIBUTES directives to specify alternative names for routines and change default passing mechanisms (see Section 10.4).

10.10.3 Invoking a C Function from HP Fortran

You can use a function reference or a CALL statement to invoke a C function from an HP Fortran main or subprogram.

If a value will be returned, use a function reference:

C Function Declaration

data-type calc(argument-list)

{

...

} ;

HP Fortran Function Invocation

EXTERNAL CALC

data-type :: CALC, variable-name

...

variable-name=CALC(argument-list)

...

10–50 Using HP Fortran in the Common Language Environment

If no value is returned, use a void return value and a CALL statement:

C Function Declaration void calc(argument-list)

{

...

} ;

HP Fortran Subroutine Invocation

EXTERNAL CALC

...

CALL CALC(argument-list)

10.10.4 Invoking an HP Fortran Function or Subroutine from C

A C main program or function can invoke an HP Fortran function or subroutine by using a function prototype declaration and invocation.

If a value is returned, use a FUNCTION declaration:

HP Fortran Declaration

FUNCTION CALC(argument-list)

data-type :: CALC

...

END FUNCTION CALC

C Invocation extern data-type calc(argument-list)

data-type variable-name;

variable-name=calc(argument-list);

...

If no value is returned, use a SUBROUTINE declaration and a value: void return

HP Fortran Declaration

SUBROUTINE CALC(argument-list)

...

END SUBROUTINE CALC

C Invocation extern void calc(argument-list) calc(argument-list);

...

10.10.5 Equivalent Data Types for Function Return Values

Both C and HP Fortran pass most function return data by value, but equivalent data types must be used. The following table lists a sample of equivalent function declarations in HP Fortran and C. See Table 10–8 for a complete list of data declarations.

Using HP Fortran in the Common Language Environment 10–51

C Function Declaration float rfort( ) double dfort( ) int ifort( )

HP Fortran Function Declaration

FUNCTION RFORT( )

REAL (KIND=4) :: RFORT

FUNCTION DFORT( )

REAL (KIND=8) :: DFORT

FUNCTION IFORT( )

INTEGER (KIND=4) :: IFORT

Because there are no corresponding data types in C, you should avoid calling

HP Fortran functions of type COMPLEX and DOUBLE COMPLEX, unless you pass a struct of two float (or double float) C values (see Section 10.10.9).

The floating-point format used in memory is determined by the /FLOAT qualifier for both the FORTRAN and CC commands. When floating-point data is passed as an argument or is globally available, the same floating-point format must be used in memory by both the C and HP Fortran parts of your program.

The HP Fortran LOGICAL data types contain a zero if the value is false and a

–1 if the value is true, which works with C conditional and if statements.

For More Information:

• On using the CC command, see the HP C User’s Guide for OpenVMS

Systems.

• On using the FORTRAN command, see Chapter 2.

• On HP Fortran intrinsic data types, see Chapter 8.

• On the HP Fortran language, see the HP Fortran for OpenVMS Language

Reference Manual.

• On the HP C language, see the HP C Language Reference Manual.

10.10.6 Argument Association and Equivalent Data Types

HP Fortran follows the argument-passing rules described in Section 10.2.4.

These rules include:

• Passing arguments by reference (address)

• Receiving arguments by reference (address)

• Passing character data using a character descriptor (address and length)

10–52 Using HP Fortran in the Common Language Environment

10.10.6.1 HP Fortran Intrinsic Data Types

HP Fortran lets you specify the lengths of its intrinsic numeric data types with the following:

• The kind parameter, such as REAL (KIND=4), which is sometimes abbreviated as REAL(4). Intrinsic integer and logical kinds are 1, 2, 4, and 8. Intrinsic real and complex kinds are 4 (single-precision) and 8

(double-precision).

• A default-length name without a kind parameter, such as REAL or

INTEGER. Certain FORTRAN command qualifiers can change the default kind, as described in Section 2.3.26 (for INTEGER and LOGICAL declarations), Section 2.3.37 (for REAL and COMPLEX declarations), and

Section 2.3.17 (for DOUBLE PRECISION declarations).

• The HP Fortran extension of appending a *n size specifier to the defaultlength name, such as INTEGER*8.

• For double-precision real or complex data, the word DOUBLE followed by the default-length name without a kind parameter (specifically DOUBLE

PRECISION and DOUBLE COMPLEX).

The following declarations of the integer An are equivalent (unless you specified the appropriate FORTRAN command qualifier):

INTEGER (KIND=4) :: A1

INTEGER (4) :: A2

INTEGER

INTEGER*4

:: A3

:: A4

Character data in HP Fortran is passed and received by character descriptor.

Dummy character arguments can use assumed-length for accepting character data of varying length.

For More Information:

On HP Fortran intrinsic data types, see Chapter 8.

10.10.6.2 Equivalent HP Fortran and C Data Types

The calling routine must pass the same number of arguments expected by the called routine. Also, for each argument passed, the manner (mechanism) of passing the argument and the expected data type must match what is expected by the called routine. For instance, C usually passes data by value and HP

Fortran typically passes argument data by reference.

Using HP Fortran in the Common Language Environment 10–53

You must determine the appropriate data types in each language that are compatible. When you call a C routine from a HP Fortran main program, certain Fortran cDEC$ ATTRIBUTES directives may be useful to change the default passing mechanism (such as cDEC$ ATTRIBUTES C) as discussed in

Section 10.4.2.

If the calling routine cannot pass an argument to the called routine because of a language difference, you may need to rewrite the called routine. Another option is to create an interface jacket routine that handles the passing differences.

When a C program calls an HP Fortran subprogram, all arguments must be passed by reference because this is what the HP Fortran routine expects. To pass arguments by reference, the arguments must specify addresses rather than values. To pass constants or expressions, their contents must first be placed in variables; then the addresses of the variables are passed.

When you pass the address of the variable, the data types must correspond as shown in Table 10–8.

Table 10–8 HP Fortran and C Data Types

HP Fortran Data Declaration C Data Declaration integer (kind=2) x integer (kind=4) x integer (kind=8) x logical x real x double precision x real (kind=16) x complex (kind=4) x complex (kind=8) x complex (kind=16) x character(len=5) short int x; int x;

_ _int64 x; unsigned x; float x; double x; long double x; 1 struct { float real, float imag; } x; struct { double dreal, double dimag } x; struct { long double dreal; long double dimag } x;

2 char x[5]

HP C interprets this as either a 128-bit IEEE X_FLOAT or a 64-bit floating-point number, depending on the value specified in the CC /L_DOUBLE-SIZE qualifier. The default is /L_

DOUBLE-SIZE=128.

The equivalent C declaration is long double (may not support X_floating).

10–54 Using HP Fortran in the Common Language Environment

Be aware of the various sizes supported by HP Fortran for integer, logical, and real variables (see Chapter 8), and use the size consistent with that used in the

C routine.

HP Fortran LOGICAL data types contain a zero if the value is false and a –1 if the value is true, which works with C language conditional and if statements.

Any character string passed by HP Fortran is not automatically nullterminated. To null-terminate a string from HP Fortran, use the CHAR intrinsic function (described in the HP Fortran for OpenVMS Language

Reference Manual).

10.10.7 Example of Passing Integer Data to C Functions

Example 10–8 shows C code that declares the two functions HLN and MGN.

These functions display the arguments received. The function HLN expects the argument by value, whereas MGN expects the argument by reference

(address).

Example 10–8 C Functions Called by an HP Fortran Program

/* get integer by value from Fortran. File: PASS_INT_TO_C.C */ void hln(int i) { printf("99==%d\n",i); i = 100;

}

/* get integer by reference from Fortran */ void mgn(int *i) { printf("99==%d\n",*i);

*i = 101;

}

Example 10–9 shows the HP Fortran (main program) code that calls the two C functions HLN and MGN.

Using HP Fortran in the Common Language Environment 10–55

Example 10–9 Calling C Functions and Passing Integer Arguments

! Using %REF and %VAL to pass argument to C. File: PASS_INT_TO_CFUNCS.F90

INTEGER :: I

I = 99

CALL HLN(%VAL(I))

PRINT *,"99==",I

! pass by value

! pass by reference CALL MGN(%REF(I))

PRINT *,"101==",I

I = 99

CALL MGN(I)

PRINT *,"101==",I

END

! pass by reference

The files (shown in Example 10–8 and Example 10–9) might be compiled, linked, and run as follows:

$ FORTRAN PASS_INT_TO_CFUNCS.F90

$ CC PASS_INT_TO_C.C

$ LINK/EXECUTABLE=PASS_INT PASS_INT_TO_CFUNCS, PASS_INT_TO_C

$ RUN PASS_INT

99==99

99==

99==99

101==

99==99

101==

101

10.10.8 Example of Passing Complex Data to C Functions

Example 10–10 shows HP Fortran code that passes a COMPLEX (KIND=4) value (1.0,0.0) by immediate value to subroutine foo. To pass COMPLEX arguments by value, the compiler passes the real and imaginary parts of the argument as two REAL arguments by immediate value.

10–56 Using HP Fortran in the Common Language Environment

Example 10–10 Calling C Functions and Passing Complex Arguments

! Using !DEC$ATTRIBUTES to pass COMPLEX argument by value to F90 or C.

! File: cv_main.f90

interface subroutine foo(cplx)

!DEC$ATTRIBUTES C :: foo complex cplx end subroutine end interface complex(kind=4) c c = (1.0,0.0) call foo(c) end

! pass by value

If subroutine foo were written in HP Fortran, it might look similar to the following example. In this version of subroutine foo, the COMPLEX parameter is received by immediate value. To accomplish this, the compiler accepts two

REAL parameters by immediate value and stores them into the real and imaginary parts, respectively, of the COMPLEX parameter cplx.

! File: cv_sub.f90

subroutine foo(cplx)

!DEC$ATTRIBUTES C :: foo complex cplx print *, ’The value of the complex number is ’, cplx end subroutine

If subroutine foo were written in C, it might look similar to the following example in which the complex number is explicitly specified as two arguments of type float.

/* File: cv_sub.c */

#include <stdio.h> typedef struct {float c1; float c2;} complex; void foo(complex c)

{ printf("The value of the complex number is (%f,%f)\n", c1, c2);

}

Using HP Fortran in the Common Language Environment 10–57

The main routine (shown in Example 10–10) might be compiled and linked to the object file created by the compilation of the HP Fortran subroutine and then run as follows:

$ FORTRAN CV_MAIN.F90

$ FORTRAN CV_SUB.F90

$ LINK/EXECUTABLE=CV.EXE CV_MAIN.OBJ, CV_SUB.OBJ

$ RUN CV

1.000000,0.0000000E+00

The main routine might also be compiled and linked to the object file created by the compilation of the C subroutine and then run as follows:

$ CC CV_SUB.C

$ LINK/EXECUTABLE=CV2.EXE CV_MAIN.OBJ CV_SUB.OBJ

$ RUN CV2

1.000000,0.000000

10.10.9 Handling User-Defined Structures

User-defined derived types in HP Fortran and user-defined C structures can be passed as arguments if the following conditions are met:

• The elements of the structures use the same alignment conventions

(same amount of padding bytes, if any). The default alignment for C structure members is natural alignment. You can use the CC /MEMBER_

ALIGNMENT qualifier (or pragma) to alter that alignment.

Derived-type data in HP Fortran is naturally aligned (the compiler adds needed padding bytes) unless you specify the /ALIGNMENT=RECORDS=-

PACKED (or equivalent) qualifier (see Section 2.3.3).

• All elements of the structures are in the same order.

HP Fortran orders elements of derived types sequentially. However, those writing standard-conforming programs should not rely on this sequential order because the standard allows elements to be in any order unless the

SEQUENCE statement is specified.

• The respective elements of the structures have the same data type and length (kind), as described in Section 10.10.6.

• The structure must be passed by reference (address).

10–58 Using HP Fortran in the Common Language Environment

10.10.10 Handling Scalar Pointer Data

When HP Fortran passes scalar numeric data with the POINTER attribute, how the scalar numeric data gets passed depends on whether or not an interface block is provided:

• If you do not provide an interface block to pass the actual pointer, HP

Fortran dereferences the HP Fortran pointer and passes the actual data

(the target of the pointer) by reference.

• If you do provide an interface block to pass the actual pointer, HP Fortran passes the HP Fortran pointer by reference.

When passing scalar numeric data without the pointer attribute, HP Fortran passes the actual data by reference. If the called C function declares the dummy argument for the passed data to be passed by a pointer, it accepts the actual data passed by reference (address) and handles it correctly.

Similarly, when passing scalar data from a C program to an HP Fortran subprogram, the C program can use pointers to pass numeric data by reference.

Example 10–11 shows an HP Fortran program that passes a scalar (nonarray) pointer to a C function. Variable X is a pointer to variable Y.

The function call to IFUNC1 uses a procedure interface block, whereas the function call to IFUNC2 does not. Because IFUNC1 uses a procedure interface block (explicit interface), the pointer is passed. Without an explicit interface

IFUNC2, the target data is passed.

Using HP Fortran in the Common Language Environment 10–59

Example 10–11 Calling C Functions and Passing Pointer Arguments

! Pass scalar pointer argument to C. File: SCALAR_POINTER_FUNC.F90

INTERFACE

FUNCTION IFUNC1(A)

INTEGER, POINTER :: A

INTEGER IFUNC1

END FUNCTION

END INTERFACE

INTEGER, POINTER :: X

INTEGER, TARGET :: Y

Y = 88

X => Y

PRINT *,IFUNC1(X)

PRINT *,IFUNC2(X)

! Interface block visible, so pass

! pointer by reference. C expects "int **"

! No interface block visible, so pass

! value of "y" by reference. C expects "int *"

PRINT *,Y

END

Example 10–12 shows the C function declarations that receive the HP Fortran pointer or target arguments from the example in Example 10–11.

Example 10–12 C Functions Receiving Pointer Arguments

/* C functions Fortran 90 pointers. File: SCALAR_POINTER.C

*/ int ifunc1(int **a) { printf("a=%d\n",**a);

**a = 99; return 100;

} int ifunc2(int *a) { printf("a=%d\n",*a);

*a = 77; return 101;

}

The files (shown in Example 10–11 and Example 10–12) might be compiled, linked, and run as follows:

10–60 Using HP Fortran in the Common Language Environment

$ CC SCALAR_POINTER.C

$ FORTRAN SCALAR_POINTER_FUNC.F90

$ LINK/EXECUTABLE=POINTER SCALAR_POINTER, SCALAR_POINTER_FUNC

$ RUN POINTER a=88

100 a=99

101

10.10.11 Handling Arrays

There are two major differences between the way the C and HP Fortran languages handle arrays:

• HP Fortran stores arrays with the leftmost subscript varying the fastest

(column-major order). With C, the rightmost subscript varies the fastest

(row-major order).

• Although the default for the lower bound of an array in HP Fortran is 1, you can specify an explicit lower bound of 0 (zero) or another value. With

C the lower bound is 0.

Because of these two factors:

• When a C routine uses an array passed by an HP Fortran subprogram, the dimensions of the array and the subscripts must be interchanged and also adjusted for the lower bound of 0 instead of 1 (or a different value).

• When an HP Fortran program uses an array passed by a C routine, the dimensions of the array and the subscripts must be interchanged. You also need to adjust for the lower bound being 0 instead of 1, by specifying the lower bound for the HP Fortran array as 0.

HP Fortran orders arrays in column-major order. The following HP Fortran array declaration for a 2 by 3 array creates elements ordered as y(1,1), y(2,1), y(1,2), y(2,2), y(1,3), y(2,3): integer y(2,3)

The HP Fortran declaration for a 2 by 3 array can be modified as follows to have the lowest bound 0 and not 1, resulting in elements ordered as y(0,0), y(1,0), y(0,1), y(1,1), y(0,2), y(1,2): integer y(0:1,0:2)

The following C array declaration for a 3 by 2 array has elements in row-major order as z[0,0], z[0,1], z[1,0], z[1,1], z[2,0], z[2,1]: int z[3][2]

Using HP Fortran in the Common Language Environment 10–61

To use C and HP Fortran array data:

• Consider using a 0 (zero) as the lowest bounds in the HP Fortran array declaration.

You may need to specify the HP Fortran declaration with a lowest bound 0 (not 1) for maintenance with C arrays or because of algorithm requirements.

• Reverse the dimensions in one of the array declaration statements. For example, declare an HP Fortran array as 2 by 3 and the C array as 3 by 2.

Similarly, when passing array row and column locations between C and HP

Fortran, reverse the dimension numbers (interchange the row and column numbers in a two-dimensional array).

When passing certain array arguments, if you use an explicit interface that specifies the dummy argument as an array with the POINTER attribute or an assumed-shape array, the argument is passed by array descriptor (see

Section 10.2.7).

For information about performance when using multidimensional arrays, see

Section 5.4.

Example 10–13 shows a C function declaration for function EXPSHAPE, which prints the passed explicit-shape array.

Example 10–13 C Function That Receives an Explicit-Shape Array

/* Get explicit-shape arrays from Fortran. File: EXPARRAY_FUNC.C */ void expshape(int x[3][2]) { int i,j; for (i=0;i<3;i++) for (j=0;j<2;j++) printf("x[%d][%d]=%d\n",i,j,x[i][j]);

}

Example 10–14 shows an HP Fortran program that calls the C function

EXPSHAPE (shown in Example 10–13).

10–62 Using HP Fortran in the Common Language Environment

Example 10–14 HP Fortran Program That Passes an Explicit-Shape Array

! Pass an explicit-shape array from Fortran to C. File: EXPARRAY.F90

INTEGER :: X(2,3)

X = RESHAPE( (/(I,I=1,6)/), (/2,3/) )

CALL EXPSHAPE(X)

END

The files (shown in Example 10–13 and Example 10–14) might be compiled, linked, and run as follows:

$ FORTRAN EXPARRAY.F90

$ CC EXPARRAY_FUNC.C

$ LINK/EXECUTABLE=EXPARRAY EXPARRAY, EXPARRAY_FUNC

$ RUN EXPARRAY x[0][0]=1 x[0][1]=2 x[1][0]=3 x[1][1]=4 x[2][0]=5 x[2][1]=6

For information on the use of array arguments with HP Fortran, see

Section 10.2.5.

10.10.12 Handling Common Blocks of Data

The following notes apply to handling common blocks of data between HP

Fortran and C:

• In HP Fortran, you declare each common block with the COMMON statement. In C, you can use any global variable defined as a struct.

• Data types must match unless you desire implicit equivalencing. If so, you must adhere to the alignment restrictions for HP Fortran data types.

• If there are multiple routines that declare data with multiple COMMON statements and the common blocks are of unequal length, the largest of the sizes is used to allocate space.

• A blank common block has a name of $BLANK.

• You should specify the same alignment characteristics in C and HP

Fortran. To specify the alignment of common block data items, specify the

/ALIGN=COMMONS=NATURAL or /ALIGN=COMMONS=STANDARD qualifiers when compiling HP Fortran procedures using the FORTRAN command or specify data declarations carefully (see Section 5.3).

Using HP Fortran in the Common Language Environment 10–63

The following examples show how C and HP Fortran code can access common blocks of data. The C code declares a global structure, calls the f_calc HP

Fortran function to set the values, and prints the values: struct S {int j; float k;}r; main() { f_calc(); printf("%d %f\n", r.j, r.k);

}

The HP Fortran function then sets the data values:

SUBROUTINE F_CALC()

COMMON /R/J,K

REAL K

INTEGER J

J = 356

K = 5.9

RETURN

END SUBROUTINE F_CALC

The C program then prints the structure member values 356 and 5.9 set by the

HP Fortran function.

10–64 Using HP Fortran in the Common Language Environment

Using OpenVMS Record Management

Services

This chapter describes:

• Section 11.1, Overview of OpenVMS Record Management Services

• Section 11.2, RMS Data Structures

• Section 11.3, RMS Services

• Section 11.4, User-Written Open Procedures

• Section 11.5, Example of Block Mode I/O

11.1 Overview of OpenVMS Record Management Services

You can call OpenVMS Record Management Services (RMS) directly from

HP Fortran programs. RMS is used by all utilities and languages for their

I/O processing, allowing files to be accessed efficiently, flexibly, with device independence, and taking full advantage of the capabilities of the OpenVMS operating system.

You need to know the basic concepts concerning files on OpenVMS systems and system-service calling conventions before reading this chapter. Basic file concepts are covered in the Guide to OpenVMS File Applications, and system-service calling conventions are covered in Chapter 10.

You should also have access to the OpenVMS Record Management Services

Reference Manual. Although not written specifically for HP Fortran programmers, it is the definitive reference source for all information on the use of RMS.

This chapter will help you understand the material in the OpenVMS Record

Management Services Reference Manual in terms of Fortran concepts and usage. You should also be able to more fully understand the material in the

Guide to OpenVMS File Applications, which covers more areas of RMS in greater detail than this chapter.

Using OpenVMS Record Management Services 11–1

The easiest way to call RMS services directly from HP Fortran is to use a

USEROPEN routine, which is a subprogram that you specify in an OPEN statement. The HP Fortran Run-Time Library (RTL) I/O support routines call the USEROPEN routine in place of the RMS services at the time a file is first opened for I/O.

The HP Fortran RTL sets up the RMS data structures on your behalf with initial field values that are based on parameters specified in your OPEN statement. This initialization usually eliminates most of the code needed to set up the proper input to RMS Services. If you specify the USEROPEN keyword in the OPEN statement, control transfers to the specified USEROPEN routine that can further change RMS data structures and then call the appropriate

RMS services, including SYS$OPEN (or SYS$CREATE) and SYS$CONNECT.

When you use USEROPEN routines, you can take advantage of the power of RMS without most of the declarations and initialization code normally required. Section 11.4 describes how to use USEROPEN routines and gives examples. You should be familiar with the material in Section 11.2 before reading Section 11.4.

11.2 RMS Data Structures

RMS system services have so many options and capabilities that it is impractical to use anything other than several large data structures to provide their arguments. You should become familiar with all of the RMS data structures before using RMS system services.

The RMS data structures are:

• File Access Block (FAB): used to describe files in general.

• Record Access Block (RAB): used to describe the records in files.

• Name Block (NAM): used to give supplementary information about the name of files beyond that provided with the FAB.

• Extended Attributes Blocks (XABs): a family of related blocks that are linked to the FAB or RAB to communicate to RMS any file attributes beyond those expressed in the FAB.

The RMS data structures are used both to pass arguments to RMS services and to return information from RMS services to your program. In particular, an auxiliary structure, such as a NAM or XAB block, is commonly used explicitly to obtain information optionally returned from RMS services.

11–2 Using OpenVMS Record Management Services

The OpenVMS Record Management Services Reference Manual describes how each of these data structures is used in calls to RMS services. In this section, a brief overview of each block is given, describing its purpose and how it is manipulated in HP Fortran programs.

In general, there are six steps to using the RMS control blocks in calls to RMS system services:

Declare the structure of the blocks and the symbolic parameters used in them by including the appropriate definition library modules from the

Fortran default library FORSYSDEF.TLB.

Declare the memory allocation for the blocks that you need with a

RECORD statement.

Declare the system service names by including the library module

$SYSSRVNAM from FORSYSDEF.TLB.

Initialize the values of fields needed by the service you are calling. The structure definitions provided for these blocks in the FORSYSDEF library modules provide only the field names and offsets needed to reference the

RMS data structures. You must assign all of the field values explicitly in your HP Fortran program.

Two fields of each control block are mandatory; they must be filled in with the correct values before they are used in any service call. These are the block id (BID, or COD in the case of XABs) and the block length (BLN).

These are checked by all RMS services to ensure that their input blocks have proper form.

These fields must be assigned explicitly in your HP Fortran programs, unless you are using the control blocks provided by the Fortran RTL I/O routines, which initialize all control block fields. See Table 11–1 for a list of the control field values provided by the Fortran RTL I/O routines.

Invoke the system service as a function reference, giving the control blocks as arguments according to the specifications in the RMS reference manual.

Check the return status to ensure that the service has completed successfully.

Steps 1-4 are described for each type of control block in Section 11.2.2 to

Section 11.2.5. See Section 11.3 for descriptions of steps 5 and 6.

Using OpenVMS Record Management Services 11–3

11.2.1 Using FORSYSDEF Library Modules to Manipulate RMS Data

Structures

The definition library FORSYSDEF.TLB contains the required Fortran declarations for all of the field offsets and symbolic values of field contents described in the OpenVMS Record Management Services Reference Manual.

The appropriate INCLUDE statement needed to access these declarations for each structure is described wherever appropriate in the text that follows.

In general, you need to supply one or more RECORD statements to allocate the memory for the structures that you need. See the OpenVMS

Record Management Services Reference Manual for a description of the naming conventions used in RMS service calls. Only the convention for the

PARAMETER declarations is described here.

The FORSYSDEF library modules contain several different kinds of

PARAMETER declarations. The declarations are distinguished from each other by the letter following the dollar sign ( $ ) in their symbolic names. Each is useful in manipulating field values, but the intended use of the different kinds of PARAMETER declarations is as follows:

• Declarations that define only symbolic field values are identified by the presence of a ‘‘C_’’ immediately after the block prefix in their names. For example, the RAB$B_RAC field has three symbolic values, one each for sequential, keyed, and RFA access modes. The symbolic names for these values are RAB$C_SEQ, RAB$C_KEY, and RAB$C_RFA. You use these symbolic field values in simple assignment statements. For example:

INCLUDE ’($RABDEF)’

RECORD /RABDEF/ MYRAB

. . .

MYRAB.RAB$B_RAC = RAB$C_SEQ

. . .

• Declarations that use mask values instead of explicit values to define bit offsets are identified by the presence of ‘‘M_’’ immediately after the block prefix in their names. For example, the FAB$L_FOP field is an

INTEGER*4 field with the individual bits treated as flags. Each flag has a mask value for specifying a particular file processing option. For instance, the MXV bit specifies that RMS should maximize the version number of the file when it is created. The mask value associated with this bit has the name FAB$M_MXV.

11–4 Using OpenVMS Record Management Services

In order to use these parameters, you must use .AND. and .OR. to turn off and on specific bits in the field without changing the other bits. For example, to set the MXV flag in the FOP field, you would use the following program segment:

INCLUDE ’($FABDEF)’

RECORD /FABDEF/ MYFAB

. . .

MYFAB.FAB$L_FOP = MYFAB.FAB$L_FOP .OR. FAB$M_MXV

• Two types of declarations that define symbolic field values are used to define flag fields within a larger named field. These are identified by the presence of ‘‘S_’’ or ‘‘V_’’ immediately after the block prefix in their names.

The ‘‘S_’’ form of the name defines the size of that flag field (usually the value 1, for single bit flag fields), and the ‘‘V_’’ form defines the bit offset from the beginning of the larger field. These forms can be used with the symbolic bit manipulation functions to set or clear the fields without destroying the other flags. To perform the same operation as the previous example, but using the ‘‘V_’’ and ‘‘S_’’ flags, specify the following:

INCLUDE ’($FABDEF)’

RECORD /FABDEF/ MYFAB

. . .

MYFAB.FAB$L_FOP = IBSET(MYFAB.FAB$L_FOP,FAB$V_MXV)

. . .

For most of the FAB, RAB, NAM, and XAB fields that are not supplied with symbolic values, you will need to supply sizes or pointers. For sizes, you can use ordinary numeric constants or other numeric scalar quantities. To set the maximum record number into the FAB$L_MRN field, you could use the following statement:

MYFAB.FAB$L_MRN = 5000

To supply the required pointers, usually from one block to another, you must use the %LOC built-in function to retrieve addresses. To fill in the FAB$L_

NAM field in a FAB block with the address of the NAM block that you want to use, you can use the following program fragment:

INCLUDE ’($FABDEF)’

INCLUDE ’($NAMDEF)’

. . .

RECORD /FABDEF/ MYFAB, /NAMDEF/ MYNAM

. . .

MYFAB.FAB$L_NAM = %LOC(MYNAM)

Using OpenVMS Record Management Services 11–5

11.2.2 File Access Block (FAB)

The File Access Block (FAB) is used for calling the following services:

SYS$CLOSE

SYS$CREATE

SYS$DISPLAY

SYS$ENTER

SYS$ERASE

SYS$EXTEND

SYS$OPEN

SYS$PARSE

SYS$REMOVE

SYS$RENAME

SYS$SEARCH

The purpose of the FAB is to describe the file being manipulated by these services. In addition to the fields that describe the file directly, there are pointers in the FAB structure to auxiliary blocks used for more detailed information about the file. These auxiliary blocks are the NAM block and one or more of the XAB blocks.

To declare the structure and parameter values for using FAB blocks, include the $FABDEF library module from FORSYSDEF. For example:

INCLUDE ’($FABDEF)’

To examine the fields and values declared, use the /LIST qualifier after the right parenthesis. Each field in the FAB is described at length in the OpenVMS

Record Management Services Reference Manual.

If you are using a USEROPEN procedure, the actual allocation of the FAB is performed by the Fortran Run-Time Library I/O support routines, and you only need to declare the first argument to your USEROPEN routine to be a record with the FAB structure. For example:

Calling program:

. . .

EXTERNAL MYOPEN

. . .

OPEN (UNIT=8, . . .

, USEROPEN=MYOPEN)

. . .

USEROPEN routine:

INTEGER FUNCTION MYOPEN(FABARG, RABARG, LUNARG)

INCLUDE ’($FABDEF)’

. . .

RECORD /FABDEF/ FABARG

. . .

Usually, you need to declare only one FAB block, but some situations you need to use two. For example, the SYS$RENAME service requires one FAB block to describe the old file name and another to describe the new file name. In any of these cases, you can declare whatever FAB blocks you need with a RECORD statement. For example:

11–6 Using OpenVMS Record Management Services

INCLUDE ’($FABDEF)’

. . .

RECORD /FABDEF/ OLDFAB, NEWFAB

If you use any of the above service calls without using a USEROPEN routine, you must initialize the required FAB fields in your program. The FAB fields required for each RMS service are listed in the descriptions of the individual services in the OpenVMS Record Management Services Reference Manual.

Most services also fill in output values in the FAB or one of its associated blocks. Descriptions of these output fields are also provided with the service descriptions.

In the example programs in the OpenVMS Record Management Services

Reference Manual, these initial field values are described as they would be used in MACRO programs, where the declaration macros allow initialization arguments. In each case where the MACRO example shows a field being initialized in a macro, you must have a corresponding initialization at run time in your program.

The OpenVMS Record Management Services Reference Manual contains an example that shows the use of the ALQ parameter for specifying the initial allocation size of the file in blocks:

Program that uses XABDAT and XABDAT_STORE

MYFAB: $FAB ALQ=500, FOP=CBT, FAC=<PUT>, -

FNM=<DISK$:[PROGRAM]SAMPLE_FILE.DAT>, -

ORG=SEQ, RAT=CR, RFM=VAR, SHR=<NIL>, MRS=52, XAB=MYXDAT

As described in the section on the XAB$L_ALQ field (in the same manual), this parameter sets the FAB field FAB$L_ALQ. To perform the same initialization in HP Fortran, you must supply a value to the FAB$L_ALQ field using a run-time assignment statement. For example:

MYFAB.FAB$L_ALQ = 500

The FAB$B_BID and FAB$B_BLN fields must be filled in by your program prior to their use in an RMS service call, unless they have already been supplied by the HP Fortran RTL I/O routines. You should always use the symbolic names for the values of these fields; for example:

Using OpenVMS Record Management Services 11–7

INCLUDE ’($FABDEF)’

. . .

RECORD /FABDEF/ MYFAB

. . .

MYFAB.FAB$B_BID = FAB$C_BID

MYFAB.FAB$B_BLN = FAB$C_BLN

. . .

STATUS = SYS$OPEN( . . .

)

. . .

11.2.3 Record Access Block (RAB)

The Record Access Block (RAB) is used for calling the following services:

SYS$CONNECT

SYS$DELETE

SYS$DISCONNECT

SYS$FIND

SYS$FLUSH

SYS$FREE

SYS$GET

SYS$NXTVOL

SYS$PUT

SYS$READ

SYS$RELEASE

SYS$REWIND

SYS$SPACE

SYS$TRUNCATE

SYS$UPDATE

SYS$WAIT

SYS$WRITE

The purpose of the RAB is to describe the record being manipulated by these services. The RAB contains a pointer to the FAB used to open the file being manipulated, making it unnecessary for these services to have a FAB in their argument lists. Also, a RAB can point to certain types of XABs.

Using the FOR$RAB Intrinsic Function

To declare the structure and parameter values for using RAB blocks, include the $RABDEF library module from FORSYSDEF. For example:

INCLUDE ’($RABDEF)’

To examine the fields and values declared, use the /LIST qualifier after the right parenthesis. Each field in the RAB is described at length in the

OpenVMS Record Management Services Reference Manual.

If you are using a USEROPEN procedure, the actual allocation of the RAB is performed by the HP Fortran Run-Time Library I/O support routines, and you only need to declare the second argument to your USEROPEN routine to be a record with the RAB structure. For example:

Calling program:

11–8 Using OpenVMS Record Management Services

. . .

EXTERNAL MYOPEN

. . .

OPEN (UNIT=8, . . .

, USEROPEN=MYOPEN)

. . .

USEROPEN routine:

INTEGER FUNCTION MYOPEN(FABARG, RABARG, LUNARG)

. . .

INCLUDE ’($RABDEF)’

. . .

RECORD /RABDEF/ RABARG

. . .

If you need to access the RAB used by the Fortran I/O system for one of the open files in your program, you can use the FOR$RAB intrinsic function (do not declare it as EXTERNAL). You can use FOR$RAB even if you did not use a USEROPEN routine to open the file. The FOR$RAB intrinsic function takes a single INTEGER*4 variable (or constant) argument, the unit number of the open file for which you want to obtain the RAB address. The function result is the address of the RAB for that unit.

If you use the FOR$RAB function in your program, you should declare it to be

INTEGER*4 if you assign the result value to a variable. If you do not, your program will assume that it is a REAL function and will perform an improper conversion to INTEGER.

To use the result of the FOR$RAB call, you must pass it to a subprogram as an actual argument using the %VAL built-in function. This allows the subprogram to access it as an ordinary HP Fortran record argument. For example, the main program for calling a subroutine to print the RAB fields could be coded as follows:

INTEGER (KIND=4) RABADR, FOR$RAB

. . .

OPEN(UNIT=14, FILE=’TEST.DAT’, STATUS=’OLD’)

. . .

RABADR = FOR$RAB(14)

. . .

CALL DUMPRAB(%VAL(RABADR))

. . .

If you need to access other control blocks in use by the RMS services for that unit, you can obtain their addresses using the link fields they contain. For example:

Using OpenVMS Record Management Services 11–9

SUBROUTINE DUMPRAB(RAB)

. . .

INTEGER (KIND=4) FABADR

INCLUDE ’($RABDEF)’

RECORD /RABDEF/ RAB

. . .

FABADR = RAB.RAB$L_FAB

. . .

CALL DUMPFAB(%VAL(FABADR))

. . .

In this example, the routine DUMPRAB obtains the address of the associated

FAB by referencing the RAB$L_FAB field of the RAB. Other control blocks associated with the FAB, such as the NAM and XAB blocks, can be accessed using code similar to this example.

Usually, you need to declare only one RAB block. Sometimes, however, you may need to use more than one. For example, the multistream capability of

RMS allows you to connect several RABs to a single FAB. This allows you to simultaneously access several records of a file, keeping a separate context for each record. You can declare whatever RAB blocks you need with a RECORD statement. For example:

INCLUDE ’($RABDEF)’

. . .

RECORD /RABDEF/ RAB1, RABARRAY(10)

If you use any of the above service calls without using a USEROPEN routine, you must initialize the required RAB fields in your program. The RAB fields required for each RMS service are listed in the descriptions of individual services in the OpenVMS Record Management Services Reference Manual.

Most services also fill in output values in the RAB. Descriptions of these output fields are provided with the service descriptions.

In the example programs supplied in the OpenVMS Record Management

Services Reference Manual, these initial field values are described as they would be used in MACRO programs, where the declaration macros allow initialization arguments. Thus, in each case where the MACRO example shows a field being initialized in a declaration macro, you must have a corresponding initialization at run time in your program.

For example, the OpenVMS Record Management Services Reference Manual contains an example that shows the use of the RAC parameter for specifying the record access mode to use:

11–10 Using OpenVMS Record Management Services

SRC_FAB:

$FAB FAC=<GET>,-

FOP=<SQO>,-

FNM=<SRC:>

SRC_RAB:

$RAB FAB=SRC_FAB,-

RAC=SEQ,-

UBF=BUFFER,-

USZ=BUFFER_SIZE

; File access for GET only

; DAP file transfer mode

; Name of input file

; Address of associated FAB

; Sequential record access

; Buffer address

; Buffer size

In this example, sequential access mode is used. As described in the section on the RAC field (in the same manual), this parameter sets the RAB$B_RAC field to the value RAB$C_SEQ. This means that to perform the same initialization in Fortran, you must supply RAC field values by a run-time assignment statement. For example:

MYRAB.RAB$B_RAC = RAB$C_SEQ

The RAB$B_BID and RAB$B_BLN fields must be filled in by your program prior to their use in an RMS service call, unless they have been supplied by the

Fortran RTL I/O routines. You should always use the symbolic names for the values of these fields. For example:

INCLUDE ’($RABDEF)’

. . .

RECORD /RABDEF/ MYRAB

. . .

MYRAB.RAB$B_BID = RAB$C_BID

MYRAB.RAB$B_BLN = RAB$C_BLN

. . .

STATUS = SYS$CONNECT(MYRAB)

. . .

11.2.4 Name Block (NAM)

The Name Block (NAM) can be used with the FAB in most FAB-related services in order to supply to or receive from RMS more detailed information about a file name. The NAM block is never given directly as an argument to an RMS service; to supply it you must link to it from the FAB. See Section 11.2.1 for an example of this.

Using OpenVMS Record Management Services 11–11

To declare the structure and parameter values for using NAM blocks, include the $NAMDEF library module from FORSYSDEF. For example:

INCLUDE ’($NAMDEF)’

To examine the fields and values declared, use the /LIST qualifier after the right parenthesis. Each field in the NAM is described in the OpenVMS Record

Management Services Reference Manual.

If you are using a USEROPEN procedure, the actual allocation of the NAM is performed by the HP Fortran Run-Time Library I/O support routines.

Because the NAM block is linked to the FAB, it is not explicitly given in the

USEROPEN routine argument list.

To access the NAM, you need to call a subprogram, passing the pointer by value and accessing the NAM in the subprogram as a structure. For example:

Calling program:

. . .

EXTERNAL MYOPEN

. . .

OPEN (UNIT=8, . . .

, USEROPEN=MYOPEN)

. . .

USEROPEN routine:

INTEGER FUNCTION MYOPEN(FABARG, RABARG, LUNARG)

. . .

INCLUDE ’($FABDEF)’

. . .

RECORD /FABDEF/ FABARG

. . .

CALL NAMACCESS(%VAL(FABARG.FAB$L_NAM))

. . .

NAM accessing routine:

SUBROUTINE NAMACCESS(NAMARG)

. . .

INCLUDE ’($NAMDEF)’

. . .

RECORD /NAMDEF/ NAMARG

. . .

IF (NAMARG.NAM$B_ESL .GT. 132) GO TO 100

. . .

11–12 Using OpenVMS Record Management Services

Usually, you only need to declare one NAM block. You can declare whatever

NAM blocks you need with a RECORD statement. For example:

INCLUDE ’($NAMDEF)’

. . .

RECORD /NAMDEF/ NAM1, NAM2

Most often, you use the NAM block to pass and receive information about the components of the file specification, such as the device, directory, file name, and file type. For this reason, most of the fields of the NAM block are

CHARACTER strings and lengths. When using the NAM block, you should be familiar with the argument passing mechanisms for CHARACTER arguments described in Section 10.8.4.3.

Your program must fill in the NAM$B_BID and NAM$B_BLN fields prior to their use in an RMS service call, unless they have been supplied by the HP

Fortran RTL I/O routines. You should always use the symbolic names for the values of these fields. For example:

INCLUDE ’($NAMDEF)’

. . .

RECORD /NAMDEF/ MYNAM

. . .

MYNAM.NAM$B_BID = NAM$C_BID

MYNAM.NAM$B_BLN = NAM$C_BLN

. . .

11.2.5 Extended Attributes Blocks (XABs)

Extended Attributes Blocks (XABs) are a family of related structures for passing and receiving additional information about files. There are different kinds of XABs:

• Allocation Control (XABALL)

• Date and Time (XABDAT)

• File Header Characteristics (XABFHC)

• Item List (XABITM)

• Journaling (XABJNL)

• Key Definition (XABKEY)

• Protection (XABPRO)

• Recovery Unit (XABRU)

• Revision Date and Time (XABRDT)

• Summary (XABSUM)

Using OpenVMS Record Management Services 11–13

• Terminal (XABTRM)

The XABs are described in the OpenVMS Record Management Services

Reference Manual. XABs are generally smaller and simpler than the FAB,

RAB, and NAM blocks because each describes information about a single aspect of the file. You do not have to use all of them; for any given call to an

RMS service routine, use only those that are required.

Often the XAB fields override the corresponding fields in the FAB. For example, the allocation XAB describes the file’s block allocation in more detail than the

FAB$L_ALQ field can. For this reason, XAB$L_ALQ (the allocation field in the

XABALL structure) always overrides the FAB$L_ALQ value.

The XABs used for any given RMS service call are connected to the FAB in a linked list. The head of the list is the FAB$L_XAB field in the FAB. This field contains the address of the first XAB to be used. Each successive XAB in the list links to the next using the XAB$L_NXT field. This field contains the address of the next XAB in the list. The order of the XABs in the list does not matter, but each kind of XAB must not appear more than once in the list.

The only kind of XAB that can be connected to a RAB instead of a FAB is the terminal XAB. It is linked to the RAB with the RAB$L_XAB field. This is needed because the terminal control information is dynamic and potentially changes with each record operation performed.

To declare the structure and parameter values for using the different

XAB blocks, include the appropriate XAB definition library module from

FORSYSDEF. (The names of the XAB definition library modules are listed previously in this section.) Also, because the XABs are a family of related control blocks, you need to include the $XABDEF library module from

FORSYSDEF.TLB in order to declare the fields common to all XABs. For example, to declare the fields used in the Date and Time XAB, use the following declarations:

INCLUDE ’($XABDATDEF)’

INCLUDE ’($XABDEF)’

To examine the fields and values declared, use the /LIST qualifier after the right parenthesis. All of the fields in the XABs are described in the OpenVMS

Record Management Services Reference Manual.

If you are using a USEROPEN procedure, the actual allocation of the XABs used by the open operation is performed by the HP Fortran Run-Time Library

I/O support routines. Because the XAB blocks are linked to the FAB, the XAB block addresses are not explicitly given in the USEROPEN routine argument list.

11–14 Using OpenVMS Record Management Services

To access the XABs, you need to call a subprogram and pass a pointer to it using the %VAL built-in function or a pointer argument. For an example of this method, see Section 11.2.3.

To allocate space for an XAB block in your program, you need to declare it with a RECORD statement. For example:

INCLUDE ’($XABDATDEF)’

INCLUDE ’($XABPRODEF)’

. . .

RECORD /XABDATDEF/ MYXABDAT, /XABPRODEF/ MYXABPRO

. . .

For each XAB that you declare in your program, you must supply the correct

COD and BLN fields explicitly. These field offsets are common to all XABs and are contained in the $XABDEF library module in FORSYSDEF.TLB. The block id and length are unique for each kind of XAB and the symbolic values for them are contained in the separate XAB declaration library modules in

FORSYSDEF.TLB. For example, to properly initialize a Date and Time XAB, you could use the following code segment:

INCLUDE ’($XABDEF)’

INCLUDE ’($XABDATDEF)’

RECORD /XABDEF/ MYXABDAT

. . .

MYXABDAT.XAB$B_COD = XAB$C_DAT

MYXABDAT.XAB$B_BLN = XAB$C_DATLEN

. . .

11.3 RMS Services

In general, you need to do the same things when calling an RMS service that you need to do when calling any OpenVMS service: declare the name, pass arguments, and check status values. However, RMS services have some additional conventions and ease-of-use features that you should be aware of.

For More Information:

• On calling OpenVMS system services, see Section 10.8.

• On each RMS service, see the OpenVMS Record Management Services

Reference Manual.

Using OpenVMS Record Management Services 11–15

11.3.1 Declaring RMS System Service Names

As with the other system services, you should use the $SYSSRVNAM library module in FORSYSDEF to declare the names of all of the RMS services. For example:

INCLUDE ’($SYSSRVNAM)’

This library module contains comments describing each OpenVMS system service, including all of the RMS services, and INTEGER*4 and EXTERNAL declarations for each. Including the library module allows you to use the names of the RMS services in your programs without further declaration.

11.3.2 Arguments to RMS Services

Most RMS services require three arguments:

• The first is the control block to be used, generally a RAB or FAB, and is mandatory.

• The second and third arguments are the addresses of routines to be called if the RMS service fails or succeeds, and these are optional.

Some RMS services take other arguments, but these services are rarely needed.

You should always refer to the documentation for the specific service that you are calling for detailed information on its arguments.

Most RAB and FAB fields are ignored by most RMS services. The documentation of each service in the OpenVMS Record Management Services

Reference Manual describes which fields are input for that service and which are output, for each control block used. Services that take a FAB as an argument are called the File Control services. Services that take a RAB as an argument are called the Record Control services. Typically, you need to use both when doing RMS I/O in your program.

In general, fields that are not documented as required for input to a service are ignored and can be left uninitialized. The exceptions are the Block Id (BID or

COD) and Block Length (BLN) fields; these must always be initialized. See the preceding sections about the respective blocks for examples of how to initialize these fields.

The output of many RMS services provides the values required for input to other RMS services. For this reason, you usually only need to initialize a few fields in each block to their nondefault values. This is especially true when using RMS blocks declared with the HP Fortran RTL I/O routines as when using USEROPEN routines or the FOR$RAB function.

For More Information:

On passing arguments to system services, see Section 10.8.4.

11–16 Using OpenVMS Record Management Services

11.3.3 Checking Status from RMS Services

You should always invoke RMS services as functions, rather than calling them as subroutines (see Section 10.8.2 for a general discussion of this topic). It is particularly important to check the status of RMS services because they usually do not cause an error when they fail. If the status is not checked immediately, the failure will go undetected until later in the program where it will be difficult to diagnose.

In most cases, you only need to check for success or failure by testing whether the returned status is true or false. Some services have alternate successstatus possibilities. You should always check for these in cases where the program depends on the correct operation of the services.

The RMS services have a unique set of status return symbols not used by any of the other OpenVMS system services. You should always use these symbols whenever you check the individual status values returned. To obtain the declarations for these symbols, include the $RMSDEF library module from

FORSYSDEF.TLB. For example:

INCLUDE ’($RMSDEF)’

This statement includes in your program the declarations for all of the symbolic

RMS return values.

The OpenVMS Record Management Services Reference Manual documents the symbolic values, both success and failure, that can be returned from each of the services. Your program should always test each service-result status against these symbolic values and take appropriate action when a failure status is detected. You should always declare status variables as INTEGER*4 type in order to avoid unexpected numeric conversions. The recommended action depends on whether you are using RMS services in a USEROPEN routine.

The HP Fortran RTL I/O routines that invoke your USEROPEN routine are expecting an RMS status as an output value. For this reason, you need to return the RMS status value as the function value for both failure and success conditions. For example:

INTEGER FUNCTION MYOPEN(FAB,RAB,LUN)

. . .

! Declare RMS service names INCLUDE ’($SYSSRVNAM)’

. . .

MYOPEN = SYS$OPEN(FAB)

IF (.NOT. MYOPEN) RETURN

. . .

RETURN

END

Using OpenVMS Record Management Services 11–17

In this case, if the SYS$OPEN service fails, it returns an error status into the function result variable MYOPEN. If the test of MYOPEN does not indicate success, the function returns the actual RMS status as its value. Then the

RTL I/O routines will signal the appropriate Fortran error normally, as if a

USEROPEN routine had not been used.

If the SYS$OPEN call succeeds, the program continues, and the RMS$_

NORMAL success status will ultimately be returned to the Fortran RTL. This value will cause the OPEN statement that specifies MYOPEN to complete successfully.

If you are not using a USEROPEN routine, your program must indicate the error status directly, unless it is prepared to deal with it. Often, the easiest way to indicate an error and issue a helpful message is to signal the RMS condition directly with LIB$SIGNAL or LIB$STOP. For example:

. . .

INCLUDE ’($SYSSRVNAM)’

INTEGER (KIND=4) STATUS

. . .

! Declare RMS service names

! Declare a status variable

STATUS = SYS$GET(MYRAB)

IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))

For More Information:

On the use of LIB$SIGNAL and LIB$STOP, see Chapter 14.

11.3.4 Opening a File

To perform input or output operations on a file, your program must first open the file and establish an active RMS I/O stream. To open a file, your program generally needs to call either the SYS$CREATE or SYS$OPEN services, followed by the SYS$CONNECT service. When your program uses an OPEN statement without a USEROPEN routine, the HP Fortran RTL I/O routines call these RMS services.

You can use these options related to opening a file:

• Use the SYS$OPEN service to open an existing file. SYS$OPEN returns an error status if the file cannot be found.

• Use the SYS$CREATE service to intentionally create a new file.

• Use SYS$CREATE with the CIF bit in the FAB$L_FOP field to open a file that may or may not exist. The SYS$CREATE service will either open the file (if it exists) or create a new one (if it does not exist). You can use the SUP bit to force SYS$CREATE to create a new file even if one already exists.

11–18 Using OpenVMS Record Management Services

The value of the FAB$B_FAC field of the FAB indicates to RMS what record operations are to be done on the file being opened. If a record operation that was not indicated by the FAC field (such as a SYS$PUT) is attempted, the record service will not perform the operation and will return a failure status.

This file protection feature prevents you from accidentally corrupting a file when you use the wrong RMS service.

The SYS$CONNECT service establishes an active I/O stream, using a RAB, to a file that has been previously opened by your program. RMS identifies all active I/O streams by a unique identifier, called the Internal Stream Identifier

(ISI). This value is stored in the RAB$W_ISI field of the RAB for each active stream being processed.

This field must always be zero when calling SYS$CONNECT. The

SYS$CONNECT service initializes this field, so that subsequent operations using that RAB can be uniquely identified. Under some circumstances, you can establish more than one simultaneously active I/O stream to the same file.

See the OpenVMS Record Management Services Reference Manual for more information on this topic.

11.3.5 Closing a File

To close a file, use the SYS$CLOSE service. This terminates all active I/O streams under way on that file and frees all RMS resources being used for processing that file. Use the SYS$DISCONNECT service if you want to end one active I/O stream, but continue processing the file using another stream.

This service sets the RAB$W_ISI value to zero so that the RAB can be reused for another stream.

11.3.6 Writing Data

To write data to a file, use the SYS$PUT or SYS$WRITE service. Your program must set the PUT bit in the FAB$B_FAC field when the file is opened; otherwise, the service attempting the write operation will fail.

Use the SYS$PUT service when you want to write data in record mode (the default). In record mode, RMS buffers data automatically and performs the actual output operation for a whole group of records at a time. This is the mode used for all HP Fortran WRITE statements. Because most programs and utilities can read data written in record mode, this mode should be used when the data being written is to be read and processed by a general program or utility.

Using OpenVMS Record Management Services 11–19

Use the SYS$WRITE service when you want to bypass the record management capabilities of RMS and write blocks of data directly to the device without additional buffering. This mode is called block mode I/O and is generally much faster and uses less CPU resources than record mode. For this reason, it is the preferred mode for writing large amounts of unformatted data to a device.

Block mode should only be used when the program that needs to read the data can also use block mode. If the program that is to read the data cannot use block mode, you must use some other means to guarantee that the data being written can be accessed. For instance, it is not generally possible to read data written with SYS$WRITE using ordinary HP Fortran READ statements.

Before using SYS$WRITE, read the special restrictions on using block mode in the OpenVMS Record Management Services Reference Manual, because

SYS$WRITE (block mode) may have different device dependencies than

SYS$PUT (record mode).

11.3.7 Reading Data

To read data from a file, use the SYS$GET or SYS$READ service. Your program must set the GET bit in the FAB$B_FAC field when the file is opened; otherwise, the service attempting the read operation will fail.

Use the SYS$GET service when you want to read data in record mode (the default). In this mode, RMS buffers data automatically and performs the actual input operation for a whole group of records at a time. This is the mode used for all HP Fortran READ statements. This mode should be used whenever the program or utility that wrote the data used record mode, unless your reading program can buffer and deblock the data itself.

Use the SYS$READ service when you want to read data using block mode I/O

(see Section 11.3.6. Using SYS$READ is the preferred mode for reading large amounts of unformatted data from a device, but it should only be used when the data was written by a utility or program that wrote the data in block mode.

If the file was written using record mode, RMS control information may be intermixed with the data, making it difficult to process. Before using

SYS$READ, read the special restrictions on using block mode in the OpenVMS

Record Management Services Reference Manual, because SYS$READ (block mode) may have different device dependencies than SYS$GET (record mode).

11–20 Using OpenVMS Record Management Services

11.3.8 Other Services

RMS provides many other file and record processing services beyond just opening, closing, reading, and writing. Other file processing services include:

• SYS$PARSE and SYS$SEARCH: process wildcard and incomplete file specifications and search for a sequence of files to be processed.

• SYS$DISPLAY: retrieves file attribute information.

• SYS$ENTER: inserts a file name into a directory file.

• SYS$ERASE: deletes a file and removes the directory entry used to specify it.

• SYS$EXTEND: increases the amount of disk space allocated to the file.

• SYS$REMOVE: removes directory entries for a file.

• SYS$RENAME: removes a directory entry for a file and inserts a new one in another directory.

Other record processing services include:

• SYS$FIND: positions the record stream at the desired record for later reading or writing.

• SYS$DELETE: deletes a record from the file.

• SYS$SPACE: skips over one or more blocks in block I/O mode.

• SYS$TRUNCATE: truncates a file after a given record.

• SYS$UPDATE: updates the value of an existing record.

For More Information:

On the RMS services, see the OpenVMS Record Management Services Reference

Manual.

11.4 User-Written Open Procedures

The USEROPEN keyword in an OPEN statement provides you with a way to access RMS facilities that are otherwise not available to HP Fortran programs.

It specifies a user-written external procedure (USEROPEN procedure) that controls the opening of a file. The USEROPEN keyword has the form:

USEROPEN = procedure-name

The procedure-name represents the symbolic name of a user-written open procedure. The procedure must be declared in an EXTERNAL statement, and should be a FUNCTION that returns an INTEGER*4 result.

Using OpenVMS Record Management Services 11–21

When an OPEN statement—with or without the USEROPEN keyword—is executed, the Run-Time Library uses the OPEN statement keywords to establish the RMS File Access Block (FAB) and the Record Access Block

(RAB), as well as its own internal data structures. If a USEROPEN keyword is included in the OPEN statement, the Run-Time Library then calls your

USEROPEN procedure instead of opening the file according to its normal defaults. The procedure can then provide additional parameters to RMS and can obtain results from RMS.

The three arguments passed to a user-written open procedure by the Run-Time

Library are:

Address of the FAB

Address of the RAB

Address of a longword integer containing the unit number

Using this information, your USEROPEN procedure can then perform the following operations:

• Modify the FAB and RAB (optional).

• Issue SYS$OPEN and SYS$CONNECT functions or SYS$CREATE and

SYS$CONNECT functions when HP Fortran I/O is to be performed

(required).

Your USEROPEN procedure should invoke the RMS SYS$OPEN routine if the file to be opened already exists (STATUS=’OLD’) or should call the RMS SYS$CREATE routine for any other file type (STATUS=’NEW’,

’UNKNOWN’, or not specified). The status value specified in the OPEN statement is not represented in either the FAB or RAB.

• Check status indicators returned by RMS services (required).

Your procedure should return immediately if an RMS service returns a failure status.

• Obtain information returned by RMS in the FAB and RAB by storing FAB and RAB values in program variables (optional).

• Return a success or failure status value to the Run-Time Library (required).

The RMS services SYS$CREATE, SYS$OPEN, and SYS$CONNECT return status codes. Thus, it is not necessary to set a separate status value as the procedure output if execution of one of these macros is the final step in your procedure.

11–22 Using OpenVMS Record Management Services

A USEROPEN routine can set FAB fields before the corresponding file is opened (or created). However, once the file is open (except if the FAB$V_UFO bit is set), the user should not alter any of the FAB fields.

A USEROPEN routine can likewise set RAB fields before the record stream has been connected (SYS$CONNECT). However, once the file is connected to the record stream, the user should not alter any of the RAB fields.

Once a FAB or RAB is used by the Fortran RTL, it should be treated as read-only by the user, because the Fortran RTL may need to set and alter those fields as needed to complete the user Fortran I/O statements. Any user modification of a FAB or RAB after its initial use may not have the intended effect for subsequent Fortran I/O statements.

For More Information:

On the FAB and RAB, see the OpenVMS Record Management Services

Reference Manual.

11.4.1 Examples of USEROPEN Routines

The following OPEN statement either creates a 1000-block contiguous file or returns an error. (The default HP Fortran interpretation of the INITIALSIZE keyword is to allocate the file contiguously on a best-effort basis, but not to generate an error if the space is not completely contiguous.)

EXTERNAL CREATE_CONTIG

OPEN (UNIT=10, FILE=’DATA’, STATUS=’NEW’, INITIALSIZE=1000, &

USEROPEN=CREATE_CONTIG)

User-written open procedures are often coded in BLISS or MACRO; however, they can also be coded in HP Fortran using HP Fortran’s record handling capability.

The following function creates a file after setting the RMS FOP bit (FAB$V_

CTG) to specify contiguous allocation.

UOPEN1

! Program to demonstrate the use of a simple USEROPEN routine

PROGRAM UOPEN1

EXTERNAL CREATE_CONTIG

! OPEN the file specifying the USEROPEN routine

OPEN (UNIT=10, FILE=’DATA’, STATUS=’NEW’, INITIALSIZE=1000, &

USEROPEN=CREATE_CONTIG)

STOP

END PROGRAM UOPEN1

Using OpenVMS Record Management Services 11–23

! CREATE_CONTIG

! Sample USEROPEN function to force RMS to allocate contiguous

! blocks for the initial creation of a file.

INTEGER FUNCTION CREATE_CONTIG(FAB,RAB,LUN)

Required declarations

INCLUDE ’($FABDEF)’

INCLUDE ’($RABDEF)’

! FAB Structure

! RAB Structure

INCLUDE ’($SYSSRVNAM)’

RECORD /FABDEF/ FAB, /RABDEF/ RAB

! System service name declarations

! Clear the "Contiguous-best-try" bit, set the "Contiguous" bit

FAB.FAB$L_FOP = FAB.FAB$L_FOP .AND. .NOT. FAB$M_CBT

FAB.FAB$L_FOP = FAB.FAB$L_FOP .OR. FAB$M_CTG

Perform the create and connect, and return status

CREATE_CONTIG = SYS$CREATE(FAB)

IF (.NOT. CREATE_CONTIG) RETURN

CREATE_CONTIG = SYS$CONNECT(RAB)

RETURN

END FUNCTION CREATE_CONTIG

11.4.2 RMS Control Structures

Use of the USEROPEN keyword has some restrictions. The Run-Time Library constructs the following RMS control structures before calling the USEROPEN procedure:

FAB

RAB

NAM

XAB

ESA

RSA

File Access Block

Record Access Block

Name Block

Extended Attributes Blocks

Expanded String Area

Resultant String Area

A USEROPEN procedure should not alter the allocation of these structures, although it can modify the contents of many of the fields. Your procedure can also add additional XAB control blocks by linking them anywhere into the XAB chain. You must exercise caution when changing fields that have been set as a result of HP Fortran keywords, because the Run-Time Library may not be aware of the changes. For example, do not attempt to change the record size in your USEROPEN procedure; instead, use the HP Fortran keyword RECL.

Always use an OPEN statement keyword if one is available.

11–24 Using OpenVMS Record Management Services

Although the FAB, RAB, and NAM blocks remain defined during the time that the unit is opened, the XAB blocks are present only until the file has been successfully opened. The locations of the ESA and RSA strings are changed after the file is opened, so your USEROPEN procedure should not store the addresses of the RMS control structures. Instead, have your program call

FOR$RAB to obtain the address of the RAB once the file is opened and then access the other structures through the RAB.

Note

Future releases of the Run-Time Library may alter the use of some

RMS fields. Therefore, you may have to alter your USEROPEN procedures accordingly.

Table 11–1 shows which FAB and RAB fields are either initialized before your USEROPEN procedure is called or examined upon return from your

USEROPEN procedure. All fields are initialized in response to OPEN statement keywords or default to zero. Fields labeled with a hyphen ( - ) are initialized to zero. Fields labeled with an asterisk ( * ) are returned by

RMS.

Table 11–1 RMS Fields Available with USEROPEN

Field Name Description HP Fortran OPEN Keyword and Value

FAB$B_ACMODES

FAB$L_ALQ

FAB$B_BKS

FAB$W_BLS

FAB$V_CHAN_

MODE

FAB$L_CTX

FAB$W_DEQ

FAB$L_DEV

File access modes

Allocation quantity

Bucket size

Block size

Channel access mode protection

(2-bit subfield in FAB$B_

ACMODES)

Context

Default file extension quantity

Device characteristics

Contains FAB$V_CHAN_MODE and FAB$V_

LNM_MODE.

n if INITIALSIZE=n

(BLOCKSIZE + 511)/512 n if BLOCKSIZE=n

0=usermode

– n if EXTENDSIZE=n

(continued on next page)

Using OpenVMS Record Management Services 11–25

Table 11–1 (Cont.) RMS Fields Available with USEROPEN

Field Name Description HP Fortran OPEN Keyword and Value

FAB$L_DNA

FAB$B_DNS

Default file specification string address

UNIT=nnn

Set to FORnnn.DAT or FORREAD.DAT,

FORACCEPT.DAT, FORTYPE.DAT, or

FORPRINT.DAT or to default file specification string

Set to length of default file specification string

FAB$B_FAC

Default file specification string size

File access

FAB$L_FNA File specification string address

READONLY

Set to 0 if READONLY (RMS default), else set to FAB$M_GET + FAB$M_PUT + FAB$M_

UPD + FAB$M_TRN + FAB$M_DEL

FILE=filename if FILE present, else set to FORnnn, FOR$READ, FOR$ACCEPT,

FOR$TYPE, FOR$PRINT, SYS$INPUT, or

SYS$OUTPUT

Set to length of file specification string FAB$B_FNS

FAB$L_FOP

FAB$V_ASY

FAB$V_CBT

FAB$V_CIF

File specification string size

File processing options

Asynchronous operation

Contiguous best try

Create if nonexistent

FAB$V_CTG

FAB$V_DFW

FAB$V_DLT

FAB$V_KFO

FAB$V_MXV

FAB$V_NAM

FAB$V_NEF

FAB$V_NFS

FAB$V_OFP

FAB$V_POS

FAB$V_PPF

Contiguous allocation

Deferred write

Delete on close service

Known file open

Maximize version number

Name block inputs

Not positioned at end of file

Not file structured

Output file parse

Current position (after closed file)

Process permanent file

– (not used)

1 if INITIALSIZE=n

1 if READONLY not specified and

STATUS= ’ UNKNOWN ’ or STATUS omitted

–

Set at Fortran close, depending upon DISP keyword in OPEN or CLOSE, or STATUS keyword in CLOSE

–

1 unless ACCESS= ’ APPEND ’

–

(continued on next page)

11–26 Using OpenVMS Record Management Services

Table 11–1 (Cont.) RMS Fields Available with USEROPEN

Field Name Description HP Fortran OPEN Keyword and Value

FAB$V_RCK

FAB$V_RWC

FAB$V_RWO

FAB$V_SCF

FAB$V_SPL

FAB$V_SQO

Read check

Rewind on close service

Rewind on open service

Submit command (when closed)

Spool to printer

Sequential only

–

Set at Fortran close, depending upon DISP keyword in OPEN or CLOSE, or STATUS keyword in CLOSE

1 if a network file and ACCESS=

’ SEQUENTIAL ’ or ’ APPEND ’ , else 0

–

* (not used)

FAB$V_SUP

FAB$V_SYNCSTS

FAB$V_TEF

FAB$V_TMD

FAB$V_TMP

FAB$V_UFO

FAB$V_WCK

FAB$B_FSZ

FAB$W_IFI

FAB$W_GBC

Supersede

Immediate asynchronous completion

Truncate at end-of-file

Temporary, marked for delete

Temporary (file with no directory entry)

User file open or create file only

Write check

Fixed control area size

Internal file identifier

Global buffer count

FAB$B_JOURNAL Journal flags status

FAB$V_LNM_MODE Logical name translation access mode (subfield in FAB$B_

ACMODES)

FAB$L_MRN

FAB$W_MRS

Maximum record number

Maximum record size

FAB$L_NAM Name block address

–

1 if STATUS= ’ SCRATCH ’ , else 0

– n if MAXREC=n n if RECORDTYPE= ’ FIXED ’ or

ORGANIZATION= ’ RELATIVE ’ or = ’ INDEXED ’ , else 0

Set to address of name block; both the expanded and resultant string areas are set up, but the related filename string is not

(continued on next page)

Using OpenVMS Record Management Services 11–27

Table 11–1 (Cont.) RMS Fields Available with USEROPEN

Field Name Description HP Fortran OPEN Keyword and Value

FAB$B_ORG File organization FAB$C_IDX if ORGANIZATION=

’ INDEXED ’

FAB$C_REL if ORGANIZATION=

’ RELATIVE ’

FAB$C_SEQ if ORGANIZATION=

’ SEQUENTIAL ’ or omitted

FAB$B_RAT

FAB$V_FTN

Record attributes

Fortran carriage control

FAB$V_CR

FAB$V_BLK

FAB$B_RFM

Print LF and CR

Do not cross block boundaries

Record format

1 if CARRIAGECONTROL= ’ FORTRAN ’ or not specified

1 if CARRIAGECONTROL= ’ LIST ’

– (1 if NOSPANBLOCKS)

–

FAB$C_FIX if RECORDTYPE= ’ FIXED ’

FAB$C_VAR if RECORDTYPE= ’ VARIABLE ’

FAB$C_VAR if RECORDTYPE=

’ SEGMENTED ’

FAB$C_STM if RECORDTYPE= ’ STREAM ’

FAB$C_STMCR if RECORDTYPE=

’ STREAM_CR ’

FAB$C_STMLF if RECORDTYPE=

’ STREAM_LF ’

FAB$B_RTV

FAB$L_SDC

FAB$B_SHR

FAB$V_SHRPUT

FAB$V_SHRGET

FAB$V_SHRDEL

FAB$V_SHRUPD

FAB$V_NIL

FAB$V_UPI

FAB$V_MSE

FAB$L_STS

FAB$L_STV

Retrieval window size

Spooling device characteristics

File sharing

Allow other PUTs

Allow other GETs

Allow other DELETEs

Allow other UPDATEs

Allow no other operations

User-provided interlock

Multistream allowed

Completion status code

Status value

–

1 if SHARED

(continued on next page)

11–28 Using OpenVMS Record Management Services

Table 11–1 (Cont.) RMS Fields Available with USEROPEN

Field Name Description HP Fortran OPEN Keyword and Value

FAB$L_XAB

RAB$L_BKT

RAB$L_CTX

RAB$L_FAB

RAB$W_ISI

RAB$L_KBF

RAB$B_KRF

RAB$B_KSZ

RAB$B_MBC

RAB$B_MBF

RAB$L_PBF

RAB$B_PSZ

RAB$B_RAC

RAB$C_KEY

RAB$C_SEQ

RAB$C_RFA

RAB$L_RBF

RAB$L_RFA

RAB$L_RHB

RAB$L_ROP

RAB$V_ASY

RAB$V_BIO

RAB$V_CCO

Extended attribute block address

Bucket code

Context

FAB address

Internal stream ID

Key buffer address

Key of reference

Key size

Multiblock count

Multibuffer count

Prompt buffer address

Prompt buffer size

Record access mode

If ACCESS= ’ DIRECT ’ or

’ KEYED ’

If ACCESS= ’ SEQUENTIAL ’ or

’ APPEND ’ , or ACCESS omitted

–

Record buffer address

Record file address

Record header buffer

Record processing options

Asynchronous

Block I/O

Cancel CTRL/O

–

The XAB chain always has a File Header

Characteristics (FHC) extended attribute block in order to get longest record length (XAB$W_

LRL). If the KEY=keyword is specified, key index definition blocks will also be present.

HP may add additional XABs in the future.

Your USEROPEN procedure may insert XABs anywhere in the chain.

–

Set to address of FAB

Set to address of longword containing logical record number if ACCESS= ’ DIRECT ’

–

If BLOCKSIZE=n, use (n + 511)/512 n if BUFFERCOUNT=n

Set later

–

(continued on next page)

Using OpenVMS Record Management Services 11–29

Table 11–1 (Cont.) RMS Fields Available with USEROPEN

Field Name Description HP Fortran OPEN Keyword and Value

RAB$V_CVT

RAB$V_EOF

RAB$V_ETO

Convert to uppercase

End-of-file

Extended terminal (XABTRM) operation

Fast delete

Key greater than or equal to

–

1 if ACCESS= ’ APPEND ’

–

RAB$V_FDL

RAB$V_KGE or

RAB$V_EQNXT

RAB$V_KGT or

RAB$V_NXT

RAB$V_LIM

RAB$V_LOA

RAB$V_LOC

RAB$V_NLK

RAB$V_NXR

RAB$V_PMT

RAB$V_PTA

RAB$V_RAH

RAB$V_REA

RAB$V_RLK

RAB$V_RNE

RAB$V_RNF

RAB$V_RRL

RAB$V_SYNCSTS

RAB$V_TMO

RAB$V_TPT

RAB$V_UIF

RAB$V_ULK

RAB$V_WAT

RAB$V_WBH

Key greater than

Limit

Load buckets according to fill size

Locate mode

No lock

Nonexistent record

Prompt

Purge type-ahead

Read-ahead

Lock record for read

Lock record for write

Read no echo

Read no filter

Read regardless of lock

Immediate asynchronous completion

Timeout

Truncate on PUT

Update if

Manual unlocking

Wait for locked record

Write-behind

–

* (not used)

–

1 if ACCESS= ’ DIRECT ’

–

(continued on next page)

11–30 Using OpenVMS Record Management Services

Table 11–1 (Cont.) RMS Fields Available with USEROPEN

Field Name Description HP Fortran OPEN Keyword and Value

RAB$W_RSZ

RAB$L_STS

RAB$L_STV

RAB$B_TMO

RAB$L_UBF

RAB$W_USZ

RAB$L_XAB

Record size

Completion status code

Status value

Timeout period

User record area address

User record area size

Extended attribute block address

–

Set later

The XAB chain allows you to set or obtain additional information about an I/O operation.

RMS does not allow multiple instances of the same type XAB. To be compatible with future releases of the Run-Time Library, your procedure should scan the

XAB chain for XABs of the type to be inserted. If one is found, it should be used instead.

11.5 Example of Block Mode I/O

The following example shows a complete application that calls the RMS block I/O services SYS$WRITE and SYS$READ directly from HP Fortran. A complete program called BIO.F90 writes out an array of REAL*8 values to a file using SYS$WRITE, closes the file, and then reads the data back in using

SYS$READ operations with a different I/O transfer size. This program consists of five routines:

BIO

BIOCREATE

BIOREAD

OUTPUT

INPUT

Main control program

USEROPEN routine to create the file

USEROPEN routine to open the file for READ access

Function that actually outputs the array

Function that actually reads the array and checks it

Using OpenVMS Record Management Services 11–31

11.5.1 Main Block Mode I/O Program—BIO

The following main program specifies the USEROPEN specifier in its OPEN statements.

File: BIO.F90

Program to demonstrate the use of RMS Block I/O operations from HP Fortran

PROGRAM BIO

Declare the Useropen routines as external

EXTERNAL BIOCREATE, BIOREAD

Declare status variable, functions, and unit number

LOGICAL (KIND=4) STATUS, OUTPUT, INPUT

INTEGER (KIND=4) IUN/1/

Open the file !

OPEN(UNIT=IUN, FILE=’BIODEMO.DAT’, FORM=’UNFORMATTED’, &

STATUS=’NEW’, RECL=128, BLOCKSIZE=512, ORGANIZATION=’SEQUENTIAL’, &

IOSTAT=IOS, ACCESS=’SEQUENTIAL’, RECORDTYPE=’FIXED’, &

USEROPEN=BIOCREATE, INITIALSIZE=100)

IF (IOS .NE. 0) STOP ’Create failed’

Now perform the output

STATUS = OUTPUT(%VAL(FOR$RAB(IUN)))

IF (.NOT. STATUS) STOP ’Output failed’

Close the file for output

CLOSE (UNIT=IUN)

Confirm output complete

TYPE *, ’Output complete, file closed’

Now open the file for input

OPEN(UNIT=IUN, FILE=’BIODEMO.DAT’, FORM=’UNFORMATTED’, &

STATUS=’OLD’, IOSTAT=IOS, USEROPEN=BIOREAD, DISP=’DELETE’)

IF (IOS .NE. 0) STOP ’Open for read failed’

Now read the file back

STATUS = INPUT(%VAL(FOR$RAB(IUN)))

IF (.NOT. STATUS) STOP ’Input failed’

Success, output that all is well

STOP ’Correct completion of Block I/O demo’

END PROGRAM BIO

11–32 Using OpenVMS Record Management Services

" The error processing in this example routine is very crude; the program simply stops with an indicator of where the problem occurred. In real programs, you should provide more extensive error processing and reporting functions.

Most of the necessary OPEN options for the file are specified with

OPEN statement parameters. This is recommended whenever an OPEN statement qualifier exists to perform the desired function because it allows the HP Fortran RTL I/O processing routines to issue appropriate error messages when an RMS routine returns an error status.

Note the discrepancy between RECL and BLOCKSIZE in the first OPEN statement. Both keywords specify 512 bytes, but the number given for

RECL is 128. This is because the unit implied in the RECL keyword is longwords for unformatted files.

When using Block I/O mode, the blocksize used in the I/O operations is determined by the routine that actually does the operation. The OUTPUT routine actually transfers two 512-byte blocks at a time; the INPUT routine actually transfers four 512-byte blocks at once (see Section 11.5.2).

In general, the larger the transfers, the more efficiently the I/O is performed. The maximum I/O transfer size allowed by RMS is 65535 bytes.

The intrinsic function FOR$RAB is used to supply the appropriate RAB address to the OUTPUT and INPUT routines. The %VAL function is used to transform the address returned by the FOR$RAB intrinsic function to the proper argument passing mechanism. This allows the dummy argument RAB in INPUT and OUTPUT to be addressed properly.

11.5.2 Block Mode I/O USEROPEN Functions—BIOCREATE and

BIOREAD

The only condition required for block I/O is the setting of the BIO bit in the

File Access field of the FAB, using the normal declarations needed to define the symbols properly. If you wish to perform both block and record I/O on the file without closing it, you need to set the BRO bit as well. For more information on mixing block and record mode I/O, see the OpenVMS Record

Management Services Reference Manual. Note that the only difference between

BIOCREATE and BIOREAD is the use of SYS$CREATE and SYS$OPEN services, respectively.

Using OpenVMS Record Management Services 11–33

! Procedure name: BIOCREATE

! USEROPEN routine to set the Block I/O bit and create the BLOCK I/O file.

INTEGER FUNCTION BIOCREATE(FAB, RAB, LUN)

INTEGER LUN

Declare the necessary interface names

INCLUDE ’($FABDEF)’

INCLUDE ’($RABDEF)’

INCLUDE ’($SYSSRVNAM)’

Declare the FAB and RAB blocks

RECORD /FABDEF/ FAB, /RABDEF/ RAB

! Set the Block I/O bit in the FAC (GET and PUT bits set by RTL)

FAB.FAB$B_FAC = FAB.FAB$B_FAC .OR. FAB$M_BIO

! Now do the Create and Connect

BIOCREATE = SYS$CREATE(FAB)

IF (.NOT. BIOCREATE) RETURN

BIOCREATE = SYS$CONNECT(RAB)

IF (.NOT. BIOCREATE) RETURN

! Nothing more to do at this point, just return

RETURN

END FUNCTION BIOCREATE

! Procedure name: BIOREAD

! USEROPEN routine to set the Block I/O bit and open the Block I/O demo

! file for reading

INTEGER FUNCTION BIOREAD(FAB, RAB, LUN)

INTEGER LUN

! Declare the necessary interface names

INCLUDE ’($FABDEF)’

INCLUDE ’($RABDEF)’

INCLUDE ’($SYSSRVNAM)’

! Declare the FAB and RAB blocks

RECORD /FABDEF/ FAB, /RABDEF/ RAB

! Set the Block I/O bit in the FAC (GET and PUT bits set by RTL)

FAB.FAB$B_FAC = FAB.FAB$B_FAC .OR. FAB$M_BIO

! Now do the Open and Connect

11–34 Using OpenVMS Record Management Services

BIOREAD = SYS$OPEN(FAB)

IF (.NOT. BIOREAD) RETURN

BIOREAD = SYS$CONNECT(RAB)

IF (.NOT. BIOREAD) RETURN

Nothing more to do at this point, just return

RETURN

END FUNCTION BIOREAD

11.5.2.1 OUTPUT Routine

The following routine initializes the array A and performs the SYS$WRITE operations. Beyond the normal RTL initialization, only the RSZ and RBF fields in the RAB need to be initialized in order to perform the SYS$WRITE operations. The %LOC function is used to create the address value required in the RBF field.

One of the main reasons that block mode I/O is so efficient is that it avoids copy operations by using the data areas of the program directly for the output buffer. When writing to a disk device, the program must specify a value for

RSZ that is a multiple of 512 or else the final block would be only partly filled.

! Procedure name: OUTPUT

! Function to output records in block I/O mode

LOGICAL FUNCTION OUTPUT(RAB)

Declare RMS names

INCLUDE ’($RABDEF)’

INCLUDE ’($SYSSRVNAM)’

Declare the RAB

RECORD /RABDEF/ RAB

! Declare the Array to output

REAL(KIND=8) A(6400)

Declare the status variable

INTEGER(KIND=4) STATUS

Initialize the array

DO I=6400,1,-1

A(I) = I

ENDDO

! Now, output the array, two 512-byte (64 elements) blocks at a time

OUTPUT = .FALSE.

RAB.RAB$W_RSZ = 1024

DO I=0,99,2

Using OpenVMS Record Management Services 11–35

! For each block, set the buffer address to the proper array element

RAB.RAB$L_RBF = %LOC(A(I*64+1))

STATUS = SYS$WRITE(RAB)

IF (.NOT. STATUS) RETURN

ENDDO

Successful output completion

OUTPUT = .TRUE.

RETURN

END FUNCTION OUTPUT

11.5.2.2 INPUT Routine

The following routine reads the array A from the file and verifies its values.

The USZ and UBF fields of the RAB are the only fields that need to be initialized. The I/O transfer size is twice as large as the OUTPUT routine.

This can be done because the OUTPUT routine writes an integral number of

512-byte blocks to a disk device. This method cannot be used if the writing routine either specifies an RSZ that is not a multiple of 512 or attempts to write to a magnetic tape device.

! Procedure name: INPUT

! Function to input records in block I/O mode

LOGICAL FUNCTION INPUT(RAB)

! Declare RMS names

INCLUDE ’($RABDEF)’

INCLUDE ’($SYSSRVNAM)’

! Declare the RAB

RECORD /RABDEF/ RAB

! Declare the Array to output

REAL(KIND=8) A(6400)

Declare the status variable

INTEGER(KIND=4) STATUS

! Now, read the array, four 512-byte (64 elements) blocks at a time

INPUT = .FALSE.

RAB.RAB$W_USZ = 2048

DO I=0,99,4

! For each block, set the buffer address to the proper array element

RAB.RAB$L_UBF = %LOC(A(I*64+1))

STATUS = SYS$READ(RAB)

IF (.NOT. STATUS) RETURN

ENDDO

11–36 Using OpenVMS Record Management Services

Successful input completion if data is correct

DO I=6400,1,-1

IF (A(I) .NE. I) RETURN

ENDDO

INPUT = .TRUE.

RETURN

END FUNCTION INPUT

Using OpenVMS Record Management Services 11–37

Using Indexed Files

This chapter describes:

• Section 12.1, Overview of Indexed Files

• Section 12.2, Creating an Indexed File

• Section 12.3, Writing Records to an Indexed File

• Section 12.4, Reading Records from an Indexed File

• Section 12.5, Updating Records in an Indexed File

• Section 12.6, Deleting Records from an Indexed File

• Section 12.7, Current Record and Next Record Pointers

• Section 12.8, Exception Conditions When Using Indexed Files

12.1 Overview of Indexed Files

Sequential and direct access have traditionally been the only file access modes available to Fortran programs. To overcome some of the limitations of these access modes, HP Fortran supports a third access mode, called keyed access, which allows you to retrieve records, at random or in sequence, based on key fields that are established when you create a file with indexed organization.

(See Section 6.9.2 for details about keyed access mode.)

You can access files with indexed organization using sequential access or keyed access, or a combination of both.

• Keyed access retrieves records randomly based on the particular key fields and key values that you specify.

• Sequential access retrieves records in a sequence based on the direction of the key and on the values within the particular key field that you specify.

Using Indexed Files 12–1

Once you have read a record by means of an indexed read request, you can then use a sequential read request to retrieve records with ascending key field values, beginning with the key field value in the record retrieved by the initial read request.

Indexed organization is especially suitable for maintaining complex files in which you want to select records based on one of several criteria. For example, a mail-order firm could use an indexed organization file to store its customer list. Key fields could be a unique customer order number, the customer’s zip code, and the item ordered. Reading sequentially based on the zip-code key field would enable you to produce a mailing list sorted by zip code. A similar operation based on customer-order-number key field or item-number key field would enable you to list the records in sequences of customer order numbers or item numbers.

12.2 Creating an Indexed File

You can create a file with an indexed organization by using either of these methods:

• Use the Fortran OPEN statement to specify the file options supported by

HP Fortran.

• Use the RMS EDIT/FDL Utility to select features not directly supported by

HP Fortran.

Any indexed file created with EDIT/FDL can be accessed by HP Fortran I/O statements.

When you create an indexed file, you define certain fields within each record as key fields. The primary key, identified as key number zero, must be present as a field in every record. Alternate keys are numbered from 1 through 254.

An indexed file can have as many as 255 key fields (1 primary key and up to 254 alternate keys) defined. In practice, however, few applications require more than 3 or 4 key fields.

The data types used for key fields must be INTEGER (KIND=1), INTEGER

(KIND=2), INTEGER (KIND=4), INTEGER (KIND=8), or CHARACTER.

In designing an indexed file, you must decide the byte positions of the key fields. For example, in creating an indexed file for use by a mail-order firm, you might define a file record to consist of the following fields:

12–2 Using Indexed Files

STRUCTURE /FILE_REC_STRUCT/

INTEGER(KIND=4) ORDER_NUMBER

CHARACTER(LEN=20) NAME

CHARACTER(LEN=20)

CHARACTER(LEN=2)

ADDRESS

CHARACTER(LEN=19) CITY

STATE

CHARACTER(LEN=9) ZIP_CODE

! Positions 1:4, key 0

! Positions 5:24

! Positions 25:44

! Positions 45:63

! Positions 64:65

! Positions 66:74, key 1

INTEGER(KIND=2) ITEM_NUMBER ! Positions 75:76, key 2

END STRUCTURE

RECORD /FILE_REC_STRUCT/ FILE_REC

Instead of using a record structure, you can define a the fields of a record using a derived-type definition with the SEQUENCE statement:

TYPE FILE_REC

SEQUENCE

INTEGER(KIND=4) ORDER_NUMBER

CHARACTER(LEN=20) NAME

CHARACTER(LEN=20)

CHARACTER(LEN=2)

ADDRESS

CHARACTER(LEN=19) CITY

STATE

CHARACTER(LEN=9) ZIP_CODE

! Positions 1:4, key 0

! Positions 5:24

! Positions 25:44

! Positions 45:63

! Positions 64:65

! Positions 66:74, key 1

INTEGER(KIND=2) ITEM_NUMBER ! Positions 75:76, key 2

END TYPE FILE_REC

Given this record definition, you can use the following OPEN statement to create an indexed file:

OPEN (UNIT=10, FILE=’CUSTOMERS.DAT’, STATUS=’NEW’, &

ORGANIZATION=’INDEXED’, ACCESS=’KEYED’, RECORDTYPE=’VARIABLE’, &

FORM=’UNFORMATTED’, RECL=19, &

KEY=(1:4:INTEGER, 66:74:CHARACTER, 75:76:INTEGER), &

IOSTAT=IOS, ERR=9999)

This OPEN statement establishes the attributes of the file, including the definition of a primary key and two alternate keys. The definitions of the integer keys do not explicitly state INTEGER (KIND=4) and INTEGER

(KIND=2). The data type sizes are determined by the number of character positions allotted to the key fields (4- and 2-digit positions in this case respectively).

If you specify the KEY keyword when opening an existing file, the key specification that you give must match that of the file.

Using Indexed Files 12–3

HP Fortran uses RMS default key attributes when creating an indexed file.

These defaults are as follows:

• The values in primary key fields cannot be changed when a record is rewritten. Duplicate values in primary key fields is prohibited.

• The values in alternate key fields can be changed. Duplicate values in alternate key fields is permitted.

You can use the EDIT/FDL Utility or a USEROPEN routine to override these defaults and to specify other values not supported by HP Fortran, such as null key field values, null key names, and key data types other than integer and character.

For More Information:

• On the use of the USEROPEN keyword in OPEN statements, see the HP

Fortran for OpenVMS Language Reference Manual.

• On indexed file options, see the OpenVMS Record Management Services

Reference Manual.

• On the EDIT/FDL Utility, see the VMS File Definition Language Facility

Manual and the Guide to OpenVMS File Applications.

12.3 Writing Records to an Indexed File

You can write records to an indexed file with either formatted or unformatted indexed WRITE statements. Each write operation inserts a new record into the file and updates the key indexes so that the new record can be retrieved in a sequential order based on the values in the respective key fields.

For example, you could add a new record to the file for the mail-order firm (see

Section 12.2) with the following statement:

WRITE (UNIT=10,IOSTAT=IOS,ERR=9999) FILE_REC

12.3.1 Duplicate Values in Key Fields

It is possible to write two or more records with the same value in a single key field. The attributes specified for the file when it was created determine whether this duplication is allowed. By default, HP Fortran creates files that allow duplicate alternate key field values and prohibit duplicate primary key field values. If duplicate key field values are present in a file, the records with equal values are retrieved on a first-in/first-out basis.

12–4 Using Indexed Files

For example, assume that five records are written to an indexed file in this order (for clarity, only key fields are shown):

ORDER_NUMBER

1023

942

903

1348

1263

ZIP_CODE

70856

02163

14853

44901

33032

ITEM_NUMBER

375

2736

375

1047

690

If the file is later opened and read sequentially by primary key (ORDER_

NUMBER), the order in which the records are retrieved is not affected by the duplicated value (375) in the ITEM_NUMBER key field. In this case, the records would be retrieved in the following order:

ORDER_NUMBER

903

942

1023

1263

1348

ZIP_CODE

14853

02163

70856

33032

44901

ITEM_NUMBER

375

2736

375

690

1047

However, if the read operation is based on the second alternate key (ITEM_

NUMBER), the order in which the records are retrieved is affected by the duplicate key field value. In this case, the records would be retrieved in the following order:

ORDER_NUMBER

1023

903

1263

1348

942

ZIP_CODE

70856

14853

33032

44901

02163

ITEM_NUMBER

375

690

1047

2736

The records containing the same key field value (375) are retrieved in the order in which they were written to the file.

Using Indexed Files 12–5

12.3.2 Preventing the Indexing of Alternate Key Fields

When writing to an indexed file that contains variable-length records, you can prevent entries from being added to the key indexes for any alternate key fields. This is done by omitting the names of the alternate key fields from the

WRITE statement. The omitted alternate key fields must be at the end of the record; another key field cannot be specified after the omitted key field.

For example, the last record (ORDER_NUMBER 1263) in the mail-order example could be written with the following statement:

WRITE (UNIT=10,IOSTAT=IOS,ERR=9999) FILE_REC.ORDER_NUMBER, FILE_REC.NAME, &

FILE_REC.ADDRESS, FILE_REC.CITY, FILE_REC.STATE, FILE_REC.ZIP_CODE

Because the field name FILE_REC.ITEM_NUMBER is omitted from the

WRITE statement, an entry for that key field is not created in the index. As a result, an attempt to read the file using the alternate key ITEM_NUMBER would not retrieve the last record and would produce the following listing:

ORDER_NUMBER

1023

903

1348

942

ZIP_CODE

70856

14853

44901

02163

ITEM_NUMBER

375

1047

2736

You can omit only trailing alternate keys from a record; the primary key must always be present.

12.4 Reading Records from an Indexed File

You can read records in an indexed file with either sequential or indexed

READ statements (formatted or unformatted) under the keyed mode of access.

By specifying ACCESS= ’ KEYED ’ in the OPEN statement, you enable both sequential and keyed access to the indexed file.

Indexed READ statements position the file pointers (see Section 12.7) at a particular record, determined by the key field value, the key-of-reference, and the match criterion. Once you retrieve a particular record by an indexed READ statement, you can then use sequential access READ statements to retrieve records with increasing key field values.

12–6 Using Indexed Files

The form of the external record’s key field must match the form of the value you specify in the KEY keyword. If the key field contains character data, you should specify the KEY keyword value as a CHARACTER data type. If the key field contains binary data, then the KEY keyword value should be of INTEGER data type.

If you write a record to an indexed file with formatted I/O, the data type is converted from its internal representation to an external representation. As a result, the key value must be specified in the external form when you read the data back with an indexed read. Otherwise, a match will occur when you do not expect it.

The following HP Fortran program segment prints the order number and zip code of each record where the first five characters of the zip code are greater than or equal to

’

10000

’ but less than

’

50000

’

! Read first record with ZIP_CODE key greater than or equal to ’10000’.

READ (UNIT=10,KEYGE=’10000’,KEYID=1,IOSTAT=IOS,ERR=9999) FILE_REC

While the zip code previously read is within range, print the

order number and zip code, then read the next record.

DO WHILE (FILE_REC.ZIP_CODE .LT. ’50000’)

PRINT *, ’Order number’, FILE_REC.ORDER_NUMBER, ’has zip code’, &

FILE_REC.ZIP_CODE

READ (UNIT=10,IOSTAT=IOS,END=200,ERR=9999) FILE_REC

! END= branch will be taken if there are no more records in the file.

END DO

200 CONTINUE

The error branch on the keyed READ in this example is taken if no record is found with a zip code greater than or equal to

’

10000

’

; an attempt to access a nonexistent record is an error. If the sequential READ has accessed all records in the file, an end-of-file status occurs, as with other file organizations.

If you want to detect a failure of the keyed READ, you can examine the I/O status variable, IOS, for the appropriate error number (see Table 7–1 for a list of the returned error codes).

12.5 Updating Records in an Indexed File

The REWRITE statement updates existing records in an indexed file. You cannot replace an existing record simply by writing it again; a WRITE statement would attempt to add a new record.

An update operation is accomplished in two steps:

You must read the record in order to make it the current record.

Using Indexed Files 12–7

You execute the REWRITE statement.

For example, to update the record containing ORDER_NUMBER 903 (see prior examples) so that the NAME field becomes ’ Theodore Zinck ’ , you might use the following Fortran code segment:

READ (UNIT=10,KEY=903,KEYID=0,IOSTAT=IOS,ERR=9999) FILE_REC

FILE_REC.NAME = ’Theodore Zinck’

REWRITE (UNIT=10,IOSTAT=IOS,ERR=9999) FILE_REC

When you rewrite a record, key fields may change. The attributes specified for the file when it was created determine whether this type of change is permitted. The primary key value can never change on a REWRITE operation.

If necessary, delete the old record and write a new record.

12.6 Deleting Records from an Indexed File

The DELETE statement allows you to delete records from an indexed file. The

DELETE and REWRITE statements are similar; a record must first be locked by a READ statement before it can be operated on.

The following Fortran code segment deletes the second record in the file with

ITEM_NUMBER 375 (refer to previous examples):

READ (UNIT=10,KEY=375,KEYID=2,IOSTAT=IOS,ERR=9999)

READ (UNIT=10,IOSTAT=IOS,ERR=9999) FILE_REC

IF (FILE_REC.ITEM_NUMBER .EQ. 375) THEN

DELETE (UNIT=10, IOSTAT=IOS, ERR=9999)

ELSE

PRINT *, ’There is no second record.’

END IF

Deletion removes a record from all defined indexes in the file.

12.7 Current Record and Next Record Pointers

The RMS file system maintains two pointers into an open indexed file:

• The next record pointer indicates the record to be retrieved by a sequential read. When you open an indexed file, the next record pointer indicates the record with the lowest primary key field value. Subsequent sequential read operations cause the next record pointer to be the one with the next higher value in the same key field. In case of duplicate key field values, records are retrieved in the order in which they were written.

• The current record pointer indicates the record most recently retrieved by a READ operation; it is the record that is locked from access by other programs sharing the file.

12–8 Using Indexed Files

The current record is the one operated on by the REWRITE statement and the DELETE statement. The current record is undefined until a read operation is performed on the file. Any file operation other than a read causes the current record pointer to become undefined. Also, an error results if a rewrite or delete operation is performed when the current record pointer is undefined.

12.8 Exception Conditions When Using Indexed Files

You can expect to encounter certain exception conditions when using indexed files. The two most common of these conditions involve valid attempts to read locked records and invalid attempts to create duplicate keys. Provisions for handling both of these situations should be included in a well-written program.

When an indexed file is shared by several users, any read operation may result in a ‘‘specified record locked’’ error. One way to recover from this error condition is to ask if the user would like to reattempt the read. If the user’s response is positive, then the program can go back to the READ statement.

For example:

INCLUDE ’($FORIOSDEF)’

100 READ (UNIT=10,IOSTAT=IOS) DATA

IF (IOS .EQ. FOR$IOS_SPERECLOC) THEN

TYPE *, ’That record is locked. Press RETURN’

TYPE *, ’to try again, or Ctrl/Z to discontinue’

READ (UNIT=*,FMT=*,END=900)

GO TO 100

ELSE IF (IOS .NE. 0) THEN

CALL ERROR (IOS)

END IF

You should avoid looping back to the READ statement without first providing some type of delay (caused by a request to try again, or to discontinue, as in this example). If your program reads a record but does not intend to modify the record, you should place an UNLOCK statement immediately after the

READ statement. This technique reduces the time that a record is locked and permits other programs to access the record.

The second exception condition, creation of duplicate keys, occurs when your program tries to create a record with a key field value that is already in use. When duplicate key field values are not desirable, you might have your program prompt for a new key field value whenever an attempt is made to create a duplicate. For example:

Using Indexed Files 12–9

INCLUDE ’($FORIOSDEF)’

200 WRITE (UNIT=10,IOSTAT=IOS) KEY_VAL, DATA

IF (IOS .EQ. FOR$IOS_INCKEYCHG) THEN

TYPE *, ’This key field value already exists. Please’

TYPE *, ’enter a different key field value, or press’

TYPE *, ’Ctrl/Z to discontinue this operation.’

READ (UNIT=*,FMT=300,END=999) KEY_VAL

GO TO 200

ELSE IF (IOS .NE. 0) THEN

CALL ERROR (IOS)

END IF

12–10 Using Indexed Files

Interprocess Communication

This chapter describes how to exchange and share data between local and remote processes:

• Section 13.1, HP Fortran Program Section Usage

• Section 13.2, Local Processes: Sharing and Exchanging Data

• Section 13.3, Remote Processes: Sharing and Exchanging Data

Local processes involve a single OpenVMS processor, and remote processes involve separate processors that are interconnected by means of DECnet.

13.1 HP Fortran Program Section Usage

You may need to change program section attributes to allow shared access to an installed shareable image.

The storage required by an HP Fortran program unit is allocated in contiguous areas called program sections (PSECTs). The HP Fortran compiler implicitly declares these PSECTs:

• $CODE$

• $DATA$

• $BSS$

• $LITERAL$

• $LINK$

Each common block you declare causes allocation of a PSECT with the same name as the common block. (The unnamed common block PSECT is named $BLANK.) Memory allocation and sharing are controlled by the linker according to the attributes of each PSECT; PSECT names and attributes are listed in Table 13–1.

Interprocess Communication 13–1

Each procedure in your program is named according to the name specified in the PROGRAM, BLOCK DATA, FUNCTION, or SUBROUTINE statement used in creating the object module. The defaults applied to PROGRAM and BLOCK

DATA statements are source-file-name$MAIN and source-file-name$DATA, respectively.

Table 13–1 PSECT Names and Attributes

PSECT

Name

$CODE$

Use

Executable code

$LINK$

$DATA$

Linkage information (procedure descriptors, linkage pairs, and literals)

Initialized user local static variables and compiler temporary variables

$BSS$ Uninitialized user local variables and compiler temporary variables

$LITERAL$ Literals used in FORMAT statements

$BLANK Blank common block names Named common blocks

Attributes

PIC, CON, REL, LCL, SHR, EXE, NORD,

NOWRT, OCTA

NOPIC, CON, REL, LCL, NOSHR, NOEXE,

RD, NOWRT, OCTA

NOPIC, CON, REL, LCL, NOSHR, NOEXE,

RD, WRT, OCTA

NOPIC, CON, REL, LCL, NOSHR, NOEXE,

RD, WRT, OCTA

NOPIC, CON, REL, LCL, NOSHR, NOEXE,

RD, WRT, OCTA

NOPIC, OVR, REL, GBL, NOSHR, NOEXE,

RD, WRT, OCTA

NOPIC, OVR, REL, GBL, NOSHR, NOEXE,

RD, WRT, OCTA

You can use the cDEC$ PSECT (such as !DEC$ PSECT) directive or use a linker options file to change some of the attributes of a common block.

Table 13–2 describes the meanings of HP Fortran PSECT attributes.

13–2 Interprocess Communication

Table 13–2 HP Fortran PSECT Attributes

Attribute Meaning

PIC/NOPIC

CON/OVR

REL/ABS

GBL/LCL

SHR/NOSHR

EXE/NOEXE

RD/NORD

WRT/NOWRT

LONG/QUAD/OCTA

Position independent or position dependent code

Concatenated or overlaid

Relocatable or absolute

Global or local scope

Shareable or nonshareable

Executable or nonexecutable

Readable or nonreadable (reserved by HP)

Writable or nonwritable

Longword, quadword, or octaword alignment

When the linker constructs an executable image, it divides the executable image into sections. Each image section contains PSECTs that have the same attributes. By arranging image sections according to PSECT attributes, the linker is able to control memory allocation. The linker allows you to allocate memory to your own specification by means of commands you include in an options file that is input to the linker.

For More Information:

• On the cDEC$ PSECT (!DEC$ PSECT) compiler directive statement, see the HP Fortran for OpenVMS Language Reference Manual.

• On examples of linker options files used for shared installed common data, see Section 13.2.2.

• On the linker options file and special program sections, see the HP

OpenVMS Linker Utility Manual.

13.2 Local Processes: Sharing and Exchanging Data

Interprocess communication mechanisms provided for local processes include the following capabilities:

• Program image sharing in shareable image libraries

• Data sharing in installed common areas

• Information passing by means of mailboxes

• Information passing over DECnet network links

These capabilities are discussed in the sections that follow.

Interprocess Communication 13–3

VOLATILE declarations are required when you use certain run-time features of the operating system, including values that can be read or written by methods other than direct assignment, or during a routine call.

If a variable can be accessed using rules in addition to those provided by the standard Fortran 90/95 language, declare the variable as VOLATILE.

For example, if a variable in COMMON can change value by means of an

OpenVMS AST routine or condition handler, you must declare that common block variable or the entire COMMON block as volatile.

Consider the following uses of variables as candidates for a VOLATILE declaration if asynchronous access might occur:

• Variables in common blocks

• Variables in modules

• Addresses not saved by the %LOC built-in function

• Variables with the TARGET attribute

• Variables declared with the SAVE statement in recursive routines

• Dummy arguments

Alternatively, if the only local accesses occur when the variable is passed as a dummy argument, the command-line option /ASSUME=DUMMY_

ALIASES can be used instead of a VOLATILE declaration (see

Section 5.8.9).

• Variables in shared global sections

13.2.1 Sharing Images in Shareable Image Libraries

If you have a routine that is invoked by more than one program, you should consider establishing it as a shareable image and installing it on your system.

Establishing a routine as a shareable image provides the following benefits:

• Saves disk space: The executable images to which the shareable image is linked do not actually include the shareable image. Only one copy of the shareable image exists.

• Simplifies maintenance: If you use symbol vectors, you can modify, recompile, and relink a shareable image without having to relink the executable images that reference it.

Installing a shareable image as shared (INSTALL command, /SHARED qualifier) can also save memory.

13–4 Interprocess Communication

The steps to creating and installing a shareable image are:

Compile the source file containing that routine that you want to establish as a shareable image.

Link the shareable image object file that results from step 1, specifying any object files that contain routines referenced by the shareable image object file.

The OpenVMS Linker provides a variety of options that you should consider before performing the link operation. For detailed information on shareable images and linker options, see the HP OpenVMS Linker Utility

Manual.

Create a shareable image library using the Library Utility’s LIBRARY command. For detailed information on creating shareable image libraries, see the Guide to Creating OpenVMS Modular Procedures.

Install the shareable image (the results of step 3) on your system as a shared image by using the Install Utility’s INSTALL command (with the

/SHARED qualifier). For detailed information on how to perform this operation, see the VMS Install Utility Manual.

Any programs that access a shareable image must be linked with that image.

When performing the link operation, you must specify one of the following items on your LINK command:

• The name of the shareable image library containing the symbol table of the shareable image. Use the /LIBRARY qualifier to identify a library file.

• A linker options file that contains the name of the shareable image file.

Use the /SHAREABLE qualifier to identify a shareable image file. (If you specify the /SHAREABLE qualifier on the LINK command line and you do not specify an options file, the linker creates a shareable image of the object file you are linking.)

The resulting executable image contains the contents of each object module and a pointer to each shareable image.

13.2.2 Sharing Data in Installed Common Areas

Sharing the same data among two or more processes can be done using installed common areas.

Typically, you use an installed common area for interprocess communication or for two or more processes to access the same data simultaneously.

Interprocess Communication 13–5

13.2.2.1 Creating and Installing the Shareable Image Common Area

To communicate between processes using a common area, first install the common area as a shareable image:

Create the common area: Write an HP Fortran program that declares the variables in the common area and defines the common area. This program should not contain executable code. For example:

COMMON /WORK_AREA/ WORK_ARRAY(8192)

END

This common area can use the BLOCK DATA statement.

When compiling the source file that contains the common block declarations, consistently use the /ALIGNMENT and /GRANULARITY qualifiers (see Section 13.2.2.3). For example:

$ FORTRAN/ALIGN=COMMONS=NATURAL/GRANULARITY=LONGWORD INC_COMMON.F90

Make the common area a shareable image: Compile the program containing the common area and use the LINK/SHAREABLE command to create a shareable image containing the common area. You need to specify a linker options file (shown here as SYS$INPUT to allow typed input) to specify the PSECT attributes of the COMMON block PSECT and include it in the global symbol table:

$ LINK/SHAREABLE INC_COMMON ,SYS$INPUT/OPTION

SYMBOL_VECTOR=(WORK_AREA=PSECT)

PSECT_ATTR=WORK_AREA,SHR

Ctrl/Z

With HP Fortran on OpenVMS Alpha systems, the default PSECT attribute for a common block is NOSHR (see Section 13.1). To use a shared installed common block, you must specify one of the following:

• The SHR attribute in a cDEC$ PSECT directive in the source file

• The SHR attribute in the linker options file for the shareable image to be installed and for each executable image that references the installed common block

If the !DEC$ PSECT (same as cDEC$ PSECT) directive specified the SHR attribute, the LINK command is as follows:

$ LINK/SHAREABLE INC_COMMON ,SYS$INPUT/OPTION

SYMBOL_VECTOR=(WORK_AREA=PSECT)

Ctrl/Z

The source line containing the !DEC$ PSECT directive is as follows:

!DEC$ PSECT /INC_COMMON/ SHR

13–6 Interprocess Communication

Copy the shareable image: Once created, you should copy the shareable image into SYS$SHARE: before it is installed. The file protection of the

.EXE file must allow write access for the processes running programs that will access the shareable image (shown for Group access in the following

COPY command):

$ COPY/LOG DISK$:[INCOME.DEV]INC_COMMON.EXE SYS$SHARE:*.*/PROTECTION=G:RWE

If you do not copy the installed shareable image to SYS$SHARE, before running executable images that reference the installed shareable common image, you must define a logical name that specifies the location of that image.

Install the shareable image: Using an account with CMKRNL privilege, invoke the interactive Install Utility. When the INSTALL> prompt appears, type a line containing the following: a.

The CREATE (or ADD) command b.

The complete file specification of the shareable image that contains the common area (file type defaults to EXE) c.

The qualifiers /WRITABLE and /SHARED

The Install utility installs your shareable image and reissues the

INSTALL> prompt. Type EXIT to exit. For example:

$ INSTALL

INSTALL> CREATE SYS$SHARE:INC_COMMON/WRITABLE/SHARED

INSTALL> EXIT

A disk containing an installed image cannot be dismounted until you invoke the Install Utility and type DELETE, followed by the complete file specification of the image.

For More Information:

• On default PSECT attributes, see Section 13.1.

• On the !DEC$ PSECT (cDEC$ PSECT) compiler directive statement, see the HP Fortran for OpenVMS Language Reference Manual.

• On the Install Utility, see the VMS Install Utility Manual.

• On synchronizing access to a common block installed as a shareable image, see Section 13.2.2.3.

• On the linker, see Chapter 3 and the HP OpenVMS Linker Utility Manual.

• On sharing common block data using a global section, see Section F.4 and the HP OpenVMS Programming Concepts Manual.

Interprocess Communication 13–7

• On page size differences between OpenVMS VAX and OpenVMS Alpha systems, see Migrating an Application from OpenVMS VAX to OpenVMS

Alpha.

13.2.2.2 Creating Programs to Access the Shareable Image Common Area

After the common area has been installed as a shareable image, use the following steps to access the data from any executable program:

Include the same variable declarations and common area declarations in the accessing program or programs.

All common block data declarations must be compatible wherever the common block is referenced.

Compile the program.

When compiling the program that contains the common block declarations, consistently use the same /ALIGNMENT and /GRANULARITY qualifiers used to compile the common block data declaration program that has been installed as a shareable image (see Section 13.2.2.3).

For example, assume the two programs named INCOME and REPORT that will access a common block WORK_AREA in the installed shareable image INC_COMMON:

$ FORTRAN/ALIGN=COMMONS=NATURAL/GRANULARITY=LONGWORD INCOME.F90

$ FORTRAN/ALIGN=COMMONS=NATURAL/GRANULARITY=LONGWORD REPORT.F90

Link the accessing program against the installed common area program.

You must use an options file to specify the common area program as a shareable image.

The following are LINK commands:

$ LINK INCOME, INCOME/OPTION

$ LINK REPORT, INCOME/OPTION

The linker options file INCOME.OPT contains the following lines:

INC_COMMON/SHAREABLE

PSECT_ATTR=WORK_AREA, SHR

If a !DEC$ PSECT (cDEC$ PSECT) directive specified the SHR PSECT attribute, the linker options file INCOME.OPT would contain the following line:

INC_COMMON/SHAREABLE

The source line containing the !DEC$ PSECT directive would be as follows:

!DEC$ PSECT /INC_COMMON/ SHR

13–8 Interprocess Communication

For each executable image that references the installed shareable image containing the shared common area, you must specify the SHR PSECT attribute by using either of these:

• !DEC$ PSECT (cDEC$ PSECT) directive

• Linker options file

The two programs access the same area of memory through the installed common block (program section name) WORK_AREA in the installed shareable image INC_COMMON.

If the installed image is not located in SYS$SHARE, you must define a logical name that specifies the location of that image. The logical name (in this example INC_COMMON) is the name of the installed image.

Execute the accessing program.

In the previous series of examples, the two programs INCOME and

REPORT access the same area of memory through the installed common block WORK_AREA in the installed shareable image INC_COMMON.

For More Information:

• On the /ALIGNMENT qualifier, see Section 2.3.3.

• On the /GRANULARITY qualifier, see Section 2.3.23.

• On intrinsic data types, see Chapter 8.

• On the Alpha architecture, see the Alpha Architecture Reference Manual.

• On the Itanium architecture, see the Intel Itanium Architecture Software

Developer’s Manual, Volume 1: Application Architecture.

13.2.2.3 Synchronizing Access

If more than one process or thread will write to a shared global section containing COMMON block data, the user program may need to synchronize access to COMMON block variables.

Compile all programs referencing the shared common area with the same value for the /ALIGNMENT and /GRANULARITY qualifiers. For example:

$ FORTRAN/ALIGN=COMMONS=NATURAL /GRANULARITY=LONGWORD INC_COMMON

Using /GRANULARITY=LONGWORD for 4-byte variables or

/GRANULARITY=QUADWORD for 8-byte variables ensures that adjacent data is not accidentally affected. To ensure access to 1-byte variables, specify

/GRANULARITY=BYTE. Because accessing data items less than four bytes slows run-time performance, you might want to consider synchronizing read and write access to the data on the same node.

Interprocess Communication 13–9

Typically, programs accessing shared data use common event flag clusters to synchronize read and write access to the data on the same node. In the simplest case, one event flag in a common event flag cluster might indicate that a program is writing data, and a second event flag in the cluster might indicate that a program is reading data. Before accessing the shared data, a program must examine the common event flag cluster to ensure that accessing the data does not conflict with an operation already in progress.

Other ways of synchronizing access on a single node include the OpenVMS lock manager system services (SYS$ENQ and SYS$DEQ), the hibernate and wake system services (SYS$HIBER and SYS$WAKE), or using Assembler code.

For More Information:

• On the use of event flags, see the HP OpenVMS System Services Reference

Manual.

• On sharing common block data using a global section, see Section F.4 and the HP OpenVMS Programming Concepts Manual.

• On page size differences between OpenVMS VAX and OpenVMS Alpha systems, see Migrating an Application from OpenVMS VAX to OpenVMS

Alpha.

• On the /ALIGNMENT qualifier, see Section 2.3.3.

• On the /GRANULARITY qualifier, see Section 2.3.23.

• On intrinsic data types, see Chapter 8.

• On the Alpha architecture, see the Alpha Architecture Reference Manual.

• On the Itanium architecture, see the Intel Itanium Architecture Software

Developer’s Manual, Volume 1: Application Architecture.

13.2.3 Creating and Using Mailboxes to Pass Information

It is often useful to exchange data between processes, as when synchronizing execution or sending messages.

A mailbox is a record-oriented pseudo I/O device that allows you to pass data from one process to another. Mailboxes are created by the Create Mailbox system service (SYS$CREMBX). The following sections describe how to create mailboxes and how to send and receive data using mailboxes.

13–10 Interprocess Communication

13.2.3.1 Creating a Mailbox

SYS$CREMBX creates the mailbox and returns the number of the I/O channel assigned to the mailbox. You must specify a variable for the I/O channel. You should also specify a logical name to be associated with the mailbox. The logical name identifies the mailbox for other processes and for HP Fortran I/O statements.

The SYS$CREMBX system service also allows you to specify the message and buffer sizes, the mailbox protection code, and the access mode of the mailbox; however, the default values for these arguments are usually sufficient.

The following segment of code creates a mailbox named MAILBOX. The number of the I/O channel assigned to the mailbox is returned in ICHAN.

INCLUDE ’($SYSSRVNAM)’

INTEGER (KIND=2) ICHAN

ISTATUS = SYS$CREMBX(,ICHAN,,,,,’MAILBOX’)

Note

Do not use MAIL as the logical name for a mailbox. If you do so, the system will not execute the proper image in response to the OpenVMS command MAIL.

13.2.3.2 Sending and Receiving Data Using Mailboxes

Sending data to and receiving data from a mailbox is like other forms of HP

Fortran I/O. The mailbox is simply treated as a record-oriented I/O device.

Use HP Fortran formatted sequential READ and WRITE statements to send and receive messages. The data transmission is performed synchronously; a program that writes a message to a mailbox waits until the message is read, and a program that reads a message from a mailbox waits until the message is written before it continues transmission. When the writing program closes the mailbox, an end-of-file condition is returned to the reading program.

Do not attempt to write a record of zero length to a mailbox; the program reading the mailbox interprets this record as an end-of-file. Zero-length records are produced by consecutive slashes in FORMAT statements.

The following sample program creates a mailbox assigned with the logical name MAILBOX. The program then performs an open operation specifying the logical name MAILBOX as the file to be opened. It then reads file names from

FNAMES.DAT and writes them to the mailbox until all of the records in the file have been transmitted.

Interprocess Communication 13–11

CHARACTER (LEN=64) FILENAME

INCLUDE ’($SYSSRVNAM)’

INTEGER (KIND=2) ICHAN

INTEGER (KIND=4) STATUS

STATUS = SYS$CREMBX(,ICHAN,,,,,’MAILBOX’)

IF (.NOT. STATUS) GO TO 99

OPEN (UNIT=9, FILE=’MAILBOX’, STATUS=’NEW’, &

CARRIAGECONTROL=’LIST’, ERR=99)

OPEN (UNIT=8, FILE=’FNAMES.DAT’, STATUS=’OLD’)

10 READ (8,100,END=98) FILENAME

WRITE (9,100) FILENAME

100 FORMAT(A)

GO TO 10

98 CLOSE (UNIT=8)

CLOSE (UNIT=9)

STOP

99 WRITE (6,*) ’Mailbox error’

STOP

END

The following sample program reads messages from a mailbox that was assigned the logical name MAILBOX when it was created. The messages comprise file names, which the program reads. The program then types the files associated with the file names.

CHARACTER(LEN=64) FILNAM

CHARACTER(LEN=123) TEXT

OPEN (UNIT=1, FILE=’MAILBOX’, STATUS=’OLD’)

1 READ (1,100,END=12) FILNAM

100 FORMAT (A)

OPEN (UNIT=2, FILE=FILNAM, STATUS=’OLD’)

OPEN (UNIT=3, FILE=’SYS$OUTPUT’, STATUS=’NEW’)

2 READ (2,100,END=10) TEXT

WRITE (3,100) TEXT

GO TO 2

10 CLOSE (UNIT=2)

CLOSE (UNIT=3)

GO TO 1

12 END

13–12 Interprocess Communication

For More Information:

• On calling system services, see Chapter 10.

• On the arguments supplied to the Create Mailbox system service, see the

HP OpenVMS System Services Reference Manual.

13.3 Remote Processes: Sharing and Exchanging Data

If your computer is a node in a DECnet network, you can communicate with other nodes in the network by means of standard HP Fortran I/O statements.

These statements let you exchange data with a program at the remote computer (task-to-task communication) and access files at the remote computer

(resource sharing). There is no apparent difference between these intersystem exchanges and the local interprocess and file access exchanges.

Remote file access and task-to-task communications are discussed separately in the sections that follow.

The system manager at the remote system needs to create the necessary network objects and security controls (such as proxy access). Network file specifications might need to use access control strings, depending on how the remote system access has been implemented.

For More Information:

• On OpenVMS system management, see the HP OpenVMS System

Manager’s Manual.

• On accessing files across networks, see the OpenVMS User’s Manual.

13.3.1 Remote File Access

To access a file on a remote system, include the remote node name in the file name specification. For example:

BOSTON::DBA0:[SMITH]TEST.DAT;2

To make a program independent of the physical location of the files it accesses, you can assign a logical name to the network file specification as shown in the following example:

$ DEFINE INVFILE MIAMI::DR4:[INV]INVENT.DAT

The logical name INVFILE now refers to the remote file and can be used in the program. For example:

OPEN (UNIT=10, FILE=’INVFILE’, STATUS=’OLD’)

Interprocess Communication 13–13

To process a file on the local network node, reassign the logical name; you do not need to modify the source program.

13.3.2 Network Task-to-Task Communication

Network task-to-task communication allows a program running on one network node to interact with a program running on another network node.

This interaction is accomplished with standard HP Fortran I/O statements and looks much like an interactive program/user session.

The steps involved in network task-to-task communications are:

Request the network connection. The originating program initiates task-to-task communication. It opens the remote task file with a special file name syntax: the name of the remote task file is preceded with TASK= and surrounded with quotation marks. For example:

BOSTON::"TASK=UPDATE"

Unless the remote task file is contained in the default directory for the remote node’s DECnet account, you must specify the pertinent account information (a user name and password) as part of the node name:

BOSTON"username password"::"TASK=UPDATE"

The form of the remote task file varies, depending on the remote computer’s operating system. For OpenVMS systems, this task file is a command file with a file type of COM. The network software submits the command file as a batch job on the remote system.

Complete the network connection. When the remote task starts, it must complete the connection back to the host. On OpenVMS systems, the remote task completes this connection by performing an open operation on the logical name SYS$NET. When opening the remote task file or

SYS$NET, specify either FORM= ’ UNFORMATTED ’ or the combination of

FORM= ’ FORMATTED ’ and CARRIAGECONTROL= ’ NONE ’ .

Exchange messages. When the connection is made between the two tasks, each program performs I/O using the established link.

Task-to-task communication is synchronous. This means that when one task performs a read, it waits until the other task performs a write before it continues processing.

Terminate the network connection. To prevent losing data, the program that receives the last message should terminate the network connection using the CLOSE statement. When the network connection is terminated, the cooperating image receives an end-of-file error.

13–14 Interprocess Communication

The following is a complete example showing how HP Fortran programs can exchange information over a network. The originating program prompts for an integer value and sends the value to the remote program. The remote program then adds one to the value and returns the value to the originating program.

It is assumed that the remote operating system is an OpenVMS system.

The originating program on the local node contains the following source code:

OPEN (UNIT=10, FILE=’PARIS::"TASK=REMOTE"’, STATUS=’OLD’, &

FORM=’UNFORMATTED’, ACCESS=’SEQUENTIAL’, IOSTAT=IOS, ERR=999)

Prompt for a number

PRINT 101

101 FORMAT ($,’ ENTER A NUMBER: ’)

ACCEPT *,N

Perform the network I/O

WRITE (UNIT=10, IOSTAT=IOS, ERR=900) N

READ (UNIT=10, IOSTAT=IOS, ERR=900) N

Display the number and process errors

PRINT 102, N

102 FORMAT (’ The new value is ’,I11)

GO TO 999

900 PRINT *, ’Unexpected I/O Error Number ’, IOS

999 CLOSE (UNIT=10)

END PROGRAM

The task file REMOTE.COM on the remote node contains the following

OpenVMS DCL commands:

$ DEFINE SYS$PRINT NL:

$ RUN DB0:[NET]REMOTE.EXE

$ PURGE/KEEP=2 REMOTE.LOG

! Inhibit printing of log

! Run remote program

! Delete old log files

The remote program PARIS::DB0:[NET]REMOTE.EXE contains the following source code:

OPEN (UNIT=10, FILE=’SYS$NET’, FORM=’UNFORMATTED’, &

ACCESS=’SEQUENTIAL’, STATUS=’OLD’)

READ (UNIT=10) N

N = N + 1

WRITE (UNIT=10) N

CLOSE (UNIT=10)

END PROGRAM

For More Information:

On using DECnet, refer to the DECnet for OpenVMS Networking Manual and

DECnet for OpenVMS Guide to Networking.

Interprocess Communication 13–15

Condition-Handling Facilities

This chapter describes:

• Section 14.1, Overview of Condition-Handling Facilities

• Section 14.2, Overview of the Condition-Handling Facility

• Section 14.3, Default Condition Handler

• Section 14.4, User-Program Interactions with the CHF

• Section 14.5, Operations Performed in Condition Handlers

• Section 14.6, Coding Requirements of Condition Handlers

• Section 14.7, Returning from a Condition Handler

• Section 14.8, Matching Condition Values to Determine Program Behavior

• Section 14.9, Changing a Signal to a Return Status

• Section 14.10, Changing a Signal to a Stop

• Section 14.11, Checking for Arithmetic Exceptions

• Section 14.12, Checking for Data Alignment Traps

• Section 14.13, Condition Handler Example

14.1 Overview of Condition-Handling Facilities

An exception condition, as the term is used in this chapter, is an event, usually an error, that occurs during the execution of a program and is detected by system hardware or software or by logic in a user application program. To resolve exception conditions, you can create a condition-handler routine.

This chapter addresses error handling only as it relates to the creation and use of condition-handler routines. Condition-handler routines are specific to the

OpenVMS operating system. For a general discussion of error handling, see

Chapter 7.

Condition-Handling Facilities 14–1

Examples of the types of exception conditions detected by system hardware and software are:

• Hardware exceptions, such as memory access violations.

• Software exceptions, such as output conversion errors, end-of-file conditions, and invalid arguments to mathematical procedures.

When an exception condition is detected by system hardware or software or by your program, that condition is signaled (by means of a signal call) to the OpenVMS Condition-Handling Facility (CHF). The CHF then invokes one or more condition-handler routines that will attempt to either resolve the condition or terminate the processing in an orderly fashion.

The CHF allows a main program and each subprogram that follows it, regardless of call depth, to establish a condition-handler routine (one per program unit). Each of these condition-handler routines can potentially handle any or all software or hardware events that are treated as exception conditions by the user program or by the system hardware or software. More than one condition handler for a given condition can be established by different program units in the call stack (see the HP OpenVMS Programming Concepts Manual).

The address of the condition handler for a particular program unit is placed in the call frame for that unit in the run-time call stack.

When the program unit returns to its caller, the call frame is removed and the condition handler for that program unit can no longer be accessed by the CHF.

Multiple condition handlers can be accessed by the CHF in the processing of a single exception condition signal. A process-wide handler can be established using the SYS$SETEXV system service.

Throughout this chapter, the term program unit refers to an executable

Fortran main program, subroutine, or function.

For More Information:

• On multiple condition handlers, see Section 14.7.

• On condition handling concepts, see the HP OpenVMS Programming

Concepts Manual.

14–2 Condition-Handling Facilities

14.2 Overview of the Condition-Handling Facility

The Condition-Handling Facility (CHF) receives control and coordinates processing of all exception conditions that are signaled to it. The signals are issued under the following circumstances:

• When a user program detects an application-dependent exception condition

• When system hardware or an HP Fortran software component detects a system-defined exception condition

In cases where the default condition handling is insufficient (see Section 14.3), you can develop your own handler routines and use the HP Fortran intrinsic function LIB$ESTABLISH to identify your handlers to the CHF. Typically, your needs for special condition handling are limited to the following types of operations:

• To respond to condition codes that are signaled instead of being returned, as in the case of integer overflow errors. (Section 14.9 describes the system-defined handler LIB$SIG_TO_RET, which allows you to treat signals as return values.)

• To add additional messages to those messages associated with the originally signaled condition code or to log the occurrence of various application-specific or system-specific conditions.

When an exception condition is detected by a system hardware or software component or by a component in the user application program, the component calls the CHF by means of a signal routine (LIB$SIGNAL or LIB$STOP), passing a value to the CHF that identifies the condition. The CHF takes program control away from the routine that is currently executing and begins searching for a condition-handler routine to call. If it finds one, it establishes a call frame on the run-time call stack and then invokes the handler. The handler routine then attempts to deal with the condition.

The sections that follow describe the CHF in detail—how it operates, how user programs can interact with it, and how users can code their own condition-handling routines:

• Section 14.3 describes default condition handlers established by the system.

• Section 14.4 describes how a user program makes a condition handler known to the CHF and how it signals a condition and passes arguments.

• Section 14.5, Section 14.6, and Section 14.7 contain information about writing a condition-handling routine.

• Section 14.8, Section 14.9, and Section 14.10 describe using the RTL routines LIB$MATCH_COND, LIB$SIG_TO_RET, and LIB$SIG_TO_STOP.

Condition-Handling Facilities 14–3

• Section 14.11 contains information on checking for arithmetic exceptions.

• Section 14.12 contains information on checking for data alignment traps.

• Section 14.13 contains some examples of the use of condition handlers.

14.3 Default Condition Handler

When the system creates an HP Fortran user process, it establishes a systemdefined condition handler that will be invoked by the CHF under the following circumstances:

• No user-established condition handlers exist in the call stack. (Any userestablished condition handlers in the call stack are always invoked before the default handler is invoked.)

• All of the user-established condition handlers in the call stack return the condition code SS$_RESIGNAL to the CHF. (The SS$_RESIGNAL condition code causes the CHF to search for another condition handler. See

Section 14.7.)

When establishing the default handler, the system has two handlers to choose from: the traceback handler and the catchall handler.

• Traceback Handler. Displays the message associated with the:

Signaled condition code

Traceback message

Program unit name and line number of the statement that resulted in the exception condition

Relative and absolute program counter values

In addition, the traceback handler displays the names of the program units in the current calling sequence and the line number of the invocation statements. (For exception conditions with a severity level of warning or error, the number of the next statement to be executed is also displayed.)

After displaying the error information, the traceback handler continues program execution or, if the error is severe, terminates program execution.

If the program terminates, the condition value becomes the program exit status.

• Catchall Handler. Displays the message associated with the condition code and then either continues program execution or, if the error is severe, terminates execution. If the program terminates, the condition value becomes the program exit status. In user mode, the catchall handler can be a list of handlers.

14–4 Condition-Handling Facilities

The /DEBUG and /TRACEBACK qualifiers—on the FORTRAN and LINK command lines, respectively—determine which default handler is enabled. If you take the defaults for these qualifiers, the traceback handler is established as the default handler. To establish the catchall handler as the default, specify

/NODEBUG or /DEBUG=NOTRACEBACK on the FORTRAN command line and /NOTRACEBACK on the LINK command line.

Use the FORTRAN command /SYNCHRONOUS_EXCEPTIONS (Alpha only) qualifier to ensure precise exception reporting.

For More Information:

• On condition values, see Table 7–1.

• On the FORTRAN command /SYNCHRONOUS_EXCEPTIONS (Alpha only) qualifier, see Section 2.3.46.

14.4 User-Program Interactions with the CHF

User-program interactions with the CHF are strictly optional and applicationdependent. In each program unit, you have the option of establishing (and removing) a single condition handler to handle exceptions that may occur in that program unit or in subsequent subprograms (regardless of call depth).

Once a program unit returns to its caller, its call frame is removed and any condition handler that the program unit has established becomes inaccessible.

The condition handler established by the user program can be coded to handle an exception condition signaled either by system hardware, a HP Fortran system software component, or the user program itself. User-program signals are issued by means of the LIB$STOP and LIB$SIGNAL routines described in

Section 14.4.2.

Although condition handlers offer a convenient and structured approach to handling exception conditions, they can have a significant impact on runtime performance when a condition handler is actually used. For commonly occurring application-specific conditions within a loop, for example, it may be wise to use other methods of dealing with the conditions. The best use of the facility is in large applications in which occasional exception conditions requiring special handling are anticipated.

The following sections describe how to establish and remove condition handlers and how to signal exception conditions.

Condition-Handling Facilities 14–5

14.4.1 Establishing and Removing Condition Handlers

To establish a condition handler, call the LIB$ESTABLISH intrinsic function.

(For compatibility with Compaq Fortran 77 for OpenVMS VAX Systems, HP

Fortran provides the LIB$ESTABLISH and LIB$REVERT routines as intrinsic functions.)

The form of the call can be as a subroutine or a function reference:

CALL LIB$ESTABLISH (new-handler)

old-handler=LIB$ESTABLISH(new-handler) new-handler

Specifies the name of the routine to be set up as a condition handler.

old-handler

Receives the address of the previously established condition handler.

LIB$ESTABLISH moves the address of the condition-handling routine into the appropriate process context and returns the previous address of a previously established condition handler.

The handler itself could be user-written or selected from a list of utility functions provided with HP Fortran. The following example shows how a call to establish a user-written handler might be coded:

EXTERNAL HANDLER

CALL LIB$ESTABLISH(HANDLER)

In the preceding example, HANDLER is the name of a Fortran function subprogram that is established as the condition handler for the program unit containing these source statements. A program unit can remove an established condition handler in two ways:

• Issue another LIB$ESTABLISH call specifying a different handler.

• Issue the LIB$REVERT call.

The LIB$REVERT call has no arguments and can be a subroutine or a function reference:

CALL LIB$REVERT

old-handler=LIB$REVERT( )

The use of old-handler for the LIB$REVERT call is the same as for the

LIB$ESTABLISH call.

14–6 Condition-Handling Facilities

This call removes the condition handler established in the current program unit. Like LIB$ESTABLISH, LIB$REVERT is provided as an intrinsic function.

When the program unit returns to its caller, the condition handler associated with that program unit is automatically removed (the program unit’s stack frame, which contains the condition handler address, is removed from the stack).

14.4.2 Signaling a Condition

When a prescribed condition requiring special handling by a condition handler is detected by logic in your program, you issue a condition signal in your program in order to invoke the CHF. A condition signal consists of a call to one of the two system-supplied signal routines in the following forms:

EXTERNAL LIB$SIGNAL, LIB$STOP

CALL LIB$SIGNAL(condition-value, arg, ..., arg)

CALL LIB$STOP(condition-value, arg, ..., arg) condition-value

An INTEGER (KIND=4) value that identifies a particular exception condition

(see Section 14.4.3) and can only be passed using the %VAL argument-passing mechanism.

arg

Optional arguments to be passed to user-established condition handlers and the system default condition handlers. These arguments consist of messages and formatted-ASCII-output arguments (see the VMS Run-Time Library

Routines Volume).

The CHF uses these parameters to build the signal argument array SIGARGS

(see Section 14.6) before passing control to a condition handler.

Whether you issue a call to LIB$SIGNAL or LIB$STOP depends on the following considerations:

• If the current program unit can continue after the signal is made, call

LIB$SIGNAL. The condition handler can then determine whether program execution continues. After the signal is issued, control is not returned to the user program until one of the condition handlers in the call stack resolves the exception condition and indicates to the CHF that program execution should continue.

Condition-Handling Facilities 14–7

• If the condition does not allow the current program unit to continue, call

LIB$STOP. (The only way to override a LIB$STOP signal is to perform an unwind operation. See Section 14.7.)

Figure 14–1 lists all of the possible effects of a LIB$SIGNAL or LIB$STOP call.

Figure 14–1 Effects of Calls to LIB$SIGNAL or LIB$STOP

Call to:

Signaled

Condition

Severity

<2:0>

Default

Handler

Gets Control

Handler

Specifies

Continue

Handler

Specifies

UNWIND

No Handler

Is Found

(stack bad)

LIB$SIGNAL or hardware exception

LIB$STOP

=4 force

(=4) condition message

RET condition message

EXIT condition message

EXIT

RET

"cannot continue"

EXIT

UNWIND

Call last chance handler

EXIT

Call last chance handler

EXIT

Call last chance handler

EXIT

ZK−5162−GE

In Figure 14–1, ‘‘cannot continue’’ indicates an error that results in the following message:

IMPROPERLY HANDLED CONDITION, ATTEMPT TO CONTINUE FROM STOP

14–8 Condition-Handling Facilities

To pass the condition value, you must use the %VAL argument-passing mechanism (see Section 10.3.3). Condition values are usually expressed as condition symbols (see Section 10.8.1). Condition symbols have either of the following forms:

fac$_symbol (HP-defined)

fac_ _symbol (user-defined) fac

A facility name prefix.

symbol

Identifies a specific condition. (See Table 7–1 for a list of HP Fortran condition symbols.)

In the following example, a signal call passes a condition symbol used to report a missing required privilege.

CALL LIB$SIGNAL(%VAL(SS$_NOSYSPRV))

You can include additional arguments to provide supplementary information about the error. System symbols such as SS$_NOSYSPRV are defined in the library module $SSDEF.

When your program issues a condition signal, the CHF searches for a condition handler by examining the preceding call frames, in order, until it either finds a procedure that handles the signaled condition or reaches the default condition handler. Condition handling procedures should use SS$_RESIGNAL for conditions they are not intended to handle.

14.4.3 Condition Values and Symbols Passed to CHF

The OpenVMS system uses condition values to indicate that a called procedure has either executed successfully or failed, and to report exception conditions.

Condition values are INTEGER (KIND=4) values (see the HP OpenVMS

Programming Concepts Manual and the HP OpenVMS Calling Standard for details). They consist of fields that indicate which software component generated the value, the reason the value was generated, and the severity of the condition. A condition value has the following fields:

Condition-Handling Facilities 14–9

31 28 27 16 15 3 2 control bits facility number message number severity code

0 condition identification condition value

ZK−7459−GE

The facility number field identifies the software component that generated the condition value. Bit 27 = 1 indicates a user-supplied facility; bit 27 = 0 indicates a system facility.

The message number field identifies the condition that occurred. Bit 15 = 1 indicates that the message is specific to a single facility; bit 15 = 0 indicates a system-wide message.

Table 14–1 gives the meanings of values in the severity code field.

Table 14–1 Severity Codes for Exception Condition Values

Code (Symbolic Name) Severity Response

0 (STS$K_WARNING)

1 (STS$K_SUCCESS)

2 (STS$K_ERROR)

3 (STS$K_INFORMATION)

4 (STS$K_SEVERE)

5 - 7

Warning

Success

Error

Information

Severe error

–

Execution continues, unpredictable results

Execution continues, expected results

Execution continues, erroneous results

Execution continues, informational message displayed

Execution terminates, no output

Reserved for use by HP

The symbolic names for the severity codes are defined in the $STSDEF library module in the HP Fortran Symbolic Definition Library, FORSYSDEF.

A condition handler can alter the severity code of a condition value—either to allow execution to continue or to force an exit, depending on the circumstances.

14–10 Condition-Handling Facilities

The condition value is passed in the second element of the array SIGARGS.

(See Section 14.6 for detailed information about the contents and use of the array SIGARGS.) In some cases, you may require that a particular condition be identified by an exact match; each bit of the condition value (31:0) must match the specified condition. For example, you may want to process a floating overflow condition only if its severity code is still 4 (that is, only if a previous handler has not changed the severity code).

In many cases, however, you may want to respond to a condition regardless of the value of the severity code. To ignore the severity and control fields of a condition value, use the LIB$MATCH_COND routine (see Section 14.8).

The FORSYSDEF library contains library modules that define condition symbols. When you write a condition handler, you can specify any of the following library modules, as appropriate, with an INCLUDE statement:

• $CHFDEF—This library module contains structure definitions for the primary argument list (CHFDEF), the signal array (CHFDEF1), and the mechanism array (CHFDEF2). These symbols have the following form:

CHF$_xxxxxxx

For example:

CHF$_IH_MCH_SAVR0

• $FORDEF—This library module contains definitions for all condition symbols from the HP Fortran library routines. See Table 7–1 for a list of the HP Fortran error numbers (IOSTAT values) associated with these symbols. These symbols have the following form:

FOR$_error

For example:

FOR$_INPCONERR

• $LIBDEF—This library module contains definitions for all condition symbols from the OpenVMS general utility library facility. These symbols have the following form:

LIB$_condition

For example:

LIB$_INSVIRMEM

Condition-Handling Facilities 14–11

• $MTHDEF—This library module contains definitions for all condition symbols from the mathematical procedures library. These symbols have the following form:

MTH$_condition

For example:

MTH$_SQUROONEG

• $SSDEF—This library module contains definitions for system services status codes, which are frequently used in HP Fortran condition handlers.

These symbols have the following form:

SS$_status

For example:

SS$_BADPARAM

For More Information:

• On performing an unwind operation, see Section 14.7.

• On a list of HP Fortran condition symbols, see Table 7–1.

• On the signal array SIGARGS, see Section 14.6.

14.5 Operations Performed in Condition Handlers

A condition handler responds to an exception by analyzing arguments passed to it and by taking appropriate action. Possible actions taken by condition handlers are:

• Condition correction

• Condition reporting

• Execution control

First, the handler must determine whether it can correct the condition identified by the condition code passed by the signal call. If possible, the handler takes the appropriate corrective action and execution continues. If it cannot correct the condition, the handler can resignal the condition; it can request that another condition handler (associated with an earlier program unit in the call stack) attempt to process the exception.

Condition reporting performed by handlers can involve one or more of the following actions:

• Maintaining a count of exceptions encountered during program execution.

14–12 Condition-Handling Facilities

• Signaling the same condition again (resignaling) in order to send the appropriate message to your terminal or log file.

• Changing the severity field of the condition value and resignaling the condition.

• Signaling a different condition, such as producing a message appropriate to a specific application. (The condition handler must establish the application-specific condition handler using LIB$ESTABLISH and then signal the condition using LIB$SIGNAL.)

Execution can be affected in a number of ways, such as:

• Continuing from the point of exception. However, if the signal was issued by means of a call to LIB$STOP, the program exits.

• Returning control (unwinding) to the program unit that established the handler. Execution resumes at the point of the call that resulted in the exception. The handler establishes the function value to be returned by the called procedure.

• Returning control (unwinding) to the establisher ’ s caller (to the program unit that called the program unit that established the handler). The handler establishes the function value to be returned by the program unit that established the handler.

For More Information:

• On returning from condition handlers, see Section 14.7.

• On condition handler examples, see Section 14.13.

14.6 Coding Requirements of Condition Handlers

An HP Fortran condition handler is an INTEGER (KIND=4) function that has two argument arrays passed to it by the CHF. To meet these requirements, you could define a condition handler as follows:

INCLUDE ’($CHFDEF)’

INTEGER (KIND=4) FUNCTION HANDLER(SIGARGS,MECHARGS)

INTEGER (KIND=4) SIGARGS(*)

RECORD /CHFDEF2/ MECHARGS

The CHF creates the signal and mechanism argument arrays SIGARGS and MECHARGS and passes them to the condition handler. Note that the mechanism vector block differs on OpenVMS I64 and OpenVMS Alpha systems

(see the HP OpenVMS Calling Standard).

Condition-Handling Facilities 14–13

The signal array (SIGARGS) is used by condition handlers to obtain information passed as arguments in the LIB$SIGNAL or LIB$STOP signal call.

Table 14–2 shows the contents of SIGARGS.

Table 14–2 Contents of SIGARGS

Array Element CHFDEF1 Field Name

SIGARGS(1)

SIGARGS(2)

SIGARGS(3 to n-1)

SIGARGS(n)

SIGARGS(n+1)

CHF$IS_SIG_ARGS

CHF$IS_SIG_NAME

CHF$IS_SIG_ARG1

(first argument)

None

Contents

Argument count (n)

Condition code

Zero or more additional arguments, specific to the condition code in

SIGARGS(2)

PC (program counter)

PS (processor status), lower 32-bits of the 64-bit OpenVMS processor status

• The notation n represents the argument count, that is, the number of elements in SIGARGS, not including the first element.

• The first array element SIGARGS(1) or CHF$IS_SIG_ARGS indicates how many additional arguments are being passed in this array. The count does not include this first element.

• SIGARGS(2) or CHF$IS_SIG_NAME indicates the signaled condition

(condition value) specified by the call to LIB$SIGNAL or LIB$STOP. If more than one message is associated with the exception condition, the condition value in SIGARGS(2) belongs to the first message.

• SIGARGS(3) or CHF$IS_SIG_ARG1 varies with the type of condition code in SIGARGS(2). This could contain the message description for the message associated with the condition code in SIGARGS(2), including secondary messages from RMS and system services. The format of the message description varies depending on the type of message being signaled. For more information, see the SYS$PUTMSG description in the

HP OpenVMS System Services Reference Manual.

Additional arguments, SIGARGS(n-1), can be specified in the call to

LIB$SIGNAL or LIB$STOP (see Section 14.4.2).

• The second-to-last element, SIGARGS(n), contains the value of the program counter (PC).

14–14 Condition-Handling Facilities

If the condition that caused the signal was a fault (occurring during the instruction’s execution), the PC contains the address of that instruction.

If the condition that caused the signal was a trap (occurring at the end of the instruction), the PC contains the address of the instruction following the call that signaled the condition code.

• The last element, SIGARGS(n+1), reflects the value of the processor status

(PS) at the time the signal was issued.

A condition handler is usually written in anticipation of a particular condition code or set of condition codes. Because handlers are invoked as a result of any signaled condition code, you should begin your handler routine by comparing the condition code passed to the handler (element 2 of SIGARGS) with the condition codes expected by the handler. If the signaled condition code is not an expected code, you should resignal the condition code by equating the function value of the handler to the global symbol SS$_RESIGNAL (see

Section 14.7).

The mechanism array (MECHARGS) is used to obtain information about the procedure activation of the program unit that established the condition handler. MECHARGS is a 90-element array, but only integer registers (Rn) and floating-point registers (Fn) are contained beyond element 12 (R0 is in elements 13 and 14 and all registers are 64 bits).

Table 14–3 shows the contents of MECHARGS on OpenVMS Alpha systems.

The contents are essentially the same on I64 and Alpha up to the CHF$IL_

MCH_SAVR10_HIGH field name. After that, the I64 registers are saved in the

I64 order and the contents of MECHARGS become different. For information about the additional field names for I64, see the HP OpenVMS System Services

Reference Manual.

Condition-Handling Facilities 14–15

Table 14–3 Contents of MECHARGS on OpenVMS Alpha Systems

INTEGER (KIND=4) Array Element CHFDEF2 Field Name Contents

MECHARGS(1)

MECHARGS(2)

MECHARGS(3), MECHARGS(4)

MECHARGS(5)

MECHARGS(6)

MECHARGS(7), MECHARGS(8)

MECHARGS(9), MECHARGS(10)

CHF$IS_MCH_ARGS

CHF$IS_MCH_FLAGS

CHF$PH_MCH_FRAME

CHF$IS_MCH_DEPTH

CHF$IS_MCH_RESVD1

CHF$PH_MCH_DADDR

CHF$PH_MCH_ESF_ADDR

MECHARGS(11), MECHARGS(12) CHF$PH_MCH_SIG_ADDR

MECHARGS(13), MECHARGS(14)

MECHARGS(15), MECHARGS(16)

CHF$IH_MCH_SAVR0

CHF$IL_MCH_SAVR0_LOW

CHF$IL_MCH_SAVR0_HIGH

CHF$IH_MCH_SAVR1

CHF$IL_MCH_SAVR1_LOW

CHF$IL_MCH_SAVR10_HIGH

MECHARGS(17) to MECHARGS(42) CHF$IH_MCH_SAVRnn

MECHARGS(43), MECHARGS(44)

MECHARGS(45), MECHARGS(46)

CHF$FH_MCH_SAVF0(2)

CHF$FH_MCH_SAVF1(2)

MECHARGS(47) to MECHARGS(88) CHF$IH_MCH_SAVFnn(2)

MECHARGS(89), MECHARGS(90) CHF$PH_MCH_SIG64_ADDR

Argument count

Flags

Frame address pointer

Call depth

Not used

Handler data address

Exception stack frame address

Signal array address

R0 low-order 32 bits high-order 32 bits

R1 low-order 32 bits high-order 32 bits

R16-R28

F10-F30

Address of 64-bit form of signal arrray

• CHF$IS_MCH_ARGS or MECHARGS(1) contains the argument count of this array in quadwords, not including this first quadword (the value 43).

• CHF$IS_MCH_FLAGS or MECHARGS(2) contains various flags to communicate additional information. For instance, if bit zero ( 0 ) is set, this indicates that the process has already performed a floatingpoint operation and that the floating-point registers are valid (CHF$S_

FPRREGS_VALID=1 and CHF$V_FPRREGS_VALID=0).

• CHF$PH_MCH_FRAME or MECHARGS(3) and MECHARGS(4) contains the address of the call frame on the stack for the program unit that established the handler.

• CHF$IS_MCH_DEPTH or MECHARGS(5) contains the number of calls made between the program unit that established the handler and the program unit that signaled the condition code.

14–16 Condition-Handling Facilities

• MECHARGS(6) is not used.

• CHF$PH_MCH_DADDR or MECHARGS(7) and MECHARGS(8) contain the address of the handler data quadword.

• CHF$PH_MCH_ESF_ADDR or MECHARGS(9) and MECHARGS(10) contain the address of the handler stack frame.

• CHF$PH_MCH_SIG_ADDR or MECHARGS(11) and MECHARGS(12) contains the address of the signal array.

• CHF$IH_MCH_SAVRnn to CHF$IH_MCH_SAVFnn (2) or MECHARGS(13) to MECHARGS(88) contain certain integer and floating-point registers.

• MECHARGS(89), MECHARGS(90): for information about 64-bit signal arrays, see HP OpenVMS Calling Standard.

Inside a condition handler, you can use any other variables that you need. If they are shared with other program units (for example, in common blocks), make sure that they are declared volatile. This will ensure that compiler optimizations do not invalidate the handler actions. See Section 5.7.3 and the

HP Fortran for OpenVMS Language Reference Manual for more information on the VOLATILE statement.

For More Information:

• On condition values, see Section 14.4.3.

• On the Itanium architecture, see the Intel Itanium Architecture Software

Developer’s Manual, Volume 1: Application Architecture.

• On register use, see the Alpha Architecture Reference Manual and the HP

OpenVMS Calling Standard.

• On condition handler examples, see Section 14.13.

14.7 Returning from a Condition Handler

One way that condition handlers control subsequent execution is by specifying a function return value (symbols defined in library module $SSDEF). Function return values and their effects are defined in Table 14–4.

Condition-Handling Facilities 14–17

Table 14–4 Condition-Handler Function Return Values

Symbolic Values Effects

SS$_CONTINUE

SS$_RESIGNAL

If you assign SS$_CONTINUE to the function value of the condition handler, the handler returns control to the program unit at the statement that signaled the condition

(fault) or the statement following the one that signaled the condition (trap).

If you assign SS$_RESIGNAL to the function value of the condition handler, or do not specify a function value

(function value of zero), the CHF will search for another condition handler in the call stack. If you modify SIGARGS or MECHARGS before resignaling, the modified arrays are passed to the next handler.

A condition handler can also request a call stack unwind by calling

SYS$UNWIND before returning. Unwinding the call stack:

• Removes call frames, starting with the call frame for the program unit in which the condition occurred

• Returns control to an earlier program unit in the current calling sequence

In this case, any function return values established by condition handlers are ignored by the CHF.

You can unwind the call stack whether the condition was detected by hardware or signaled by means of LIB$SIGNAL or LIB$STOP. Unwinding is the only way to continue execution after a call to LIB$STOP.

A stack unwind is typically made to one of two places:

• To the establisher of the condition handler that issues the SYS$UNWIND.

You pass the call depth (first half of the third element of the MECHARGS array) as the first argument in the call to SYS$UNWIND. Do not specify a second argument. For example:

INCLUDE ’($CHFDEF)’

RECORD /CHFDEF2/ MECHARGS

CALL SYS$UNWIND(MECHARGS.CHF$IS_MCH_DEPTH,)

Control returns to the establisher and execution resumes at the point of the call that resulted in the exception.

• To the establisher’s caller. Do not specify either of the arguments in the call to SYS$UNWIND. For example:

CALL SYS$UNWIND(,)

14–18 Condition-Handling Facilities

Control returns to the program unit that called the establisher of the condition handler that issues the call to SYS$UNWIND.

The actual stack unwind is not performed immediately after the condition handler issues the call to SYS$UNWIND. It occurs when a condition handler returns control to the CHF.

During the actual unwinding of the call stack, SYS$UNWIND examines each frame in the call stack to determine whether a condition handler was declared. If a handler was declared, SYS$UNWIND calls the handler with the condition value SS_$UNWIND (indicating that the stack is being unwound) in the condition name argument of the signal array. When a condition handler is called with this condition value, that handler can perform any procedurespecific clean-up operations that may be required. After the condition handler returns, the call frame is removed from the stack.

The system service SYS$GOTO_UNWIND performs a similar function.

For More Information:

On an example that uses SYS$UNWIND, see Section 14.13.

14.8 Matching Condition Values to Determine Program

Behavior

In many condition-handling situations, you may want to respond to an exception condition regardless of the value of the severity code passed in the condition value. To ignore the severity and control fields of a condition value, use the LIB$MATCH_COND routine as a function in the following form:

index = LIB$MATCH_COND(SIGARGS(2),con-1,...con-n) index

An integer variable that is assigned a value for use in a subsequent computed

GOTO statement.

con

A condition value.

The LIB$MATCH_COND function compares bits 27:3 of the value in

SIGARGS(2) with bits 27:3 of each specified condition value. If it finds a match, the function assigns the index value according to the position of the matching condition value in the list.

Condition-Handling Facilities 14–19

If the match is with the third condition value following SIGARGS(2), then

index = 3. If no match is found, index = 0. The value of the index can then be used to transfer control, as in the following example:

INTEGER (KIND=4) FUNCTION HANDL(SIGARGS,MECHARGS)

INCLUDE ’($CHFDEF)’

INCLUDE ’($FORDEF)’

INCLUDE ’($SSDEF)’

INTEGER (KIND=4) SIGARGS(*)

RECORD /CHFDEF2/ MECHARGS

INDEX=LIB$MATCH_COND(SIGARGS(2), FOR$_FILNOTFOU, &

FOR$_NO_SUCDEV, FOR$_FILNAMSPE, FOR$_OPEFAI)

GO TO (100,200,300,400), INDEX

HANDL=SS$_RESIGNAL

RETURN

...

100 ! Handle FOR$_FILNOTFOU

...

200 ! Handle FOR$_NO_SUCDEV

...

300 ! Handle FOR$_FILNAMSPE

...

400 ! Handle FOR$_OPEFAI

If no match is found between the condition value in SIGARGS(2) and any of the values in the list, then INDEX = 0 and control transfers to the next executable statement after the computed GOTO. A match with any of the values in the list transfers control to the corresponding statement in the GOTO list.

If SIGARGS(2) matches the condition symbol FOR$_OPEFAI, control transfers to statement 400.

For More Information:

• On a list of HP Fortran condition symbols, see Table 7–1.

• On an example that uses LIB$MATCH_COND, see Section 14.13.

14–20 Condition-Handling Facilities

14.9 Changing a Signal to a Return Status

When it is preferable to detect errors by signaling, but the calling procedure expects a returned status, LIB$SIG_TO_RET may be used by the procedure that signals. LIB$SIG_TO_RET is a condition handler that converts any signaled condition to a return status. The status is returned to the caller of the procedure that established LIB$SIG_TO_RET.

The arguments for LIB$SIG_TO_RET are:

LIB$SIG_TO_RET (sig-args,mch-args) sig-args

Contains the address of the signal argument array (see Section 14.6).

mch-args

Contains the address of the mechanism argument array (see Section 14.6).

You can establish LIB$SIG_TO_RET as a condition handler by specifying it in a call to LIB$ESTABLISH. You can also establish it by calling it from a user-written condition handler. If LIB$SIG_TO_RET is called from a condition handler, the signaled condition is returned as a function value to the caller of the establisher of that handler when the handler returns to the CHF. When a signaled exception condition occurs, LIB$SIG_TO_RET procedure does the following:

• Places the signaled condition value in the image of R0 that is saved as part of the mechanism argument vector.

• Calls the unwind system service (SYS$UNWIND) with the default arguments. After returning from LIB$SIG_TO_RET (when it is established as a condition handler) or after returning from the condition handler that called LIB$SIG_TO_RET (when LIB$SIG_TO_RET is called from within a condition handler), the stack is unwound to the caller of the procedure that established the handler.

Your calling procedure is then able to test R0 and R1 as if the called procedure had returned a status. Then the calling procedure can specify an error recovery action.

Condition-Handling Facilities 14–21

14.10 Changing a Signal to a Stop

The routine LIB$SIG_TO_STOP causes a signal to appear as though it had been signaled by a call to LIB$STOP.

LIB$SIG_TO_STOP can be established as a condition handler or called from within a user-written condition handler.

The argument that you passed to LIB$STOP is a 4-byte condition value (see

Section 14.4.3). The argument must be passed using the %VAL argumentpassing mechanism.

When a signal is generated by LIB$STOP, the severity code is forced to severe

(STS$K_SEVERE) and control cannot be returned to the procedure that signaled the condition.

14.11 Checking for Arithmetic Exceptions

On OpenVMS I64 systems, arithmetic exceptions are indicated by specific condition codes. Examples are SS$_FLTDIV or SS$_INTOVR.

On OpenVMS Alpha systems, arithmetic exceptions are indicated by the condition code SS$_HPARITH. The signal array for arithmetic exceptions

(condition code SS$_HPARITH) is unique to OpenVMS Alpha systems and contains seven longwords (seven INTEGER (KIND=4) array elements):

• SIGARRAY(1) contains the argument count.

• SIGARRAY(2) contains the condition code SS$_HPARITH.

• SIGARRAY(3) contains the integer register write mask.

• SIGARRAY(4) contains the floating-point register write mask.

• SIGARRAY(5) contains the exception summary.

• SIGARRAY(6) contains the exception PC (program counter).

• SIGARRAY(7) contains the exception PS (processor status).

In the integer register write mask and the floating-point register write mask, where each bit represents a register, any bits set indicate the registers that were targets of the exception. The exception summary indicates the type of exception or exceptions in the first seven bits of that longword, as follows:

14–22 Condition-Handling Facilities

Bit

Meaning

Software completion.

Invalid floating arithmetic, conversion, or comparison.

Invalid attempt to perform a floating-point divide with a divisor of zero.

(Integer divide-by-zero is not reported.)

Floating-point exponent overflow (arithmetic or conversion).

Floating-point exponent underflow (arithmetic or conversion).

Floating-point inexact result (arithmetic or conversion).

Integer arithmetic overflow or precision overflow during conversion from floating-point to integer.

To allow precise reporting of exceptions, specify the /SYNCHRONOUS_

EXCEPTIONS (Alpha only) qualifier on the FORTRAN command line.

If you omit /SYNCHRONOUS_EXCEPTIONS, instructions beyond the instruction causing the exception may have been executed by the time the exception is reported. This causes the PC to be located at a subsequent instruction (inexact exception reporting). Specifying /SYNCHRONOUS_

EXCEPTIONS drains the instruction pipeline after appropriate arithmetic instructions, but this slows performance.

For More Information:

• On the /CHECK qualifier, see Section 2.3.11.

• On the /SYNCHRONOUS_EXCEPTIONS (Alpha only) qualifier, see

Section 2.3.46.

14.12 Checking for Data Alignment Traps

Although HP Fortran naturally aligns local variables and provides the

/ALIGNMENT qualifier to control alignment of fields in a record structures, derived-type structures, or a common block, certain conditions can result in unaligned data (see Section 5.3).

Unaligned data can result in a data alignment trap, which is an exception indicated by the condition code SS$_ALIGN. The OpenVMS operating system fixes up data alignment traps and does not report them to the program unless requested.

To obtain data alignment trap information, your program can call the

SYS$START_ALIGN_FAULT_REPORT service.

Condition-Handling Facilities 14–23

You can also run the program within the OpenVMS debugger environment to detect the location of any unaligned data by using the SET

BREAK/UNALIGNED debugger command (see Section 4.7).

Use the FORTRAN command /SYNCHRONOUS_EXCEPTIONS (Alpha only) qualifier to ensure precise exception reporting.

Depending on the type of optimizations that might be applied, use the

FORTRAN command /NOOPTIMIZE qualifier to ensure exception reporting.

For More Information:

• On alignment, see Section 5.3.

• On using the OpenVMS Debugger to detect unaligned data, see Section 4.7.

• On the SYS$START_ALIGN_FAULT_REPORT service, see the HP

OpenVMS System Services Reference Manual.

• On the /CHECK qualifier, see Section 2.3.11.

• On the /SYNCHRONOUS_EXCEPTIONS (Alpha only) qualifier, see

Section 2.3.46.

14.13 Condition Handler Example

The example in this section demonstrates the use of condition handlers in typical Fortran procedures.

The following example creates a function HANDLER that tests for integer overflow. The program needs to be compiled using the /CHECK=OVERFLOW,

/SYNCHRONOUS_EXCEPTIONS (Alpha only), and (if fixed source form)

/EXTEND_SOURCE qualifiers.

This program types a maximum value for a 4-byte integer and

then causes an exception with integer overflow, transferring

control to a condition handler named HANDLER.

Compile with: /CHECK=OVERFLOW

/SYNCHRONOUS_EXCEPTIONS

(and if fixed format, /EXTEND_SOURCE)

File: INT_OVR.F90

INTEGER (KIND=4) INT4

EXTERNAL HANDLER !

14–24 Condition-Handling Facilities

CALL LIB$ESTABLISH (HANDLER) int4=2147483645

WRITE (6,*) ’ Beginning DO LOOP, adding 1 to ’, int4

DO I=1,10

INT4=INT4+1

WRITE (6,*) ’ INT4 NUMBER IS ’, int4

END DO

WRITE (6,*) ’ The end ...’

END PROGRAM

The function HANDLER that handles the condition SS$_HPARITH

INTEGER (KIND=4) FUNCTION HANDLER (SIGARGS, MECHARGS)

INTEGER (KIND=4) SIGARGS(*),MECHARGS(*)

INCLUDE ’($CHFDEF)’

INCLUDE ’($SSDEF)’

RECORD /CHFDEF1/ SIGARGS

RECORD /CHFDEF2/ MECHARGS

INTEGER INDEX

INTEGER LIB$MATCH_COND

INDEX = LIB$MATCH_COND(SIGARGS(2), SS$_HPARITH)

IF (INDEX .EQ. 0 ) THEN

HANDLER = SS$_RESIGNAL

ELSE IF (INDEX .GT. 0) THEN

WRITE (6,*) ’--> Arithmetic exception detected. Now in HANDLER’

CALL LIB$STOP(%VAL(SIGARGS(2)),) ’

END IF

RETURN

END FUNCTION HANDLER

The program is compiled, linked, and executed:

$ FORTRAN/CHECK=OVERFLOW/SYNCHRONOUS_EXCEPTIONS INT_OVR (

$ LINK INT_OVR

$ RUN INT_OVR

Condition-Handling Facilities 14–25

Beginning DO LOOP, adding 1 to 2147483645

INT4 NUMBER IS 2147483646

INT4 NUMBER IS 2147483647

--> Arithmetic exception detected. Now in HANDLER

%SYSTEM-F-HPARITH, high performance arithmetic trap, Imask=00000000,

Fmask=0002023C, summary=1B, PC=00000001, PS=00000001

-SYSTEM-F-FLTINV, floating invalid operation, PC=00000001, PS=00000001

-SYSTEM-F-FLTOVF, arithmetic trap, floating overflow at PC=00000001,

PS=00000001

-SYSTEM-F-FLTUND, arithmetic trap, floating underflow at PC=00000001,

PS=00000001

TRACE-F-TRACEBACK, symbolic stack dump follows

Image Name

INT_OVR

Module Name

INT_OVR$MAIN

Routine Name

HANDLER

Line Number

’ rel PC abs PC

1718 0000023C 0002023C

DEC$FORRTL 0 000729F4 000A49F4

----- above condition handler called with exception 00000504:

%SYSTEM-F-HPARITH, high performance arithmetic trap, Imask=00000002,

Fmask=00000000, summary=40, PC=000200CC, PS=0000001B

-SYSTEM-F-INTOVF, arithmetic trap,integer overflow at PC=000200CC, PS=0000001B

----- end of exception message

INT_OVR INT_OVR$MAIN INT_OVR$MAIN

0 84C122BC 84C122BC

19 000000CC 000200CC

0 84D140D0 84D140D0

The routine HANDLER is declared as EXTERNAL.

The main program calls LIB$ESTABLISH to establish the condition handler named HANDLER.

# Within the DO loop, the value of variable INT4 is incremented. When the overflow occurs, control transfers to the condition handler.

$ The condition handler (function HANDLER) is declared as an integer function accepting the signal array and mechanism array arguments.

% The library modules $SSDEF and $CHFDEF from FORSYSDEF.TLB are included and the SIGARGS and MECHARGS variables are declared as records. In this case, the structure definitions for the MECHARGS array are not needed, so the $CHFDEF library module is not included.

’

The condition handler is only intended to handle the condition code SS$_

HPARITH. For other conditions, SS$_RESIGNAL is returned, allowing the

CHF to look for another condition handler.

If the exception is SS$_HPARITH, the condition handler makes a call to

LIB$STOP to:

Display the %SYSTEM-F-HPARITH message.

14–26 Condition-Handling Facilities

(

Display the traceback information. Note that the PC address is the address of the HANDLER routine. To obtain the approximate address where the exception occurred, the CALL LIB$ESTABLISH line can be commented out in the routine causing the exception and recompiled, relinked, and rerun.

Stop program execution. This is not a continuable error.

The program must be compiled using /CHECK=OVERFLOW. Using

/SYNCHRONOUS_EXCEPTIONS (Alpha only) allows more precise exception reporting. If the program is compiled as fixed-form file, specify the /EXTEND_SOURCE qualifier.

Condition-Handling Facilities 14–27

Using the Compaq Extended Math Library

(CXML) (Alpha Only)

This chapter describes:

• Section 15.1, What Is CXML?

• Section 15.2, CXML Routine Groups

• Section 15.3, Using CXML from Fortran

• Section 15.4, CXML Program Example

Note

This entire chapter pertains only to HP Fortran on OpenVMS Alpha systems only.

15.1 What Is CXML?

The Compaq Extended Math Library (CXML) provides a comprehensive set of mathematical library routines callable from Fortran and other languages. CXML contains a set of over 1500 high-performance mathematical subprograms designed for use in many different types of scientific and engineering applications. It significantly improves the run-time performance of certain HP Fortran programs.

CXML is included with HP Fortran for OpenVMS Alpha Systems and can be installed using the instructions in the HP Fortran Installation Guide for

OpenVMS Alpha Systems.

The CXML reference guide is available in both online and hardcopy formats.

You can obtain this documentation by accessing the following files:

• SYS$HELP:CXMLREF-VMS.PDF (online)—view with the Adobe Acrobat

Reader

Using the Compaq Extended Math Library (CXML) (Alpha Only) 15–1

• SYS$HELP:CXMLREF-VMS.PS (hardcopy)—print to a PostScript printer

Example programs are also provided with CXML. These programs are located in the following directory:

SYS$COMMON:[SYSHLP.EXAMPLES.CXML]

15.2 CXML Routine Groups

CXML provides a comprehensive set of highly efficient mathematical subroutines designed for use in many different types of scientific and engineering applications. CXML includes the following functional groups of subroutines:

• Basic linear algebra

• Linear system and Eigenproblem solvers

• Sparse linear system solvers

• Signal processing

• Utility subprograms

The routines are described in Table 15–1.

15–2 Using the Compaq Extended Math Library (CXML) (Alpha Only)

Table 15–1 CXML Routine Groups

Name Description

Basic Linear Algebra

Signal Processing

Sparse Linear System

LAPACK

Utility subprograms

The Basic Linear Algebra Subprograms (BLAS) library includes the industry-standard Basic Linear Algebra Subprograms for Level 1

(vector-vector, BLAS1), Level 2 (matrix-vector, BLAS2), and Level 3

(matrix-matrix, BLAS3). Also included are subprograms for BLAS

Level 1 Extensions, and Sparse BLAS Level 1.

The Signal Processing library provides a basic set of signal processing functions. Included are one-, two-, and three-dimensional Fast Fourier

Transforms (FFT), group FFTs, Cosine/Sine Transforms (FCT/FST),

Convolution, Correlation, and Digital Filters.

The Sparse Linear System library provides both direct and iterative sparse linear system solvers. The direct solver package supports both symmetric and symmetrically shaped sparse matrices stored using the compressed row storage scheme. The iterative solver package supports a basic set of storage schemes, preconditioners, and iterative solvers.

LAPACK is an industry-standard subprogram package offering an extensive set of linear system and eigenproblem solvers. LAPACK uses blocked algorithms that are better suited to most modern architectures, particularly ones with memory hierarchies.

Utility subprograms include random number generation, vector math functions, and sorting subprograms.

Where appropriate, each subprogram has a version to support each combination of real or complex and single- or double-precision arithmetic.

In addition, selected key CXML routines are available in parallel form as well as serial form on HP OpenVMS Alpha systems.

15.3 Using CXML from Fortran

To use CXML, you need to make the CXML routines and their interfaces available to your program and specify the appropriate libraries when linking.

The CXML routines can be called explicitly by your program. There are separate CXML libraries for the IEEE and the VAX floating-point formats.

You must compile your program for one of these float formats and then link to the matching CXML library (either IEEE or VAX), depending upon how you compiled the program.

Either the IEEE or VAX CXML library can be established as the systemwide default by the system startup procedure. Individual users can select between the VAX and IEEE version by executing the SYS$LIBRARY:CXML$SET_LIB

Using the Compaq Extended Math Library (CXML) (Alpha Only) 15–3

command procedure. For example, the following command alters the default

CXML link library for the current user to the VAX format library:

$ @SYS$LIBRARY:CXML$SET_LIB VAX

For more details, see the section about CXML post-installation startup options in the HP Fortran Installation Guide for OpenVMS Alpha Systems.

If needed, you can instead specify the appropriate CXML library or libraries on the LINK command line (use the /LIBRARY qualifier after each library file name). You must compile your program and then link to the appropriate

CXML library (either IEEE or VAX), depending upon how you compiled the program. The following examples show the corresponding CXML commands for compiling and linking for cases where the CXML default library is not used:

$ FORTRAN /FLOAT=IEEE_FLOAT MYPROG.F90

$ LINK MYPROG.OBJ, SYS$LIBRARY:CXML$IMAGELIB_TS/LIBRARY

The link command uses the name of the CXML library for IEEE floating-point data, cxml$imagelib_ts . To use VAX floating-point data, specify the CXML library name as cxml$imagelib_gs .

If you are using an older version of CXML, use dxml$xxxxx instead of cxml$xxxxx as the library name. For more information on using CXML and specifying the correct object libraries on the LINK command, see the Compaq

Extended Mathematical Library Reference Manual.

15.4 CXML Program Example

The free-form Fortran 90 example program below invokes the function SAXPY from the BLAS portion of the CXML libraries. The SAXPY function computes a 3 x + y

15–4 Using the Compaq Extended Math Library (CXML) (Alpha Only)

PROGRAM example

This free-form example demonstrates how to call

CXML routines from Fortran.

REAL(KIND=4) :: a(10)

REAL(KIND=4) :: x(10)

REAL(KIND=4) :: alpha

INTEGER(KIND=4) :: n

INTEGER(KIND=4) :: incx

INTEGER(KIND=4) :: incy n = 5 ; incx = 1 ; incy = 1 ; alpha = 3.0

DO i = 1,n a(i) = FLOAT(i) x(i) = FLOAT(2*i)

ENDDO

PRINT 98, (a(i),i=1,n)

PRINT 98, (x(i),i=1,n)

98 FORMAT(’ Input = ’,10F7.3)

CALL saxpy( n, alpha, a, incx, x, incy )

PRINT 99, (x(i),I=1,n)

99 FORMAT(/,’ Result = ’,10F7.3)

STOP

END PROGRAM example

Using the Compaq Extended Math Library (CXML) (Alpha Only) 15–5

Differences Between HP Fortran on

OpenVMS I64 and OpenVMS Alpha

Systems

This appendix describes:

• Section A.1, HP Fortran Commands on OpenVMS I64 That Are Not

Available on OpenVMS Alpha

• Section A.2, HP Fortran Commands on OpenVMS Alpha That Are Not

Available on OpenVMS I64

• Section A.3, Differences in Default Values

• Section A.4, Support for VAX-Format Floating-Point

• Section A.5, Changes in Exception Numbers and Places

• Section A.6, Changes in Exception-Mode Selection

A.1 HP Fortran Commands on OpenVMS I64 That Are Not

Available on OpenVMS Alpha

• /CHECK=ARG_INFO

• /CHECK=FP_MODE

A.2 HP Fortran Commands on OpenVMS Alpha That Are Not

Available on OpenVMS I64

• /ARCHITECTURE

• /MATH_LIBRARY

• /OLD_F77

Differences Between HP Fortran on OpenVMS I64 and OpenVMS Alpha Systems A–1

• /OPTIMIZE=TUNE

• /SYNCHRONOUS_EXCEPTIONS

A.3 Differences in Default Values

The differences are:

• Because the Itanium architecture supports IEEE directly, the default floating-point format on OpenVMS I64 systems is /FLOAT=IEEE_FLOAT.

On OpenVMS Alpha systems, the default is /FLOAT=G_FLOAT. See

Section 2.3.22.

• The default floating-point exception handling mode on OpenVMS I64 systems is /IEEE_MODE=DENORM_RESULTS). On OpenVMS Alpha systems, the default is /IEEE_MODE=FAST. See Section 2.3.24.

A.4 Support for VAX-Format Floating-Point

Because there is no direct hardware support for VAX-format floating-point on

OpenVMS I64 systems, the VAX-format floating-point formats (F, D, and G) are supported indirectly by a three-step process:

Conversion from VAX-format variable to IEEE floating-point temporary

(using the denormalized number range)

Computation in IEEE floating-point

Conversion back to VAX-format floating-point and storage into the target variable

There are a number of implications for this approach:

• Exceptions might move, appear, or disappear, because the calculation is done in a different format with a different range of representable values.

• Because there are very small numbers representable in VAX format that can only be represented in IEEE format using the IEEE denorm range, there is a potential loss of accuracy if an intermediate result of the calculation is one of those numbers.

At worst, the two bits with the least significance will be set to zero. Note that further calculations might result in magnifying the magnitude of this loss of accuracy.

Note that this small loss of accuracy does not raise signal FOR$_

SIGLOSMAT (or FOR$IOS_SIGLOSMAT).

A–2 Differences Between HP Fortran on OpenVMS I64 and OpenVMS Alpha Systems

• Expressions that are used to drive control flow but are not stored back into a variable will not be converted back into VAX format. This can cause exceptions to disappear.

• There can be a significant performance cost for the use of VAX-format floating-point.

Note that floating-point query built-ins (such as TINY and HUGE) will return values appropriate to the floating-point format that you select, despite the fact that all formats are supported by IEEE.

A.5 Changes in Exception Numbers and Places

There will be changes in the number of exceptions raised and in the code location at which they are raised.

This is particularly true for VAX-format floating-point calculations, because many exceptions will only be raised at the point where a result is converted from IEEE format to VAX format. Some valid IEEE-format numbers will be too large or too small to convert and will thus raise underflow or overflow. IEEE exceptional values (such as Infinity and NaN) produced during the evaluation of an expression will not generate exceptions until the final conversion to VAX format is done.

If a VAX-format floating-point calculation has intermediate results (such as the

X * Y in the expression (X * Y)/ Z ), and the calculation of that intermediate result raised an exception on OpenVMS Alpha systems, it is not guaranteed that an exception will be raised on OpenVMS I64 systems. An exception will only be raised if the IEEE calculation produces an exception.

A.5.1 Ranges of Representable Values

In general, the range of VAX-format floating-point numbers is the same as the range for IEEE-format. However, the smallest F- or G-format value is one quarter the size of the smallest normal IEEE number, while the largest F- or

G-format number is about half that of the largest IEEE number. There are therefore nonexceptional IEEE values that would raise overflows in F- or Gformat. There are also nonexceptional F- or G-format values that would raise underflow in IEEE-format in those modes in which denormalized numbers are not supported.

Differences Between HP Fortran on OpenVMS I64 and OpenVMS Alpha Systems A–3

A.5.2 Underflow in VAX Format with /CHECK=UNDERFLOW

OpenVMS Alpha and VAX Fortran applications do not report underflows for VAX-format floating-point operations unless you specifically enable underflow traps by compiling with the /CHECK=UNDERFLOW qualifier

(see Section 2.3.11).

The same is true on OpenVMS I64 systems, but with an important caveat:

Since all I64 floating-point operations are implemented by means of IEEEformat operations, enabling underflow traps with /CHECK=UNDERFLOW causes exceptions to be raised when values underflow the IEEE-format representation, not the VAX-format one.

This can result in an increased number of underflow exceptions seen with

/CHECK=UNDERFLOW when compared with equivalent Alpha or VAX programs, as the computed values may be in the valid VAX-format range, but in the denormalized IEEE-format range.

If your application requires it, a user-written exception handler could catch the IEEE-format underflow exception, inspect the actual value, and determine whether it represented a VAX-format underflow or not.

See Section 8.4 for exact ranges of VAX-format and IEEE-format floating point.

A.6 Changes in Exception-Mode Selection

On OpenVMS Alpha systems, the exception-handling mode and the rounding mode can be chosen on a per-routine basis. This lets you set a desired exception mode and rounding mode using compiler qualifiers. Thus, a single application can have different modes during the execution of different routines.

This is not as easy to do on OpenVMS I64 systems. While the modes can be changed during the execution of a program, there is a significant performance penalty for doing so.

As a result, the HP Fortran compiler and the OpenVMS linker implement a

‘‘whole-program’’ rule for exception handling and rounding modes. The rule says that the whole program is expected to run in the same mode, and that all compilations will have been done using the same mode qualifiers. To assist in enforcing this rule, the compiler, linker and loader work together:

• The compiler tags each compiled object file with a code specifying the modes selected by the user (directly or using the default) for that compilation.

• The linker tags the generated executable file with a code specifying the mode selected by the user.

A–4 Differences Between HP Fortran on OpenVMS I64 and OpenVMS Alpha Systems

• The loader initializes the floating-point status register of the process based on the linker code.

A.6.1 How to Change Exception-Handling or Rounding Mode

If you are using an OpenVMS I64 system and want to change the exceptionhandling or rounding mode during the execution of a program, use a call to either of the following:

• Fortran routines DFOR$GET_FPE and DFOR$SET_FPE

• System routines SYS$IEEE_SET_FP_CONTROL, SYS$IEEE_SET_

PRECISION_MODE, and SYS$IEEE_SET_ROUNDING_MODE

Note

HP does not encourage users to change the exception-handling or rounding mode within a program. This practice is particularly discouraged for an application using VAX-format floating-point.

A.6.1.1 Calling DFOR$GET_FPE and DFOR$SET_FPE

If you call DFOR$GET_FPE and DFOR$SET_FPE, you need to construct a mask using the literals in SYS$LIBRARY:FORDEF.FOR, module FOR_FPE_

FLAGS.

The calling format is:

INTEGER*4 OLD_FLAGS, NEW_FLAGS

INTEGER*4 DFOR$GET_FPE, DFOR$GET_FPE

EXTERNAL DFOR$GET_FPE, DFOR$GET_FPE

! Set the new mask, return old mask.

OLD_FLAGS = DFOR$GET_FPE( NEW_FLAGS )

! Return the current FPE mask.

OLD_FLAGS = DFOR$GET_FPE ()

An example (which does no actual computations) follows. For a more complete example, see Example A–1.

Differences Between HP Fortran on OpenVMS I64 and OpenVMS Alpha Systems A–5

subroutine via_fortran include ’sys$library:fordef.for’ include ’($IEEEDEF)’ integer new_flags, old_flags old_flags = dfor$get_fpe() new_flags = FOR_K_FPE_CNT_UNDERFLOW + FPE_M_TRAP_UND call dfor$set_fpe( new_flags )

Code here uses new flags

call dfor$set_fpe( old_flags ) return end subroutine

A.6.1.2 Calling SYS$IEEE_SET_FP_CONTROL, SYS$IEEE_SET_PRECISION_MODE, and SYS$IEEE_SET_ROUNDING_MODE

If you call SYS$IEEE_SET_FP_CONTROL, SYS$IEEE_SET_PRECISION_

MODE, and SYS$IEEE_SET_ROUNDING_MODE, you need to construct a set of masks using the literals in SYS$LIBRARY:FORSYSDEF.TLB, defined in module IEEEDEF.H (in STARLET). For information about the signature of these routines, see the HP OpenVMS System Services Reference Manual.

An example (which does no actual computations) follows. For a more complete example, see Example A–1.

subroutine via_system( rr ) real rr include ’($IEEEDEF)’ integer*8 clear_flags, set_flags, old_flags, new_flags clear_flags = IEEE$M_MAP_DNZ + IEEE$M_MAP_UMZ set_flags = IEEE$M_TRAP_ENABLE_UNF + IEEE$M_TRAP_ENABLE_DNOE call sys$ieee_set_fp_control(%ref(clear_flags),

%ref(set_flags),%ref(old_flags))

Code here uses new flags

clear_flags = set_flags call sys$ieee_set_fp_control(%ref(clear_flags),%ref(old_flags),%ref(new_flags)) return

A.6.1.3 Additional Rules That You Should Follow

If you decide to change the exception-handling or rounding mode, be careful to observe the following rules to maintain the ‘‘whole-program’’ rule. Failure to do so might cause unexpected errors in other parts of your program:

• The preexisting mode must be restored at the end of the execution of the section in which the new mode is used. This includes both normal endings, such as leaving a code block, and exits by means of exception handlers.

A–6 Differences Between HP Fortran on OpenVMS I64 and OpenVMS Alpha Systems

• It is a good idea to establish a handler to restore the old mode on unwinds, because called code can cause exceptions to be raised (including exceptions not related to floating point).

• The code should be compiled with the same mode qualifiers as the other,

‘‘normal’’ parts of the application, not with the mode that will be set by the call to the special function.

• Be aware that VAX-format expressions are actually calculated in IEEE format, and any change to the modes will impact a calculation in IEEE format, not a calculation in VAX format.

• Consider adding the VOLATILE attribute to the declaration of all the variables used in the calculation in the different mode. This will prevent optimizations that might move all or part of the calculation out of the region in which the different mode is in effect.

A.6.1.4 Whole-Program Mode and Library Calls

System libraries that need to use an alternate mode (for example, the math library) accomplish this by using an architectural mechanism not available to user code: the the .sf0

flags).

.sf1

flags of the floating-point status register (user code uses

Therefore, a user’s choice of exception-handling or rounding mode will not have an impact on any system library used by the program.

A.6.2 Example of Changing Floating-Point Exception-Handling Mode

Example A–1 shows both methods of changing the floating-point exceptionhandling mode. However, for a real program, you should pick just one of the two methods.

Differences Between HP Fortran on OpenVMS I64 and OpenVMS Alpha Systems A–7

Example A–1 Changing Floating-Point Exception Mode

SET_FPE.F90: Change floating-point exception handling mode,

and check that it worked.

Compile and link like this:

$ f90 set_fpe

$ lin set_fpe,SYS$LIBRARY:VMS$VOLATILE_PRIVATE_INTERFACES.OLB/lib

$ run set_fpe

The library is needed to bring in the code for LIB$I64_INS_DECODE,

which we call for its side-effect of incrementing the PC in the

correct manner for I64.

This is a place to save the old FPE flags.

module saved_flags integer saved_old_flags end module

Turn on underflow detection for one routine

Using the FORTRAN library function FOR_SET_FPE.

subroutine via_fortran( rr ) real rr include ’sys$library:fordef.for’ include ’($IEEEDEF)’ integer new_flags, old_flags old_flags = dfor$get_fpe() new_flags = FPE_M_TRAP_UND call dfor$set_fpe( new_flags )

Code here uses new flags

rr = tiny(rr) type *,’ Expect a catch #1’ rr = rr / huge(rr)

call dfor$set_fpe( old_flags ) return end subroutine

(continued on next page)

A–8 Differences Between HP Fortran on OpenVMS I64 and OpenVMS Alpha Systems

Example A–1 (Cont.) Changing Floating-Point Exception Mode

Alternatively, do the same using the system routine.

Code here uses new flags

rr = tiny(rr) type *,’ Expect a catch #2’ rr = rr / huge(rr)

clear_flags = set_flags call sys$ieee_set_fp_control(%ref(clear_flags),%ref(old_flags),%ref(new_flags)) return end subroutine

Main program

program tester use saved_flags real, volatile :: r

Establish an exception handler.

external handler call lib$establish( handler )

Save the initial setting of the exception mode flags.

saved_old_flags = dfor$get_fpe()

This expression underflows, but because this program has

been compiled with /IEEE=DENORM (by default) underflows

do not raise exceptions.

write (6,100)

100 format(1x,’ No catch expected’) r = tiny(r); r = r / huge(r)

(continued on next page)

Differences Between HP Fortran on OpenVMS I64 and OpenVMS Alpha Systems A–9

Example A–1 (Cont.) Changing Floating-Point Exception Mode

Call a routine to turn on underflow and try that expression

again.

After the call, verify that underflow detection has

been turned off.

call via_fortran( r ) write (6,100) r = tiny(r) r = r / huge(r)

Ditto for the other approach

call via_system( r ) write (6,100) r = tiny(r) r = r / huge(r) end program

A handler is needed to catch any exceptions.

integer (kind=4) function handler( sigargs, mechargs ) use saved_flags include ’($CHFDEF)’ include ’($SSDEF)’ integer sigargs(100) record /CHFDEF2/ mechargs integer lib$match_cond integer LIB$I64_INS_DECODE

integer index integer status integer no_loop logical int_over logical int_div

/ 20 / logical float_over logical float_div logical float_under logical float_inval logical float_denorm logical hp_arith logical do_PC_advance integer pc_index integer*8 pc_value

Don’t loop forever between handler and exception

(in case something goes wrong).

(continued on next page)

A–10 Differences Between HP Fortran on OpenVMS I64 and OpenVMS Alpha Systems

Example A–1 (Cont.) Changing Floating-Point Exception Mode

no_loop = no_loop - 1 if( no_loop .le. 0 ) then handler = ss$_resignal return endif

We’ll need the PC value of the instruction if

this turns out to have been a fault rather than

a trap.

pc_index = sigargs(1) pc_value = sigargs(pc_index)

Figure out what kind of exception we have, and

whether it is a fault and we need to advance the

PC before continuing.

do_PC_advance = .false.

int_over int_div

= .false.

float_over = .false.

float_div = .false.

float_under = .false.

float_inval = .false.

float_denorm = .false.

hp_arith = .false.

index = lib$match_cond(sigargs(2), SS$_INTOVF) if( index .eq. 0 ) then int_over = .true.

endif

index = lib$match_cond(sigargs(2), SS$_INTDIV) if( index .eq. 0 ) then int_div = .true.

endif

index = lib$match_cond(sigargs(2), SS$_FLTOVF) if( index .eq. 0 ) then float_over = .true.

endif

index = lib$match_cond(sigargs(2), SS$_FLTDIV) if( index .eq. 0 ) then float_div = .true.

endif

(continued on next page)

Differences Between HP Fortran on OpenVMS I64 and OpenVMS Alpha Systems A–11

Example A–1 (Cont.) Changing Floating-Point Exception Mode

index = lib$match_cond(sigargs(2), SS$_FLTUND) if( index .eq. 0 ) then float_under = .true.

endif

index = lib$match_cond(sigargs(2), SS$_FLTOVF_F) if( index .eq. 0 ) then endif

float_over = .true.

do_PC_advance = .true.

index = lib$match_cond(sigargs(2), SS$_FLTDIV_F) if( index .eq. 0 ) then endif

float_div = .true.

do_PC_advance = .true.

index = lib$match_cond(sigargs(2), SS$_FLTUND_F) if( index .eq. 0 ) then float_under = .true.

do_PC_advance = .true.

endif

index = lib$match_cond(sigargs(2), SS$_FLTINV) if( index .eq. 0 ) then float_inval = .true.

do_PC_advance = .true.

endif

index = lib$match_cond(sigargs(2), SS$_INTOVF_F) if( index .eq. 0 ) then int_over = .true.

do_PC_advance = .true.

endif

index = lib$match_cond(sigargs(2), SS$_FLTDENORMAL) if( index .eq. 0 ) then float_denorm = .true.

endif

index = lib$match_cond(sigargs(2), SS$_HPARITH) if( index .eq. 0 ) then hp_arith = .true.

endif

Tell the user what kind of exception this is.

(continued on next page)

A–12 Differences Between HP Fortran on OpenVMS I64 and OpenVMS Alpha Systems

Example A–1 (Cont.) Changing Floating-Point Exception Mode

handler = ss$_continue if( float_over) then write(6,*) ’ - Caught Floating overflow’ else if ( int_over ) then write(6,*) ’ - Caught Integer overflow’ else if ( int_div ) then write(6,*) ’ - Caught Integer divide by zero’ else if ( float_div ) then write(6,*) ’ - Caught Floating divide by zero’ else if ( float_under ) then write(6,*) ’ - Caught Floating underflow’ else if ( float_inval ) then write(6,*) ’ - Caught Floating invalid’ else if ( hp_arith ) then write(6,*) ’ - Caught HP arith error’ else write(6,*) ’ - Caught something else: resignal ’

Here we have to restore the initial floating-point

exception processing mode in case the exception

happened during one of the times we’d changed it.

call dfor$set_fpe( saved_old_flags )

handler = ss$_resignal endif

If this was a fault, and we want to continue, then

the PC has to be advanced over the faulting instruction.

if( do_PC_advance .and. (handler .eq. ss$_continue)) then status = lib$i64_ins_decode (pc_value) sigargs(pc_index) = pc_value endif

return end function handler

Differences Between HP Fortran on OpenVMS I64 and OpenVMS Alpha Systems A–13

Compatibility: Compaq Fortran 77 and HP

Fortran

This appendix describes:

• Section B.1, HP Fortran and Compaq Fortran 77 Compatibility on Various

Platforms

• Section B.2, Major Language Features for Compatibility with Compaq

Fortran 77 for OpenVMS Systems

• Section B.3, Language Features and Interpretation Differences Between

Compaq Fortran 77 and HP Fortran on OpenVMS Systems

• Section B.4, Improved HP Fortran Compiler Diagnostic Detection

• Section B.5, Compiler Command-Line Differences

• Section B.6, Interoperability with Translated Shared Images

• Section B.7, Porting Compaq Fortran 77 for OpenVMS VAX Systems Data

• Section B.8, VAX H_float Representation

B.1 HP Fortran and Compaq Fortran 77 Compatibility on

Various Platforms

Table B–1 summarizes the compatibility of HP Fortran (HF, which supports the Fortran 95, 90, 77, and 66 standards) and Compaq Fortran 77 (CF77) on multiple platforms (architecture/operating system pairs).

HP Fortran is available on OpenVMS I64 systems, OpenVMS Alpha Systems,

Tru64 UNIX Alpha systems, Linux Alpha systems, and as Compaq Visual

Fortran (CVF) on Windows systems.

Compatibility: Compaq Fortran 77 and HP Fortran B–1

Table B–1 Summary of Language Compatibility

UNIX

Alpha

Linux

Alpha

CVF

Windows x86

OpenVMS

I64 and

Alpha

CF77

OpenVMS

Alpha

CF77

OpenVMS

VAX Language Feature

Linking against static and shared libraries

Create code for shared libraries

Recursive code support

AUTOMATIC and STATIC statements

STRUCTURE and RECORD declarations

INTEGER*1, *2, *4

LOGICAL*1, *2, *4

INTEGER*8 and LOGICAL*8

REAL*4, *8

REAL*16

COMPLEX*8, *16

COMPLEX*32

POINTER (CRAY-style)

INCLUDE statements

IMPLICIT NONE statements

Data initialization in type declarations

Automatic arrays

VOLATILE statements

NAMELIST-directed I/O

31-character names including $ and _

Source listing with machine code

Debug statements in source

Bit constants to initialize data and use in arithmetic

For REAL*16 data, OpenVMS VAX systems use H_float format, and I64 and Alpha systems use IEEE style

X_float format.

For COMPLEX*32 data, I64 and Alpha systems use IEEE style X_float format for both REAL*16 parts.

(continued on next page)

B–2 Compatibility: Compaq Fortran 77 and HP Fortran

Table B–1 (Cont.) Summary of Language Compatibility

Language Feature

DO WHILE and END DO statements

Built-in functions %LOC, %REF, %VAL

SELECT CASE construct

EXIT and CYCLE statements

Variable FORMAT expressions (VFEs)

! marks end-of-line comment

Optional run-time bounds checking for arrays and substrings

Binary (unformatted) I/O in IEEE big endian, IEEE little endian, VAX, IBM, and CRAY floating-point formats

Fortran 90/95 standards checking

FORTRAN-77 standards checking

IEEE exception handling

VAX floating data type in memory

IEEE floating data type in memory

CDD/Repository DICTIONARY support

KEYED access and INDEXED files

Parallel decomposition

OpenMP parallel directives

Conditional compilation using IF . . .

DEF constructs

Vector code support

Direct inlining of Basic Linear Algebra

Subroutines (BLAS)

DATE_AND_TIME returns 4-digit year

FORALL statement and construct

UNIX

Alpha

Linux

Alpha

CVF

Windows x86

3 3

OpenVMS

I64 and

Alpha

CF77

OpenVMS

Alpha

CF77

OpenVMS

VAX

3 3

BLAS and other routines are available with the Compaq Extended Mathematical Library (CXML). See

Chapter 15.

(continued on next page)

Compatibility: Compaq Fortran 77 and HP Fortran B–3

Table B–1 (Cont.) Summary of Language Compatibility

Language Feature

Automatic deallocation of ALLOCATABLE arrays

UNIX

Alpha

Dim argument to MAXLOC and

MINLOC

PURE user-defined subprograms

ELEMENTAL user-defined subprograms

Pointer initialization (initial value)

The NULL intrinsic to nullify a pointer

Derived-type structure initialization

CPU_TIME intrinsic subroutine

Kind argument to CEILING and

FLOOR intrinsics

Nested WHERE constructs, masked

ELSEWHERE statement, and named

WHERE constructs

Comments allowed in namelist input

Generic identifier in END INTERFACE statements

Minimal FORMAT edit descriptor field width

Detection of obsolescent and/or deleted features

Linux

Alpha

CVF

Windows x86

OpenVMS

I64 and

Alpha

HP Fortran flags these deleted and obsolescent features but fully supports them.

CF77

OpenVMS

Alpha

CF77

OpenVMS

VAX

B.2 Major Language Features for Compatibility with Compaq

Fortran 77 for OpenVMS Systems

To simplify porting Compaq Fortran 77 applications from OpenVMS VAX systems to HP Fortran on OpenVMS I64 or OpenVMS Alpha systems, the following features (extensions) are provided with HP Fortran:

• HP Fortran provides LIB$ESTABLISH and LIB$REVERT as intrinsic functions for compatibility with Compaq Fortran 77 for OpenVMS VAX

Systems condition handling; see Chapter 14.

B–4 Compatibility: Compaq Fortran 77 and HP Fortran

• HP Fortran provides FOR$RAB as an intrinsic function and it should not be declared as EXTERNAL; see Section 11.2.3.

• FORSYSDEF parameter definitions for use with OpenVMS system services

(see Appendix E).

• The /VMS qualifier (the default) makes the run-time environment behave more like Compaq Fortran 77 for OpenVMS VAX Systems (see

Section 2.3.50).

• Compaq Fortran 77 extensions not part of the Fortran 90 standard that are supported as extensions by HP Fortran for OpenVMS Alpha Systems include the following:

Record structures (STRUCTURE and RECORD statements)

Indexed sequential files, relative files, and keyed access

USEROPEN routines for RMS control block access

I/O statements, including PRINT, ACCEPT, TYPE, DELETE, and

UNLOCK

I/O statement specifiers, such as the INQUIRE statement specifiers

CARRIAGECONTROL, CONVERT, ORGANIZATION, and

RECORDTYPE

Certain data types, including 8-byte INTEGER and LOGICAL variables (available on Alpha systems) and 16-byte REAL variables.

REAL (KIND=16) data is provided in Alpha X_float format (not VAX

H_float format)

Size specifiers for data declaration statements, such as INTEGER*4, in addition to the KIND type parameter

The POINTER statement and its associated data type (CRAY pointers)

The typeless PARAMETER statement

The VOLATILE statement

The AUTOMATIC and STATIC statements

Built-in functions used in argument lists, such as %VAL and %LOC

Hollerith constants

Variable-format expressions

Certain intrinsic functions

The tab source form (resembles fixed-source form)

Compatibility: Compaq Fortran 77 and HP Fortran B–5

I/O formatting descriptors

Additional language features, including the DEFINE FILE, ENCODE,

DECODE, and VIRTUAL statements

For More Information:

• On the HP Fortran language, see the HP Fortran for OpenVMS Language

Reference Manual.

B.3 Language Features and Interpretation Differences

Between Compaq Fortran 77 and HP Fortran on

OpenVMS Systems

This section lists Compaq Fortran 77 extensions to the FORTRAN-77 standard that are interpretation differences or are not included in HP Fortran for

OpenVMS I64 or OpenVMS Alpha systems. Where appropriate, this list indicates equivalent HP Fortran language features.

HP Fortran conforms to the Fortran 90 and Fortran 95 standards. The Fortran

90 standard is a superset of the FORTRAN-77 standard. The Fortran 95 standard deletes some FORTRAN-77 features from the Fortran 90 standard.

HP Fortran fully supports all of these deleted features (see the HP Fortran for

OpenVMS Language Reference Manual).

HP Fortran provides many but not all of the FORTRAN-77 extensions provided by Compaq Fortran 77.

B.3.1 Compaq Fortran 77 for OpenVMS Language Features Not

Implemented

The following FORTRAN-77 extensions provided by Compaq Fortran 77 on

OpenVMS systems (both Alpha and VAX hardware) are not provided by HP

Fortran for OpenVMS I64 or OpenVMS Alpha systems:

• Octal notation for integer constants is not part of the HP Fortran language.

Compaq Fortran 77 for OpenVMS Alpha Systems supports this feature only when the /VMS qualifier is in effect (default). For example:

I = "0014 ! Assigns 12 to I, not supported by HP Fortran

• The HP Fortran language prohibits dummy arguments with nonconstant bounds from being a namelist item. For example:

B–6 Compatibility: Compaq Fortran 77 and HP Fortran

SUBROUTINE FOO(A,N)

DIMENSION A(N),B(10)

NAMELIST /N1/ A

NAMELIST /N2/ B

END SUBROUTINE

! Incorrect

! Correct

• HP Fortran does not recognize certain hexadecimal and octal constants in

DATA statements, such as those used in the following program:

INTEGER I, J

DATA I/O20101/, J/Z20/

TYPE *, I, J

END

B.3.2 Compaq Fortran 77 for OpenVMS VAX Systems Language

Features Not Implemented

Certain language features are available in Compaq Fortran 77 for OpenVMS

VAX systems, but are not supported in HP Fortran for OpenVMS I64 or

OpenVMS Alpha systems. These features include features supported by the

VAX architecture, VAX hardware support, and older language extensions:

• Automatic decomposition features of FORTRAN /PARALLEL=

(AUTOMATIC). For information on a performance preprocessor that allows parallel execution, see Section 5.1.1.

• Manual (directed) decomposition features of FORTRAN /PARALLEL=

(MANUAL) using the CPAR$ directives, such as CPAR$ DO_PARALLEL.

For information on a performance preprocessor that allows parallel execution, see Section 5.1.1.

• The following I/O and error subroutines for PDP-11 compatibility:

ASSIGN

ERRSET

ERRTST

FDBSET

IRAD50

RAD50

R50ASC

USEREX

When porting existing programs, calls to ASSIGN, CLOSE, and FBDSET should be replaced with the appropriate OPEN statement. (You might consider converting DEFINE FILE statements at the same time, even though HP Fortran does support the DEFINE FILE statement.)

In place of ERRSET and ERRTST, OpenVMS condition handling might be used.

• Radix-50 constants in the form nRxxx

For existing programs being ported, radix 50 constants and the IRAD50,

RAD50 and R50ASC routines should be replaced by data encoded in ASCII using CHARACTER declared data.

Compatibility: Compaq Fortran 77 and HP Fortran B–7

• Numeric local variables are usually (but not always) initialized to a zero value, depending on the level of optimization used. To guarantee that a value will be initialized to zero under all circumstances, use an explicit assignment or DATA statement.

• Character constant actual arguments must be associated with character dummy arguments, not numeric dummy arguments, if source program units are compiled separately. (Compaq Fortran 77 for OpenVMS VAX

Systems passed ’A’ by reference if the dummy argument was numeric.)

To allow character constant actual arguments to be associated with numeric dummy arguments, specify the /BY_REF_CALL qualifier on the

FORTRAN command line (see Section 2.3.9).

The following language features are available in Compaq Fortran 77 for

OpenVMS VAX systems, but are not supported in HP Fortran because of architectural differences between OpenVMS I64 and OpenVMS Alpha systems and OpenVMS VAX systems:

• Certain FORSYSDEF symbol definition library modules might be specific to the VAX or Itanium or Alpha architecture. For information on FORSYSDEF text library modules, see Appendix E.

• Precise exception control

Compaq Fortran 77 for OpenVMS VAX Systems provides precise reporting of run-time exceptions. For performance reasons on OpenVMS I64 and

OpenVMS Alpha systems, the default FORTRAN command behavior is that exceptions are usually reported after the instruction causing the exception. You can request precise exception reporting using the

FORTRAN command /SYNCHRONOUS_EXCEPTIONS (Alpha only) qualifier (see Section 2.3.46). For information on error and condition handling, see Chapter 7 and Chapter 14.

• The REAL*16 H_float data type supported on OpenVMS VAX systems

The REAL (KIND=16) floating-point format on OpenVMS I64 and

OpenVMS Alpha systems is X_float (see Chapter 8). For information on the VAX H_float data type, see Section B.8.

• VAX support for D_float, F_float, and G_float

The OpenVMS Alpha instruction set does not support D_float computations, and the OpenVMS I64 instruction set does not support

D_float, F_float or G_float computations. As a result, any data stored in those formats is converted to a native format for arithmetic computations and then converted back to its original format. On Alpha systems, the native format used for D_float is G_float. On I64 systems, S_float is used for F_float data, and T_float is used for D_float and G_float data.

B–8 Compatibility: Compaq Fortran 77 and HP Fortran

This means that for programs that perform many floating-point computations, using D_float data on Alpha systems is slower than using

G_float or T_float data. Similarly, using D_float, F_float, or G_float data on I64 systems is slower than using S_float or T_float data. Additionally, due to the conversions involved, the results might differ from native VAX

D_float, F_float, and G_float computations and results.

Use the /FLOAT qualifier to specify the floating-point format (see

Section 2.3.22).

To create an HP Fortran application program to convert D_float data to

G_float or T_float format, use the file conversion methods described in

Chapter 9.

• Vectorization capabilities

Vectorization, including /VECTOR and its related qualifiers, and the

CDEC$ INIT_DEP_FWD directive are not supported. The Alpha processor provides instruction pipelining and other features that resemble vectorization capabilities.

B.3.3 Compaq Fortran 77 for OpenVMS Language Interpretation

Differences

The following FORTRAN-77 extensions provided by Compaq Fortran 77 on

OpenVMS systems (both Alpha and VAX hardware) are interpreted differently by HP Fortran.

• The HP Fortran compiler discards leading zeros for "disp" in the STOP statement. For example:

STOP 001 ! Prints 1 instead of 001

• When a single-precision constant is assigned to a double-precision variable,

Compaq Fortran 77 evaluates the constant in double precision, whereas HP

Fortran evaluates the constant in single precision (by default).

You can request that a single-precision constant assigned to a doubleprecision variable be evaluated in double precision, specify the FORTRAN command /ASSUME=FP_CONSTANT qualifier. The Fortran 90 standard requires that the constant be evaluated in single precision, but this can make calculated results differ between Compaq Fortran 77 and HP

Fortran.

In the example below, Compaq Fortran 77 assigns identical values to D1 and D2, whereas HP Fortran obeys the standard and assigns a less precise value to D1.

Compatibility: Compaq Fortran 77 and HP Fortran B–9

For example:

REAL*8 D1,D2

DATA D1 /2.71828182846182/ ! Incorrect - only REAL*4 value

DATA D2 /2.71828182846182D0/ ! Correct - REAL*8 value

• The names of intrinsics introduced by HP Fortran may conflict with the names of existing external procedures if the procedures were not specified in an EXTERNAL declaration. For example:

EXTERNAL SUM

REAL A(10),B(10)

S = SUM(A) ! Correct - invokes external function

T = DOT_PRODUCT(A,B) ! Incorrect - invokes intrinsic function

• When writing namelist external records, HP Fortran uses the syntax for namelist external records specified by the Fortran 90 standard, rather than the Compaq Fortran 77 syntax (an extension to the FORTRAN-77 and

Fortran 90 standards).

Consider the following program:

INTEGER I

NAMELIST /N/ I

I = 5

PRINT N

END

When this program is run after being compiled by the FORTRAN command, the following output appears:

$ FORTRAN TEST.F

$ LINK TEST

$ RUN TEST

= 5

When this program is run after being compiled by the FORTRAN command with the /OLDF77 qualifier, the following output appears:

$ FORTRAN /OLDF77 TEST.F

$ LINK TEST

$ RUN TEST

$END

= 5

HP Fortran accepts Fortran 90 namelist syntax and Compaq Fortran 77 namelist syntax for reading records.

B–10 Compatibility: Compaq Fortran 77 and HP Fortran

• HP Fortran does not support C-style escape sequences in standard character literals. Use the C string literal syntax extension or the CHAR intrinsic instead. For example:

CHARACTER*2 CRLF

CRLF = ’\r\n’

CRLF = ’\r\n’C

! Incorrect

! Correct

CRLF = CHAR(13)//CHAR(10) ! Standard-conforming alternative

• HP Fortran inserts a leading blank when doing list-directed I/O to an internal file. Compaq Fortran 77 does this only when the /VMS qualifier is in effect (default) on OpenVMS Alpha Systems. For example:

CHARACTER*10 C

WRITE(C,*) ’FOO’ ! C = ’ FOO’

• Compaq Fortran 77 and HP Fortran produce different output for a real value whose data magnitude is 0 with a G field descriptor. For example:

X = 0.0

WRITE(*,100) X

100 FORMAT(G12.4)

! Compaq Fortran 77 prints 0.0000E+00

! HP Fortran prints 0.000

• HP Fortran does not allow certain intrinsic procedures (such as SQRT) in constant expressions for array bounds. For example:

REAL A(SQRT(31.5))

END

• Compaq Fortran 77 returns UNKNOWN while HP Fortran returns

UNDEFINED when the ACCESS, BLANK, and FORM characteristics cannot be determined. For example:

INQUIRE(20,ACCESS=acc,BLANK=blk,FORM=form)

• HP Fortran does not allow extraneous parentheses in I/O lists. For example: write(*,*) ((i,i=1,1),(j,j=1,2))

• HP Fortran does not allow control characters within quoted strings, unless you use the C-string extension. For example: character*5 c c = ’ab\nef’ !

not allowed c = ’ab\nef’C !

allowed end

• HP Fortran, like Compaq Fortran 77, supports the use of character literal constants (such as ’ABC’ or "ABC") in numeric contexts, where they are treated as Hollerith constants.

Compatibility: Compaq Fortran 77 and HP Fortran B–11

Compaq Fortran 77 also allows character PARAMETER constants (typed and untyped) and character constant expressions (using the // operator) in numeric constants as an undocumented extension.

HP Fortran does allow character PARAMETER constants in numeric contexts, but does not allow character expressions. For example, the following is valid for Compaq Fortran 77, but will result in an error message from HP Fortran:

REAL*8 R

R = ’abc’ // ’def’

WRITE (6,*) R

END

HP Fortran does allow PARAMETER constants:

PARAMETER abcdef = ’abc’ // ’def’

REAL*8 R

R = abcdef

WRITE (6,*) R

END

• Compaq Fortran 77 namelist output formats character data delimited with apostrophes. For example, consider:

CHARACTER CHAR4*4

NAMELIST /CN100/ CHAR4

CHAR4 = ’ABCD’

WRITE(20,CN100)

CLOSE (20)

This produces the following output file:

$CN100

CHAR4 = ’ABCD’

$END

This file is read by:

READ (20, CN100)

In contrast, HP Fortran produces the following output file by default:

&CN100

CHAR4 = ABCD

When read, this generates a syntax error in NAMELIST input error.

To produce delimited strings from namelist output that can be read by namelist input, use program.

DELIM="’" in the OPEN statement of an HP Fortran

B–12 Compatibility: Compaq Fortran 77 and HP Fortran

For More Information:

• On argument passing between HP Fortran and Compaq Fortran 77, see

Section 10.9.

• On the HP Fortran language, see the HP Fortran for OpenVMS Language

Reference Manual.

B.3.4 Compaq Fortran 77 for OpenVMS VAX Systems Interpretation

Differences

The following language features are interpreted differently in Compaq Fortran

77 for OpenVMS VAX Systems and HP Fortran for OpenVMS I64 or OpenVMS

Alpha systems:

• Random number generator (RAN)

The RAN function generates a different pattern of numbers in HP Fortran than in Compaq Fortran 77 for OpenVMS VAX Systems for the same random seed. (The RAN and RANDU functions are provided for Compaq

Fortran 77 for OpenVMS VAX Systems compatibility. See the HP Fortran

for OpenVMS Language Reference Manual.)

• INQUIRE(RECL) for unformatted files

INQUIRE(RECL) for unformatted files with the default RECL unit

(longwords) gives different answers for Compaq Fortran 77 for OpenVMS

VAX Systems and HP Fortran if the existing file has a record length that is not a multiple of 4 bytes. To prevent this difference, use

/ASSUME=BYTERECL and specify the proper RECL in bytes in the

OPEN statement.

• Hollerith constants in formatted I/O statements

Compaq Fortran 77 for OpenVMS VAX Systems and HP Fortran behave differently if either of the following occurs:

Two different I/O statements refer to the same CHARACTER

PARAMETER constant as their format specifier, for example:

CHARACTER*(*) FMT2

PARAMETER (FMT2=’(10Habcdefghij)’)

READ (5, FMT2)

WRITE (6, FMT2)

Two different I/O statements use the identical character constant as their format specifier, for example:

READ (5, ’(10Habcdefghij)’)

WRITE (6, ’(10Habcdefghij)’)

Compatibility: Compaq Fortran 77 and HP Fortran B–13

In Compaq Fortran 77 for OpenVMS VAX Systems, the value obtained by the READ statement is the output of the WRITE statement (FMT2 is ignored). However, in HP Fortran, the output of the WRITE statement is

"abcdefghij". (The value read by the READ statement has no effect on the value written by the WRITE statement.)

B.4 Improved HP Fortran Compiler Diagnostic Detection

The following language features are detected differently by HP Fortran than

Compaq Fortran 77:

• The HP Fortran compiler enforces the constraint that the ‘‘nlist’’ in an

EQUIVALENCE statement must contain at least two variables. For example:

EQUIVALENCE (X) ! Incorrect

EQUIVALENCE (Y,Z) ! Correct

• The HP Fortran compiler enforces the constraint that entry points in a

SUBROUTINE must not be typed. For example:

SUBROUTINE ABCXYZ(I)

REAL ABC

I = I + 1

RETURN

! Incorrect ENTRY ABC

BAR = I + 1

RETURN

ENTRY XYZ ! Correct

I = I + 2

RETURN

END SUBROUTINE

• The HP Fortran compiler enforces the constraint that a type must appear before each list in an IMPLICIT statement. For example:

IMPLICIT REAL (A-C), (D-H) ! Incorrect

IMPLICIT REAL (O-S), REAL (T-Z) ! Correct

• The HP Fortran language disallows passing mismatched actual arguments to intrinsics with corresponding integer formal arguments. For example:

R = REAL(.TRUE.) ! Incorrect

R = REAL(1) ! Correct

• The HP Fortran compiler enforces the constraint that a simple list element in an I/O list must be a variable or an expression. For example:

READ (10,100) (I,J,K) ! Incorrect

READ (10,100) I,J,K ! Correct

B–14 Compatibility: Compaq Fortran 77 and HP Fortran

• The HP Fortran compiler enforces the constraint that if two operators are consecutive, the second operator must be a plus or a minus. For example:

I = J -.NOT.K

I = J - (.NOT.K)

! Incorrect

! Correct

• The HP Fortran compiler enforces the constraint that character entities with a length greater than 1 cannot be initialized with a bit constant in a

DATA statement. For example:

CHARACTER*1 C1

CHARACTER*4 C4

DATA C1/’FF’X/

DATA C4/’FFFFFFFF’X/

! Correct

! Incorrect

• The HP Fortran compiler enforces the requirement that edit descriptors in the FORMAT statement must be followed by a comma or slash separator.

For example:

1 FORMAT (SSF4.1)

2 FORMAT (SS,F4.1)

! Incorrect

! Correct

• The HP Fortran compiler enforces the constraint that the number and types of actual and formal statement function arguments must match (such as incorrect number of arguments). For example:

CHARACTER*4 C,C4,FUNC

FUNC()=C4

C=FUNC(1)

C=FUNC()

! Incorrect

! Correct

• The HP Fortran compiler detects the use of a format of the form Ew.dE0 at compile time. For example:

1 format(e16.8e0) ! HP Fortran detects error at compile time write(*,1) 5.0

! Compaq Fortran 77 compiles but an output

! conversion error occurs at run time

• HP Fortran detects passing of a statement function to a routine. For example: foo(x) = x * 2 call bar(foo) end

• The HP Fortran compiler enforces the constraint that a branch to a statement shared by one more DO statements must occur from within the innermost loop. For example:

Compatibility: Compaq Fortran 77 and HP Fortran B–15

DO 10 I = 1,10

IF (L1) GO TO 10 ! Incorrect

DO 10 J = 1,10

IF (L2) GO TO 10 ! Correct

10 CONTINUE

• The HP Fortran compiler enforces the constraint that a file must contain at least one program unit. For example, a source file containing only comment lines results in an error at the last line (end-of-file).

The Compaq Fortran 77 compiler compiles files containing less than one program unit.

• The HP Fortran compiler correctly detects misspellings of the

ASSOCIATEVARIABLE keyword to the OPEN statement. For example:

OPEN(1,ASSOCIATEVARIABLE = I) ! Correct

OPEN(2,ASSOCIATEDVARIABLE = J) ! Incorrect (extra D)

• The HP Fortran language enforces the constraint that the result of an operation is determined by the data types of its operands. For example:

INTEGER*8 I8

I8 = 2147483647+1 ! Incorrect. Produces less accurate

INTEGER*4 result from integer overflow

I8 = 2147483647_8 + 1_8 ! Correct

• The HP Fortran compiler enforces the constraint that an object can be typed only once. Compaq Fortran 77 issues a warning message and uses the first type. For example:

LOGICAL B,B ! Incorrect (B multiply declared)

• The HP Fortran compiler enforces the constraint that certain intrinsic procedures defined by the Fortran 95 standard cannot be passed as actual arguments. For example, Compaq Fortran 77 allows most intrinsic procedures to be passed as actual arguments, but the HP Fortran compiler only allows those defined by the Fortran 95 standard (issues an error message).

Consider the following program: program tstifx intrinsic ifix,int,sin call a(ifix) call a(int) call a(sin) stop end

B–16 Compatibility: Compaq Fortran 77 and HP Fortran

subroutine a(f) external f integer f print *, f(4.9) return end

The IFIX and INT intrinsic procedures cannot be passed as actual arguments (the compiler issues an error message). However, the SIN intrinsic is allowed to be passed as an actual argument by the Fortran 90 standard.

• HP Fortran reports character truncation with an error-level message, not as a warning.

The following program produces an error message during compilation with

HP Fortran, whereas Compaq Fortran 77 produces a warning message:

INIT5 = ’ABCDE’

INIT4 = ’ABCD’

INITLONG = ’ABCDEFGHIJKLMNOP’

PRINT 10, INIT5, INIT4, INITLONG

10 FORMAT (’ ALL 3 VALUES SHOULD BE THE SAME: ’ 3I)

END

• If your code invokes HP Fortran intrinsic procedures with the wrong number of arguments or an incorrect argument type, HP Fortran reports this with an error-level message, not with a warning. Possible causes include:

An HP Fortran intrinsic has been added with the same name as a user-defined subprogram and the user-defined subprogram needs to be declared as EXTERNAL.

An intrinsic that is an extension to an older Fortran standard is incompatible with a newer standard-conforming intrinsic (for example, the older RAN function that accepted two arguments).

The following program produces an error message during compilation with

HP Fortran, whereas Compaq Fortran 77 produces a warning message:

Compatibility: Compaq Fortran 77 and HP Fortran B–17

INTEGER ANOTHERCOUNT

ICOUNT=0

100 write(6,105) (ANOTHERCOUNT(ICOUNT), INT1=1,10)

105 FORMAT(’ correct if print integer values 1 through 10’ /10I7)

Q = 1.

R = .23

110 FORMAT(’ CORRECT = 1.23

RESULT = ’,f8.2)

END

S = SIN(Q,R)

WRITE (6,110) S

INTEGER FUNCTION ANOTHERCOUNT(ICOUNT)

ICOUNT=ICOUNT+1

ANOTHERCOUNT=ICOUNT

RETURN

END

REAL FUNCTION SIN(FIRST, SECOND)

SIN = FIRST + SECOND

RETURN

END

• HP Fortran reports missing commas in FORMAT descriptors with an error-level message, not as a warning.

The following program produces an error message during compilation with

HP Fortran, whereas Compaq Fortran 77 produces a warning message:

LOGICAL LOG/111/

TYPE 1,LOG

1 FORMAT(’ ’23X,’LOG=’O12)

END

In the preceding example, the correct coding (adding the missing comma) for the FORMAT statement is:

1 FORMAT(’ ’,23X,’LOG=’O12)

• HP Fortran generates an error when it encounters a 1-character source line containing a Ctrl/Z character, whereas Compaq Fortran 77 allows such a line (which is treated as a blank line).

• HP Fortran does not detect an extra comma in an I/O statement when the

/STANDARD qualifier is specified, whereas Compaq Fortran 77 with the same qualifier identifies an extra comma as an extension. For example:

WRITE(*,*) , P(J)

B–18 Compatibility: Compaq Fortran 77 and HP Fortran

• HP Fortran detects the use of a character variable within parentheses in an I/O statement. For example:

CHARACTER*10 CH/’(I5)’/

INTEGER I

READ CH,I ! Acceptable

READ (CH),I ! Generates error message, interpreted as an internal READ

END

• HP Fortran evaluates the exponentiation operator at compile time only if the exponent has an integer data type. Compaq Fortran 77 evaluates the exponentiation operator even when the exponent does not have an integer data type. For example:

PARAMETER ( X = 4.0 ** 1.1)

• HP Fortran detects an error when evaluating constants expressions that result in an NaN or Infinity exceptional value, while Compaq Fortran 77 allows such expressions. For example:

PARAMETER ( X = 4.0 / 0.0 )

For More Information:

• On passing arguments and returning function values between HP Fortran and Compaq Fortran 77, see Section 10.9.

• On HP Fortran procedure calling and argument passing, see Section 10.2.

• On the HP Fortran language, see the HP Fortran for OpenVMS Language

Reference Manual.

B.5 Compiler Command-Line Differences

This section summarizes the differences between HP Fortran and Compaq

Fortran 77 for OpenVMS Systems command lines.

The following commands initiate compilation on OpenVMS systems:

Platform

OpenVMS I64 systems

OpenVMS Alpha systems

OpenVMS VAX systems

Language

HP Fortran

Compaq Fortran 77

Command

FORTRAN

FORTRAN/OLD_F77

FORTRAN

Compatibility: Compaq Fortran 77 and HP Fortran B–19

Most qualifiers are the same between HP Fortran for OpenVMS Alpha systems and Compaq Fortran 77 for OpenVMS Alpha systems.

B.5.1 Qualifiers Not Available on OpenVMS VAX Systems

Table B–2 lists HP Fortran compiler qualifiers that have no equivalent Compaq

Fortran 77 Version 6.4 for OpenVMS VAX Systems qualifiers.

Table B–2 HP Fortran Qualifiers Without Equivalents in Compaq Fortran 77 for

OpenVMS VAX Systems

Qualifier Description

/ALIGNMENT=

[NO]SEQUENCE

/ANNOTATION

/ARCHITECTURE=keyword

/ASSUME=ALT_PARAM 1

/ASSUME=FP_CONSTANT

/ASSUME=MINUS0 1

/ASSUME=PROTECT_

CONSTANTS

/BY_REF_CALL

/CHECK=ARG_INFO (I64 only)

Specifies that components of derived types with the SEQUENCE attribute will obey whatever alignment rules are currently in use

(see Section 2.3.3).

Controls whether an annotated listing showing optimizations is included with the listing file (see Section 2.3.5).

Specifies the type of Alpha architecture code instructions generated for a particular program unit being compiled (see

Section 2.3.6).

Allows the alternate syntax for PARAMETER statements. The alternate form has no parentheses surrounding the list, and the form of the constant, rather than implicit or explicit typing, determines the data type of the variable (see Section 2.3.7).

Controls whether constants are evaluated in single or double precision (see Section 2.3.7). Compaq Fortran 77 always evaluates single-precision constants in double precision.

Controls whether the compiler uses Fortran 95 standard semantics for the IEEE floating-point value of -0.0 (minus zero) in the SIGN intrinsic, if the processor is capable of distinguishing the difference between -0.0 and +0.0 (see Section 2.3.7).

Specifies whether constant actual arguments can be changed (see

Section 2.3.7).

Allows character constant actual arguments to be associated with numeric dummy arguments (allowed by Compaq Fortran 77 for

OpenVMS VAX Systems; see Section 2.3.9).

Controls whether run-time checking of the actual argument list occurs (see Section 2.3.11).

This qualifier applies only to HP Fortran and does not apply to Compaq Fortran 77 on any platform.

(continued on next page)

B–20 Compatibility: Compaq Fortran 77 and HP Fortran

Table B–2 (Cont.) HP Fortran Qualifiers Without Equivalents in Compaq Fortran 77 for

OpenVMS VAX Systems

Qualifier

/CHECK=ARG_TEMP_

CREATED

/CHECK=FP_EXCEPTIONS

/CHECK=FP_MODE (I64 only)

/CHECK=POWER

/DOUBLE_SIZE

/FAST

/FLOAT

/GRANULARITY

/IEEE_MODE

/INTEGER_SIZE

/MODULE

/NAMES

/OPTIMIZE

Description

Issues a run-time warning message and continues execution if a temporary is created for an array actual argument (see

Section 2.3.11).

Controls whether messages about IEEE floating-point exceptional values are reported at run time (see Section 2.3.11).

Controls whether run-time checking of the current state of the processor’s floating-point status register (FPSR) occurs (see

Section 2.3.11).

Controls whether the compiler evaluates and returns a result for certain arithmetic expressions containing floating- point numbers and exponentiation (see Section 2.3.11).

Makes DOUBLE PRECISION declarations REAL (KIND=16) instead of REAL (KIND=8) (see Section 2.3.17).

Sets several qualifiers that improve run-time performance (see

Section 2.3.21).

Controls the format used for floating-point data (REAL or

COMPLEX) in memory, including the selection of either VAX

F_float or IEEE S_float for KIND=4 data and VAX G_float, VAX

D_float, or IEEE T_float for KIND=8 data (see Section 2.3.22).

Compaq Fortran 77 for OpenVMS VAX Systems provides the

/[NO]G_FLOAT qualifier.

Controls the granularity of data access for shared data (see

Section 2.3.23).

Controls how floating-point exceptions are handled for IEEE data

(see Section 2.3.24).

Controls the size of INTEGER and LOGICAL declarations (see

Section 2.3.26).

Controls where module files (.F90$MOD) are placed. If you omit this qualifier or specify /NOMODULE, the .F90$MOD files are placed in your current default directory (see Section 2.3.31).

Controls whether external names are converted to uppercase, lowercase, or as is (see Section 2.3.32).

Most keywords are not available on Compaq Fortran 77 for

OpenVMS VAX Systems, including INLINE, LOOPS, PIPELINE,

TUNE, and UNROLL (see Section 2.3.35).

(continued on next page)

Compatibility: Compaq Fortran 77 and HP Fortran B–21

Table B–2 (Cont.) HP Fortran Qualifiers Without Equivalents in Compaq Fortran 77 for

OpenVMS VAX Systems

Qualifier Description

/REAL_SIZE Controls the size of REAL and COMPLEX declarations (see

Section 2.3.37).

/REENTRANCY Specifies whether code generated for the main program and

Fortran procedures it calls will rely on threaded or asynchronous reentrancy (see Section 2.3.39).

/ROUNDING_MODE Controls how floating-point calculations are rounded for IEEE data (see Section 2.3.40).

/SEPARATE_COMPILATION Controls whether the HP Fortran compiler:

/SEVERITY 1

/SOURCE_FORM

/STANDARD

/SYNTAX_ONLY

/WARNINGS

/VMS

• Places individual compilation units as separate modules in the object file like Compaq Fortran 77 for OpenVMS VAX

Systems (/SEPARATE_COMPILATION)

• Groups compilation units as a single module in the object file

(/NOSEPARATE_COMPILATION, the default), which allows more interprocedure optimizations.

For more information, see Section 2.3.41.

Changes compiler diagnostic warning messages to have a severity of error instead of warning (see Section 2.3.42).

Controls whether the compiler expects free or fixed form source

(see Section 2.3.44).

Flags extensions to the Fortran 90 or Fortran 95 standards (see

Section 2.3.45).

Requests that only syntax checking occurs and no object file is created (see Section 2.3.47).

Certain keywords are not available on Compaq Fortran 77 for

OpenVMS VAX Systems (see Section 2.3.51).

Requests that HP Fortran use certain Compaq Fortran 77 for

OpenVMS VAX Systems conventions (see Section 2.3.50).

This qualifier applies only to HP Fortran and does not apply to Compaq Fortran 77 on any platform.

B.5.2 Qualifiers Specific to Compaq Fortran 77 for OpenVMS VAX

Systems

This section summarizes Compaq Fortran 77 for OpenVMS VAX Systems compiler options that have no equivalent HP Fortran options.

B–22 Compatibility: Compaq Fortran 77 and HP Fortran

Table B–3 lists compilation options that are specific to Compaq Fortran 77 for

OpenVMS VAX Systems Version 6.4.

Table B–3 Compaq Fortran 77 for OpenVMS VAX Systems Options Not in HP Fortran

Compaq Fortran 77 for OpenVMS

VAX Systems Qualifier Description

/BLAS=(INLINE,MAPPED)

/CHECK=ASSERTIONS

/DESIGN=[NO]COMMENTS

/DESIGN=[NO]PLACEHOLDERS

/DIRECTIVES=DEPENDENCE

Specifies whether Compaq Fortran 77 for OpenVMS VAX

Systems recognizes and inlines or maps the Basic Linear

Algebra Subroutines (BLAS).

Enables or disables assertion checking.

Analyzes program for design information.

Specifies whether specified compiler directives are used at compilation.

Supports parallel processing.

/PARALLEL=(MANUAL or

AUTOMATIC)

/SHOW=(DATA_DEPENDENCIES,

LOOPS)

Control whether the listing file includes:

• Diagnostics about loops that are ineligible for dependence analysis and data dependencies that inhibit vectorization or autodecomposition (DATA_

DEPENDENCIES)

• Reports about loop structures after compilation

(LOOPS)

/VECTOR

/WARNINGS=INLINE

Requests vector processing.

Controls whether the compiler prints informational diagnostic messages when it is unable to generate inline code for a reference to an intrinsic routine. Other

/WARNINGS keywords are only available with Compaq

Fortran 77 for OpenVMS VAX Systems, including

TRUNCATED_SOURCE.

All CPAR$ directives and certain CDEC$ directives associated with directed

(manual) decomposition and their associated qualifiers or keywords are also specific to Compaq Fortran 77 for OpenVMS VAX Systems.

For More Information:

• On the FORTRAN command and qualifiers, see Chapter 2.

• On the Compaq Fortran 77 compilation commands and options, see the appropriate Compaq Fortran 77 user manual.

Compatibility: Compaq Fortran 77 and HP Fortran B–23

B.6 Interoperability with Translated Shared Images

HP Fortran provides the ability to interoperate with translated shared images.

That is, when creating a native HP Fortran image, you can add certain qualifiers to the FORTRAN and LINK command lines to allow the resulting image to interoperate with translated shared images at image activation (run time).

To allow the use of translated shared images:

• On the FORTRAN command line, specify the /TIE qualifier.

• On the LINK command line, specify the /NONATIVE_ONLY qualifier

(default).

The created executable image contains code that allows the resulting executable image to interoperate with shared (installed) images, including allowing the Compaq Fortran 77 for OpenVMS VAX Systems RTL (FORRTL_

TV) to work with the HP Fortran RTL (DEC$FORRTL).

For More Information:

On porting, see Migrating an Application from OpenVMS VAX to OpenVMS

Alpha.

B.7 Porting Compaq Fortran 77 for OpenVMS VAX Systems

Data

Record types are identical for Compaq Fortran 77 on OpenVMS VAX Systems and HP Fortran on OpenVMS I64 or OpenVMS Alpha systems.

If you need to convert unformatted floating-point data, keep in mind that

Compaq Fortran 77 for OpenVMS VAX Systems programs (VAX hardware) stores:

• REAL*4 or COMPLEX*8 data in F_float format

• REAL*8 or COMPLEX*16 data in either D_float or G_float format

• REAL*16 data in H_float format.

HP Fortran programs (running on OpenVMS I64 or OpenVMS Alpha systems) store REAL*4, REAL*8, COMPLEX*8, and COMPLEX*16 data in one of the formats shown in Table B–4 and REAL*16 data in X_float format.

B–24 Compatibility: Compaq Fortran 77 and HP Fortran

Table B–4 Floating-Point Data Formats on OpenVMS VAX and OpenVMS I64 and Alpha Systems

Data Declaration OpenVMS VAX Formats OpenVMS I64 and Alpha Formats

REAL*4 and

COMPLEX*8

REAL*8 and

COMPLEX*16

REAL*16

VAX F_float

VAX D_float or

VAX G_float

VAX H_float

VAX F_float or IEEE S_float

VAX D_float

, VAX G_float, or IEEE

T_float

X_float format. You can convert VAX

H_float REAL*16 data to Alpha X_float format.

The D_float format on I64 and Alpha systems has less precision during computations than on VAX systems.

The floating-point data types supported by HP Fortran on OpenVMS systems are described in Chapter 8.

Example B–1 shows the use of the CVT$CONVERT_FLOAT RTL routine to convert VAX S_float data to VAX F_float format. This allows the converted value to be used as an argument to the LIB$WAIT routine.

The parameter definitions used in the CVT$CONVERT_FLOAT argument list

(such as CVT$K_IEEE_S) are included from the $CVTDEF library module in FORSYSDEF. The S_float value read as an argument is contained in the variable F_IN; the F_float value is returned by CVT$CONVERT_FLOAT to variable F_OUT.

Example B–1 Using the CVT$CONVERT_FLOAT Routine

! This program converts IEEE S_float data to VAX F_float format

! Compile with: $ F90/FLOAT=IEEE_FLOAT

PROGRAM CONVERT

INCLUDE ’($CVTDEF)’

REAL(KIND=4) F_IN

REAL(KIND=4) F_OUT

INTEGER ISTAT

F_IN = 20.0

PRINT *,’ Sample S_float input value is ’, F_IN

(continued on next page)

Compatibility: Compaq Fortran 77 and HP Fortran B–25

Example B–1 (Cont.) Using the CVT$CONVERT_FLOAT Routine

ISTAT=CVT$CONVERT_FLOAT(F_IN, %VAL(CVT$K_IEEE_S), F_OUT, &

%VAL(CVT$K_VAX_F), %VAL(CVT$M_ROUND_TO_NEAREST))

PRINT *,’Return status ISTAT’,ISTAT

IF (.NOT. ISTAT) CALL LIB$SIGNAL(%VAL(ISTAT))

PRINT *, ’ Waiting for specified time ’

CALL LIB$WAIT (F_OUT)

STOP

END PROGRAM CONVERT

B.8 VAX H_float Representation

This section describes the REAL*16 VAX H_float data formats used on

OpenVMS VAX systems. On OpenVMS I64 and OpenVMS Alpha systems,

REAL*16 (extended precision) data is always stored in IEEE X_float format.

With VAX floating-point data types, the binary radix point is to the left of the most-significant bit.

The REAL*16 H_float format is available only on OpenVMS VAX systems;

REAL*16 on OpenVMS I64 and OpenVMS Alpha systems use X_float format

(see Section 8.4.4).

As shown in Figure B–1, REAL*16 H_float data is 16 contiguous bytes starting on an arbitrary byte boundary. The bits are labeled from the right, 0 through

127.

The form of a REAL*16 (H_float) data is sign magnitude with bit 15 the sign bit, bits 14:0 an excess 16384 binary exponent, and bits 127:16 a normalized 113-bit fraction with the redundant most significant fraction bit not represented.

The value of H_float data is in the approximate range 0.84*10**–4932 through

0.59*10**4932. The precision of H_float data is approximately one part in

2**112 or typically 33 decimal digits.

B–26 Compatibility: Compaq Fortran 77 and HP Fortran

Figure B–1 VAX H_float REAL*16 Representation (VAX Systems)

0 15

EXPONENT :A

FRACTION :A+2

FRACTION

:A+4

:A+6

FRACTION

:A+8

:A+10

127

FRACTION

:A+12

:A+14

112

ZK−0805−GE

Compatibility: Compaq Fortran 77 and HP Fortran B–27

Diagnostic Messages

This appendix describes:

• Section C.1, Overview of Diagnostic Messages

• Section C.2, Diagnostic Messages from the HP Fortran Compiler

• Section C.3, Messages from the HP Fortran Run-Time System

C.1 Overview of Diagnostic Messages

Diagnostic messages related to an HP Fortran program can come from the compiler, the linker, or the HP Fortran run-time system:

• The HP Fortran compiler detects syntax errors in the source program, such as unmatched parentheses, invalid characters, misspelled specifiers, and missing or invalid parameters. HP Fortran compiler messages are described in Section C.2.

• The linker detects errors in object file format and source program errors such as undefined symbols. Linker messages are described in the

OpenVMS System Messages and Recovery Procedures Reference Manual.

Or you can use the DCL command HELP/MESSAGE.

• The HP Fortran run-time system reports errors that occur during program execution. HP Fortran run-time messages are listed and described in

Section C.3 and DCL HELP (enter HELP FORTRAN).

These messages are displayed on your terminal or in your log file. The format of the messages is:

%facility-severity-mnemonic, message_text

Diagnostic Messages C–1

The contents of the fields of information in diagnostic messages are as follows:

% facility

The percent sign identifies the line as a message.

A 2-, 3-, or 4-letter facility code that identifies the origin of the message, whether it came from the compiler (F90), the linker (LINK), or the run-time system (FOR, SS, or MTH).

severity A single character that determines message severity. The four levels of error message severity are: Fatal (F), Error (E), Warning (W), and

Informational (I). The definition of each severity level depends on the facility issuing the message.

mnemonic A 6- to 9-character name that uniquely identifies that message.

message_text Explains the event that caused the message to be generated.

C.2 Diagnostic Messages from the HP Fortran Compiler

A diagnostic message issued by the compiler describes the detected error and, in some cases, contains an indication of the action taken by the compiler in response to the error.

Besides reporting errors detected in source program syntax, the compiler issues messages indicating errors that involve the compiler itself, such as I/O errors.

C.2.1 Source Program Diagnostic Messages

The severity level of source program diagnostic messages, in order of greatest to least severity, are as follows:

Severity

Code

Description

Fatal; must be corrected before the program can be compiled. No object file is produced if an F-severity error is detected during compilation.

Error; should be corrected. No object file is produced if an F-severity error is detected during compilation.

Warning; should be investigated by checking the statements to which Wseverity diagnostic messages apply. Warnings are issued for statements that use acceptable, but nonstandard, syntax and for statements corrected by the compiler. An object file is produced, but the program results may be incorrect.

Note that W-severity messages are produced unless the /NOWARNINGS qualifier is specified in the FORTRAN command.

Information; not an error message and does not call for corrective action.

However, the I-severity message informs you that either a correct HP

Fortran statement may have unexpected results or you have used an HP

Fortran extension to the Fortran 90 or Fortran 95 standard.

C–2 Diagnostic Messages

Typing mistakes are a likely cause of syntax errors; they can cause the compiler to generate misleading diagnostic messages. Beware especially of the following:

• Missing comma or parenthesis in a complicated expression or FORMAT statement.

• Misspelled variable names or (depending on the compilation qualifiers used) case-mismatched variable names. The compiler may not detect this error, so execution can be affected.

• Inadvertent line continuation mark. This can cause a diagnostic message for the preceding line.

• When compiling using fixed-form source files, if the statement line extends past column 72, this can cause the statement to terminate early (unless you specified the /EXTEND_SOURCE qualifier).

• Confusion between the digit 0 and the uppercase letter O. This can result in variable names that appear identical to you but not to the compiler.

• Nonprinting ASCII characters encountered in HP Fortran programs are generally interpreted as a space character and a warning message appears. For more information on valid nonprinting space characters, see

Section 2.3.28.

Because a diagnostic message indicates only the immediate cause, you should always check the entire source statement carefully.

The following examples show how source program diagnostic messages are displayed in interactive mode on your screen.

40 FORMAT (I3,)

..................^

%F90-E-ERROR, An extra comma appears in the format list.

at line number 13 in file DISK$:[USER]SAMP_MESS.FOR;4

GO TO 66

..............^

%F90-E-ERROR, This label is undefined.

[66] at line number 18 in file DISK$:[USER]SAMP_MESS.FOR;4

Example C–1 shows how these messages appear in listings.

Diagnostic Messages C–3

Example C–1 Sample Diagnostic Messages (Listing Format)

MORTGAGE 30-MAR-1995 14:19:21 HP Fortran Xn.n-xxx Page 1

30-MAR-1995 14:18:48 DISK$:[USER]SAMP_MESS.F90;1

1 !

Program to calculate monthly mortgage payments

PROGRAM MORTGAGE

5 TYPE 10

6 10 FORMAT (’ ENTER AMOUNT OF MORTGAGE ’)

7 ACCEPT 20, IPV

8 20 FORMAT (I6)

10 TYPE 30

11 30 FORMAT (’ ENTER LENGTH OF MORTGAGE IN MONTHS ’)

12 ACCEPT 40, IMON

13 40 FORMAT (I3,)

................1

%F90-E-ERROR, An extra comma appears in the format list.

at line number 13 in file DISK$:[USER]SAMP_MESS.F90;1

14 TYPE 50

15 50 FORMAT (’ ENTER ANNUAL INTEREST RATE ’)

16 ACCEPT 60, YINT

17 60 FORMAT (F6.4)

18 GO TO 66

............1

%F90-E-ERROR, This label is undefined.

[66] at line number 18 in file DISK$:[USER]SAMP_MESS.F90;1

19 65 YI = YINT/12

20 IMON = -IMON

FIPV = IPV * YI

YI = YI + 1

! Get monthly rate

FIMON = YI**IMON

FIMON = 1 - FIMON

FMNTHLY = FIPV/FIMON

27 TYPE 70, FMNTHLY

28 70 FORMAT (’ MONTHLY PAYMENT EQUALS ’,F7.3 )

STOP

END PROGRAM MORTGAGE

C.2.2 Compiler-Fatal Diagnostic Messages

Conditions can be encountered of such severity that compilation must be terminated at once. These conditions are caused by hardware errors, software errors, and errors that require changing the FORTRAN command. Printed messages have the form:

%F90-F-MNEMONIC, error_text

C–4 Diagnostic Messages

The first line of the message contains the appropriate file specification or keyword involved in the error. The operating system supplies more specific information about the error whenever possible. For example, a file read error might produce the following error message:

%F90-F-ERROR, error reading _DBA0:[SMITH]MAIN.FOR;3

-RMS-W-RTB, 512 byte record too big for user’s buffer

-F90-F-ABORT, abort

The secondary operating system (in this case the RMS facility) message provides helpful information about the actual cause of the error, as described in the OpenVMS System Messages and Recovery Procedures Reference Manual or the equivalent OpenVMS HELP/MESSAGE facility.

C.3 Messages from the HP Fortran Run-Time System

Errors that occur during execution of your HP Fortran program are reported by diagnostic messages from the HP Fortran Run-Time Library (RTL).

These messages may result from hardware conditions, file system errors, errors detected by RMS, errors that occur during transfer of data between the program and an internal record, computations that cause overflow or underflow, incorrect calls to the HP Fortran RTL, problems in array descriptions, and conditions detected by the operating system.

As described in Section 7.2, the severity of run-time diagnostic messages can be fatal (F), error (E), warning (W), and informational (I).

The following example shows how run-time messages appear:

%FOR-F-ADJARRDIM, adjustable array dimension error

Table C–1 is an alphabetical list of run-time diagnostic messages, without the message prefixes FOR, SS, and MTH. (Refer to Table 7–1 for a list of the messages in error-number sequence.) For each message, Table C–1 gives a mnemonic, the message number, the severity of the message, the message text, and an explanation of the message.

Diagnostic Messages C–5

You can also view a description of specified messages using the following command:

$ HELP FORTRAN RUN_TIME

This displays the mnemonics of all HP Fortran run-time diagnostic messages.

You can abbreviate the HELP command words and specify a specific error mnemonic, such as:

$ HELP FORTRAN RUN FILNOTFOU

Table C–1 Run-Time Error Messages and Explanations

Mnemonic Number Severity Code, Message Text, and Explanation

ADJARRDIM 93 F, adjustable array dimension error

Upon entry to a subprogram, one of the following errors was detected during the evaluation of dimensioning information:

• An upper-dimension bound was less than a lower-dimension bound.

• The dimensions implied an array that was larger than addressable memory.

ARRSIZEOVF

ASSERTERR

ATTACCNON

179

145

F, Cannot allocate array — overflow on array size calculation

An attempt to dynamically allocate storage for an array failed because the required storage size exceeds addressable memory.

F, assertion error

The HP Fortran RTL encountered an assertion error. Please report the problem to HP.

F, attempt to access non-existent record

One of the following conditions occurred:

• A direct access READ, FIND, or DELETE statement attempted to access a nonexistent record from a relative organization file.

• A direct access READ or FIND statement attempted to access beyond the end of a sequential organization file.

• A keyed access READ statement attempted to access a nonexistent record from an indexed organization file.

(continued on next page)

C–6 Diagnostic Messages

Table C–1 (Cont.) Run-Time Error Messages and Explanations

Mnemonic

BACERR

Number Severity Code, Message Text, and Explanation

23 F, BACKSPACE error

During execution of a BACKSPACE statement, One of the following conditions occurred:

• The file was not a sequential organization file.

• The file was not opened for sequential access. (A unit opened for append access must not be backspaced until a REWIND statement is executed for that unit.)

• RMS (Record Management Services) detected an error condition during execution of a BACKSPACE statement.

BUG_CHECK 8

CLOERR

DELERR

DIRIO_KEY

258

F, internal consistency check failure

Internal severe error. Please check that the program is correct.

Recompile if an error existed in the program.

If this error persists, report the problem to HP.

F, CLOSE error

An error condition was detected by RMS during execution of a

CLOSE statement.

F, DELETE error

During execution of a DELETE statement, one of the following conditions occurred:

• On a direct access DELETE, the file that did not have relative organization.

• On a current record DELETE, the file did not have relative or indexed organization, or the file was opened for direct access.

• RMS detected an error condition during execution of a

DELETE statement.

F, direct-access I/O to unit open for keyed access

The OPEN statement for this unit number specified keyed access and the I/O statement specifies direct access. Check the OPEN statement and make sure the I/O statement uses the correct unit number and type of access. (For more information on statements, see the HP Fortran for OpenVMS Language Reference Manual.)

(continued on next page)

Diagnostic Messages C–7

Table C–1 (Cont.) Run-Time Error Messages and Explanations

Mnemonic

DIV

DUPFILSPE

ENDDURREA

Number Severity Code, Message Text, and Explanation

178

F, divide by zero

A floating point or integer divide by zero exception occurred.

F, duplicate file specifications

Multiple attempts were made to specify file attributes without an intervening close operation. A DEFINE FILE statement was followed by another DEFINE FILE statement or by an OPEN statement.

F, end-of-file during read

One of the following conditions occurred:

• An RMS end-of-file condition was encountered during execution of a READ statement that did not contain an

END, ERR, or IOSTAT specification.

• An end-of-file record written by the ENDFILE statement was encountered during execution of a READ statement that did not contain an END, ERR, or IOSTAT specification.

• An attempt was made to read past the end of an internal file character string or array during execution of a READ statement that did not contain an END, ERR, or IOSTAT specification.

ENDFILERR 33

ENDRECDUR 268

F, ENDFILE error

One of the following conditions occurred:

• The file was not a sequential organization file with variablelength records.

• The file was not opened for sequential or append access.

• An unformatted file did not contain segmented records.

• RMS detected an error during execution of an ENDFILE statement.

F, end of record during read

An end-of-record condition was encountered during execution of a nonadvancing I/O READ statement that did not specify the EOR branch specifier.

(continued on next page)

C–8 Diagnostic Messages

Table C–1 (Cont.) Run-Time Error Messages and Explanations

Mnemonic

ERRDURREA

ERRDURWRI

FILNAMSPE

FILNOTFOU

FINERR

Number Severity Code, Message Text, and Explanation

F, error during read

RMS detected an error condition during execution of a READ statement.

F, error during write

RMS detected an error condition during execution of a WRITE statement.

F, file name specification error

A file-name specification given to an OPEN or INQUIRE statement was not acceptable to RMS.

F, file not found

A file with the specified name could not be found during an open operation.

F, FIND error

RMS detected an error condition during execution of a FIND statement.

(continued on next page)

Diagnostic Messages C–9

Table C–1 (Cont.) Run-Time Error Messages and Explanations

Mnemonic

FLOCONFAI

Number Severity Code, Message Text, and Explanation

95 E, floating point conversion failed

The attempted unformatted read or write of nonnative floatingpoint data failed. One of the following conditions occurred for a nonnative floating-point value:

FLODIV0EXC

FLOINCEXC

299

297

• When using VAX data types in memory (/FLOAT=G_FLOAT or /FLOAT=D_FLOAT), the value exceeded the allowable maximum value for the equivalent native format and was set equal to invalid.

• When using VAX data types in memory (/FLOAT=G_FLOAT or /FLOAT=D_FLOAT), the value was infinity (plus or minus), Not-a-Number (NaN), or otherwise invalid and was set to invalid.

• When using IEEE data types in memory (/FLOAT=IEEE_

FLOAT), the value exceeded the allowable maximum value for the equivalent native format and was set equal to infinity

(plus or minus).

• When using IEEE data types in memory (/FLOAT=IEEE_

FLOAT), the value was infinity (plus or minus) and was set to infinity (plus or minus).

• When using IEEE data types in memory (/FLOAT=IEEE_

FLOAT), the value was invalid and was set to Not-a-Number

(NaN).

Make sure the correct file was specified. Make sure the record layout matches the format HP Fortran is expecting. Check that the correct nonnative floating-point data format was specified, as described in Chapter 9.

I, nn divide-by-zero traps

The total number of floating-point divide-by-zero traps encountered during program execution was nn. This summary message appears at program completion.

I, nn floating invalid traps

The total number of floating-point invalid data traps encountered during program execution was nn. This summary message appears at program completion.

(continued on next page)

C–10 Diagnostic Messages

Table C–1 (Cont.) Run-Time Error Messages and Explanations

Mnemonic

FLOINEEXC

FLOOVEMAT

FLOOVREXC

FLOUNDEXC

FLOUNDMAT

FLTDIV

FLTINE

FLTINV

Number Severity Code, Message Text, and Explanation

296

298

300

140

I, nn floating inexact traps

The total number of floating-point inexact data traps encountered during program execution was nn. This summary message appears at program completion.

F, floating overflow in math library

A floating overflow condition was detected during execution of a math library procedure.

I, nn floating overflow traps

The total number of floating-point overflow traps encountered during program execution was nn. This summary message appears at program completion.

I, nn floating underflow traps

The total number of floating-point underflow traps encountered during program execution was nn. This summary message appears at program completion.

E, floating underflow in math library

A floating underflow condition was detected during execution of a math library procedure. The result returned was zero.

E, zero divide

During a floating-point or decimal arithmetic operation, an attempt was made to divide by 0.0.

E, floating inexact

A floating-point arithmetic or conversion operation gave a result that differs from the mathematically exact result. This trap is reported if the rounded result of an IEEE operation is not exact.

E, floating invalid

During an arithmetic operation, the floating-point values used in a calculation were invalid for the type of operation requested, or invalid exceptional values. For example, when requesting a log of the floating-point values 0.0 or a negative number.

For certain arithmetic expressions, specifying the

/CHECK=NOPOWER qualifier can suppress this message (see

Section 2.3.11). For information on allowing exceptional IEEE values, see Section 2.3.24.

(continued on next page)

Diagnostic Messages C–11

Table C–1 (Cont.) Run-Time Error Messages and Explanations

Mnemonic

FLTOVF

FLTUND

FMTIO_UNF

FMYSYN

Number Severity Code, Message Text, and Explanation

257

E, arithmetic trap, floating overflow

During an arithmetic operation, a floating-point value exceeded the largest representable value for that data type. The result returned was the reserved operand, –0 for VAX-format floatingpoint and NaN for IEEE-format floating-point.

E, floating underflow

During an arithmetic operation, a floating-point value became less than the smallest finite value for that data type and was replaced with a value of zero. When using the /FLOAT=IEEE_

FLOAT, depending on the values of the /IEEE_MODE qualifier, the underflowed result was either set to zero or allowed to gradually underflow. See Chapter 8 for ranges of the various data types.

F, formatted I/O to unit open for unformatted transfers

Attempted formatted I/O (such as list-directed or namelist I/O) to a unit where the OPEN statement indicated the file was unformatted (FORM specifier). Check that the correct unit (file) was specified.

If the FORM specifier was not specified in the OPEN statement and the file should contain formatted data, specify

FORM=’FORMATTED’ in the OPEN statement. Otherwise, if appropriate, use unformatted I/O.

I, format syntax error at or near xxx

Check the statement containing xx, a character substring from the format string, for a format syntax error. For information about FORMAT statements, refer to the HP Fortran for

OpenVMS Language Reference Manual.

(continued on next page)

C–12 Diagnostic Messages

Table C–1 (Cont.) Run-Time Error Messages and Explanations

Mnemonic

FORVARMIS

Number Severity Code, Message Text, and Explanation

61 F or I, format/variable-type mismatch

An attempt was made either to read or write a real variable with an integer field descriptor (I, L, O, Z, B), or to read or write an integer or logical variable with a real field descriptor (D, E, or

F). If /CHECK=NOFORMAT is in effect (see Section 2.3.11), the severity is I (program continues). If execution continues, the following actions occurred:

INCFILORG 51

• If I, L, O, Z, B, conversion as if INTEGER (KIND=4).

• If D, E, or F, conversion as if REAL (KIND=4).

To suppress this error message, see Section 2.3.11.

F, inconsistent file organization

One of the following conditions occurred:

• The file organization specified in an OPEN statement did not match the organization of the existing file.

• The file organization of the existing file was inconsistent with the specified access mode; that is, direct access was specified with an indexed organization file, or keyed access was specified with a sequential or relative organization file.

INCKEYCHG 50 F, inconsistent key change or duplicate key

A WRITE or REWRITE statement accessing an indexed organization file caused a key field to change or be duplicated.

This condition was not allowed by the attributes of the file, as established when the file was created.

(continued on next page)

Diagnostic Messages C–13

Table C–1 (Cont.) Run-Time Error Messages and Explanations

Mnemonic

INCOPECLO

Number Severity Code, Message Text, and Explanation

46 F, inconsistent OPEN/CLOSE parameters

Specifications in an OPEN or CLOSE statement were inconsistent. Some invalid combinations follow:

• ACTION= ’ READ ’ or READONLY with STATUS= ’ NEW ’ or

STATUS= ’ SCRATCH ’

• ACCESS= ’ APPEND ’ with READONLY, ACTION= ’ READ ’ ,

STATUS= ’ NEW ’ , or STATUS= ’ SCRATCH ’

• DISPOSE= ’ SAVE ’ , ’ PRINT ’ , or ’ SUBMIT ’ with

STATUS= ’ SCRATCH ’

• DISPOSE= ’ DELETE ’ with READONLY or ACTION= ’ READ ’

• ACCESS= ’ APPEND ’ with STATUS= ’ REPLACE ’

• ACCESS= ’ DIRECT ’ or ’ KEYED ’ with

POSITION= ’ APPEND ’ , ’ ASIS ’ , or ’ REWIND ’

INCRECLEN 37

INCRECTYP

INFFORLOO

F, inconsistent record length

One of the following occurred:

• An attempt was made to create a new relative, indexed, or direct access file without specifying a record length.

• An existing file was opened in which the record length did not match the record size given in an OPEN or DEFINE

FILE statement.

• An attempt was made to write to a relative, indexed, or direct access file that was not correctly created or opened.

F, inconsistent record type

The RECORDTYPE value in an OPEN statement did not match the record type attribute of the existing file that was opened.

F, infinite format loop

The format associated with an I/O statement that included an I/O list had no field descriptors to use in transferring those values.

(continued on next page)

C–14 Diagnostic Messages

Table C–1 (Cont.) Run-Time Error Messages and Explanations

Mnemonic

INPCONERR

INPRECTOO

INPSTAREQ

INSVIRMEM

INTDIV

INTOVF

INVARGFOR

Number Severity Code, Message Text, and Explanation

F, input conversion error

During a formatted input operation, an invalid character was detected in an input field, or the input value overflowed the range representable in the input variable. The value of the variable was set to zero.

F, input record too long

A record was read that exceeded the explicit or default record length specified when the file was opened. To read the file, use an

OPEN statement with a RECL value of the appropriate size.

F, input statement requires too much data

Attempted to read more data than exists in a record with an unformatted READ statement or with a formatted sequential

READ statement from a file opened with a PAD specifier value of

’ NO ’ .

F, insufficient virtual memory

The HP Fortran Run-Time Library attempted to exceed its virtual page limit while dynamically allocating space. Inform your system manager that process quotas and/or system parameters need to be increased. For information about virtual memory use, see Section 1.2 and the HP Fortran Installation Guide for

OpenVMS I64 Systems or HP Fortran Installation Guide for

OpenVMS Alpha Systems.

F, integer zero divide

During an integer arithmetic operation, an attempt was made to divide by zero. The result of the operation was set to the dividend, which is equivalent to division by one ( 1 ).

F, integer overflow

During an arithmetic operation, an integer value exceeded its range. The result of the operation was the correct low-order part. Consider specifying a larger integer data size (or use the

/INTEGER_SIZE qualifier for INTEGER declarations without a kind or specifier.) See Chapter 8 for ranges of the various integer data types.

F, invalid argument to Fortran Run-Time Library

The HP Fortran compiler passed an invalid coded argument to the Run-Time Library. This can occur if the compiler is newer than the HP Fortran RTL in use.

(continued on next page)

Diagnostic Messages C–15

Table C–1 (Cont.) Run-Time Error Messages and Explanations

Mnemonic

INVARGMAT

INVDEALLOC

INVDEALLOC2

INVKEYSPE

INVLOGUNI

INVMATKEY

INVREALLOC

Number Severity Code, Message Text, and Explanation

153

173

151

F, invalid argument to math library

One of the mathematical procedures detected an invalid argument value.

F, allocatable array is not allocated

A Fortran allocatable array or pointer must already be allocated when you attempt to deallocate it. You must allocate the array or pointer before it can again be deallocated.

F, A pointer passed to DEALLOCATE points to an array that cannot be deallocated

A pointer that was passed to DEALLOCATE pointed to an explicit array, an array slice, or some other type of memory that could not be deallocated in a DEALLOCATE statement. Only whole arrays previously allocated with an ALLOCATE statement can be validly passed to DEALLOCATE.

F, invalid key specification

A key specification in an OPEN statement or in a keyed access

READ statement was invalid. For example, the key length may have been zero or greater than 255 bytes, or the key length may not conform to the key specification of the existing file.

F, invalid logical unit number

A logical unit number less than zero or greater than 2,147,483,647 was used in an I/O statement.

F, invalid key match specifier for key direction

A keyed READ used an invalid key match specifier for the direction of that key. Use KEYGE and KEYGT only on ascending keys. Use KEYLE and KEYLT only on descending keys. Use

KEYNXT and KEYNXTNE to avoid enforcement of key direction and match specifier.

F, allocatable array is already allocated

A Fortran allocatable array must not already be allocated when you attempt to allocate it. You must deallocate the array before it can again be allocated.

(continued on next page)

C–16 Diagnostic Messages

Table C–1 (Cont.) Run-Time Error Messages and Explanations

Mnemonic

INVREFVAR

Number Severity Code, Message Text, and Explanation

19 F, invalid reference to variable in NAMELIST input

The variable in error is shown as ‘‘varname’’ in the message text.

One of the following conditions occurred:

• The variable was not a member of the namelist group.

• An attempt was made to subscript the scalar variable.

• A subscript of the array variable was out-of-bounds.

• An array variable was specified with too many or too few subscripts for the variable.

• An attempt was made to specify a substring of a noncharacter variable or array name.

• A substring specifier of the character variable was out-ofbounds.

• A subscript or substring specifier of the variable was not an integer constant.

• An attempt was made to specify a substring using an unsubscripted array variable.

KEYIO_DIR 260

KEYVALERR

LISIO_SYN

F, keyed-access I/O to unit open for direct access

The OPEN for this unit number specified direct access and the

I/O statement specifies keyed access. Check the OPEN statement and make sure the I/O statement uses the correct unit number and type of access. (For more information on statements, see the

HP Fortran for OpenVMS Language Reference Manual.)

F, keyword value error in OPEN statement

An improper value was specified for an OPEN or CLOSE statement keyword specifier requiring a value.

F, list-directed I/O syntax error

The data in a list-directed input record had an invalid format, or the type of the constant was incompatible with the corresponding variable. The value of the variable was unchanged.

(continued on next page)

Diagnostic Messages C–17

Table C–1 (Cont.) Run-Time Error Messages and Explanations

Mnemonic

LOGZERNEG

MIXFILACC

Number Severity Code, Message Text, and Explanation

F, logarithm of zero or negative value

An attempt was made to take the logarithm of zero or a negative number. The result returned was –0 for VAX-format floatingpoint and NaN for IEEE-format floating-point.

F, mixed file access modes

One of the following conditions occurred:

• An attempt was made to use both formatted and unformatted operations on the same unit.

• An attempt was made to use an invalid combination of access modes on a unit, such as direct and sequential. The only valid combination is sequential and keyed access on a unit opened with ACCESS= ’ KEYED ’ .

• An attempt was made to execute a Fortran I/O statement on a logical unit that was opened by a program coded in a language other than Fortran.

NOTFORSPE

NO_CURREC

NO_SUCDEV

NULPTRERR

146

F, not a Fortran-specific error

An error occurred in the user program or in the HP Fortran RTL that was not a Fortran-specific error.

F, no current record

A REWRITE or current record DELETE operation was attempted when no current record was defined. To define the current record, execute a successful READ statement. You can optionally perform an INQUIRE statement on the logical unit after the

READ statement and before the REWRITE statement. No other operations on the logical unit may be performed between the

READ and REWRITE statements.

F, no such device

A file specification included an invalid or unknown device name when an OPEN operation was attempted.

F, null pointer error

Attempted to use a pointer that does not contain an address.

Modify the source program, recompile, and relink.

(continued on next page)

C–18 Diagnostic Messages

Table C–1 (Cont.) Run-Time Error Messages and Explanations

Mnemonic

OPEDEFREQ

Number Severity Code, Message Text, and Explanation

26 F, OPEN or DEFINE FILE required for keyed or direct access

One of the following conditions occurred:

• A direct access READ, WRITE, FIND, or DELETE statement specified a file that was not opened with a DEFINE

FILE statement or with an OPEN statement specifying

ACCESS= ’ DIRECT ’ .

• A keyed access READ statement specified a file that was not opened with an OPEN statement specifying

ACCESS= ’ KEYED ’ .

OPEFAI 30

OPEREQSEQ

OPERREQDIS

265

264

F, open failure

An error was detected by RMS while attempting to open a file in an OPEN, INQUIRE, or other I/O statement. This message is issued when the error condition is not one of the more common conditions for which specific error messages are provided. It can occur when an OPEN operation was attempted for one of the following:

• Segmented file that was not on a disk or a raw magnetic tape

• Standard process I/O file that had been closed

F, operation requires sequential file organization and access

Attempted BACKSPACE operation for a unit that is not connected to a sequential file opened for sequential access. Make sure the BACKSPACE statement specified the right unit number and the OPEN statement specified the correct file and access.

F, operation requires file to be on disk or tape

Attempted BACKSPACE operation for a unit that is not connected to a disk or tape device. Make sure the BACKSPACE statement specified the right unit number and the OPEN statement specified the correct device.

(continued on next page)

Diagnostic Messages C–19

Table C–1 (Cont.) Run-Time Error Messages and Explanations

Mnemonic

OUTCONERR

OUTSTAOVE

RANGEERR

RECIO_OPE

Number Severity Code, Message Text, and Explanation

150

E or I, output conversion error

During a formatted output operation, the value of a particular number could not be output in the specified field length without loss of significant digits. If /CHECK=NOOUTPUT_

CONVERSION is in effect (see Section 2.3.11), the severity is I (program continues). When /CHECK=NOOUTPUT_

CONVERSION is in effect or if no ERR address is defined for the I/O statement encountering this error, the program continues and the entire overflowed field is filled with asterisks to indicate the error in the output record.

F, output statement overflows record

An output statement attempted to transfer more data than would fit in the maximum record size.

F, range error

An integer value appears in a context where the value of the integer is outside the permissible range.

F, recursive I/O operation

While processing an I/O statement for a logical unit, another I/O operation on the same logical unit was attempted. One of the following conditions may have occurred:

• A function subprogram that performs I/O to the same logical unit was referenced in an expression in an I/O list or variable format expression.

• An I/O statement was executed at AST level for the same logical unit.

• An exception handler (or a procedure it called) executed an

I/O statement in response to a signal from an I/O statement for the same logical unit.

RECNUMOUT 25 F, record number outside range

A direct access READ, WRITE, or FIND statement specified a record number outside the range specified when the file was created.

(continued on next page)

C–20 Diagnostic Messages

Table C–1 (Cont.) Run-Time Error Messages and Explanations

Mnemonic

RESACQFAI

REWERR

Number Severity Code, Message Text, and Explanation

152

F, unresolved contention for HP Fortran RTL global resource.

Failed to acquire an HP Fortran RTL global resource for a reentrant routine.

For a multithreaded program, the requested global resource is held by a different thread in your program.

For a program using asynchronous handlers, the requested global resource is held by the calling part of the program (such as the main program) and your asynchronous handler attempted to acquire the same global resource.

F, REWIND error

One of the following conditions occurred:

• The file was not a sequential organization file.

• The file was not opened for sequential or append access.

• RMS detected an error condition during execution of a

REWIND statement.

REWRITERR

ROPRAND

SEGRECFOR

SEQIO_DIR

144

259

F, REWRITE error

RMS detected an error condition during execution of a REWRITE statement.

F, reserved operand

The HP Fortran encountered a reserved operand. Please report the problem to HP.

F, segmented record format error

An invalid segmented record control data word was detected in an unformatted sequential file. The file was probably either created with RECORDTYPE= ’ FIXED ’ or ’ VARIABLE ’ in effect, or was created by a program written in a language other than Fortran.

F, sequential-access I/O to unit open for direct access

The OPEN for this unit number specified direct access and the

I/O statement specifies sequential access. Check the OPEN statement and make sure the I/O statement uses the correct unit number and type of access. (For more information on statements, see the HP Fortran for OpenVMS Language Reference Manual.)

(continued on next page)

Diagnostic Messages C–21

Table C–1 (Cont.) Run-Time Error Messages and Explanations

Mnemonic

SHORTDATEARG 175

SHORTTIMEARG

SHORTZONEARG

SIGLOSMAT

SPERECLOC

SQUROONEG

Number Severity Code, Message Text, and Explanation

176

177

F, DATE argument to DATE_AND_TIME is too short (LEN=n), required LEN=8

The number of characters associated with the DATE argument to the DATE_AND_TIME intrinsic was shorter than the required length. You must increase the number of characters passed in for this argument to be at least 8 characters in length. Verify that the TIME and ZONE arguments also meet their minimum lengths.

F, TIME argument to DATE_AND_TIME is too short (LEN=n), required LEN=10

The number of characters associated with the TIME argument to the DATE_AND_TIME intrinsic was shorter than the required length. You must increase the number of characters passed in for this argument to be at least 10 characters in length. Verify that the DATE and ZONE arguments also meet their minimum lengths.

F, ZONE argument to DATE_AND_TIME is too short (LEN=n), required LEN=5

The number of characters associated with the ZONE argument to the DATE_AND_TIME intrinsic was shorter than the required length. You must increase the number of characters passed in for this argument to be at least 5 characters in length. Verify that the TIME and DATE arguments also meet their minimum lengths.

F, significance lost in math library

The magnitude of an argument or the magnitude of the ratio of the arguments to a math library function was so large that all significance in the result was lost. The result returned was the reserved operand, -0.

F, specified record locked

A read operation or direct access write, find, or delete operation was attempted on a record that was locked by another user.

F, square root of negative value

An argument required the evaluation of the square root of a negative value. The result returned was the reserved operand,

–0 for VAX-format floating-point and NaN for IEEE-format floating-point.

(continued on next page)

C–22 Diagnostic Messages

Table C–1 (Cont.) Run-Time Error Messages and Explanations

Mnemonic

STKOVF

STRLENERR

SUBRNG

SUBSTRERR

SYNERRFOR

SYNERRNAM

TOOMANREC

Number Severity Code, Message Text, and Explanation

147

148

149

F, stack overflow

The HP Fortran RTL encountered a stack overflow while executing your program.

F, string length error

During a string operation, an integer value appears in a context where the value of the integer is outside the permissible string length range. Try recompiling with /CHECK=BOUNDS or examine source code.

F, subscript out of range

An array reference was detected outside the declared array bounds.

F, substring error

An array subscript is outside the dimensioned boundaries of an array. Try recompiling with /CHECK=BOUNDS or examine source code.

F, syntax error in format

A syntax error was encountered while the HP Fortran RTL was processing a format stored in an array or character variable.

F, syntax error in NAMELIST input ‘‘text’’

The syntax of input to a namelist-directed READ statement was incorrect. (The part of the record in which the error was detected is shown as ‘‘text’’ in the message text.)

F, too many records in I/O statement

One of the following conditions occurred:

• An attempt was made to read or write more than one record with an ENCODE or DECODE statement.

• An attempt was made to write more records than existed.

TOOMANVAL 18 F, too many values for NAMELIST variable ‘‘varname’’

An attempt was made to assign too many values to a variable during a namelist-directed READ statement. (The name of the variable is shown as ‘‘varname’’ in the message text.)

(continued on next page)

Diagnostic Messages C–23

Table C–1 (Cont.) Run-Time Error Messages and Explanations

Mnemonic

UNDEXP

UNFIO_FMT

UNIALROPE

UNLERR

VFEVALERR

WRIREAFIL

WRONUMARG

Number Severity Code, Message Text, and Explanation

256

F, undefined exponentiation

An exponentiation that is mathematically undefined was attempted, for example, 0.**0. The result returned for floatingpoint operations was –0 for VAX-format floating-point and NaN for IEEE-format floating-point. For integer operations, zero is returned.

F, unformatted I/O to unit open for formatted transfers

Attempted unformatted I/O to a unit where the OPEN statement indicated the file was formatted (FORM specifier). Check that the correct unit (file) was specified.

If the FORM specifier was not specified in the OPEN statement and the file should contain unformatted data, specify

FORM= ’ UNFORMATTED ’ in the OPEN statement. Otherwise, if appropriate, use formatted I/O (such as list-directed or namelist

I/O).

F, unit already open

A DEFINE FILE statement specified a logical unit that was already opened.

F, UNLOCK error

RMS detected an error condition during execution of an UNLOCK statement.

F, variable format expression value error

The value of a variable format expression was not within the range acceptable for its intended use; for example, a field width was less than or equal to zero. A value of one was assumed, except for a P edit descriptor, for which a value of zero was assumed.

F, write to READONLY file

A write operation was attempted to a file that was declared

ACTION= ’ READ ’ or READONLY in the OPEN statement that is currently in effect.

F, wrong number of arguments

An improper number of arguments was used to call a math library procedure.

C–24 Diagnostic Messages

HP Fortran Logical Names

This appendix describes:

• Section D.1, Commands for Assigning and Deassigning Logical Names

• Section D.2, Compile-Time Logical Names

• Section D.3, Run-Time Logical Names

D.1 Commands for Assigning and Deassigning Logical

Names

HP Fortran recognizes certain logical names at compile time and run time.

A logical name specified must not contain brackets, semicolons, or periods.

The system treats any name containing these punctuation marks as a file specification, not as a logical name.

To view the previously set logical names, use the SHOW LOGICAL command

(see HELP SHOW LOGICAL):

$ SHOW LOGICAL PROJ_DIR

%SHOW-S-NOTRAN, no translation for logical name PROJ_DIR

Use a DEFINE command to set (define) a logical name:

$ DEFINE logical-name equivalence-value

For example, to associate the process logical name PROJ_DIR with the directory DISK2:[PROJ], type a DEFINE command:

$ DEFINE PROJ_DIR DISK2:[PROJ]

$ SHOW LOGICAL PROJ_DIR

"PROJ_DIR" = "DISK2:[PROJ]" (LNM$PROCESS_TABLE)

To use logical name tables other than the process table, specify qualifiers to the

DEFINE (or ASSIGN) command. A system manager can define logical names system-wide, perhaps in a system startup procedure.

HP Fortran Logical Names D–1

To remove the association of a logical name and its value, use the DEASSIGN command:

$ DEASSIGN logical-name

D.2 Compile-Time Logical Names

Table D–1 describes the logical names that HP Fortran recognizes at compile time.

Table D–1 HP Fortran Compile-Time Logical Names

Logical Name Description

FORT$LIBRARY Specifies a default text library to be searched for included library modules

(INCLUDE statements that specify library modules) that are not explicitly specified.

FORT$LIBRARY is recognized by both Compaq Fortran 77 and HP Fortran.

For more information, see Section 2.2.4.

FORT$INCLUDE Specifies an additional directory to be searched for included source files

(INCLUDE statements that specify files). For more information, see

Section 2.3.25.

D.3 Run-Time Logical Names

Table D–2 describes the logical names HP Fortran recognizes at run time.

D–2 HP Fortran Logical Names

Table D–2 HP Fortran Run-Time Logical Names

Logical Name Description

FORnnn

FOR$READ

FOR$ACCEPT

FOR$PRINT

FOR$TYPE

FOR$CONVERTnnn

FOR$CONVERT.ext and FOR$CONVERT_ ext

Allows the user to specify the directory and file name at run time for a logical unit (nnn) for which the OPEN statement does not specify a file name (leading zeros are required). If the appropriate logical name is not set and the OPEN statement does not specify a file name for that logical unit, a default file name of FORnnn.DAT is used. For more information, see Section 6.6.1.

Specifies the name of a file to receive input from a READ statement instead of SYS$INPUT. For more information, see Section 6.6.1.

Specifies the name of a file instead of SYS$INPUT to receive input from an ACCEPT statement. For more information, see Section 6.6.1.

Specifies the name of a file instead of SYS$OUTPUT to receive output from a PRINT statement. For more information, see Section 6.6.1.

Specifies the name of a file instead of SYS$OUTPUT to receive output from a TYPE statement. For more information, see Section 6.6.1.

For an unformatted file, specifies the nonnative numeric format of the data at run time for a logical unit (nnn). Otherwise, the nonnative numeric format of the unformatted data must be specified at compile time by using the FORTRAN command /CONVERT qualifier. For more information, see Chapter 9.

For an unformatted file, specifies the nonnative numeric format of the data at run time for a file whose suffix is ext. Otherwise, the nonnative numeric format of the unformatted data must be specified at compile time by using the FORTRAN command /CONVERT qualifier. For more information, see Chapter 9.

HP Fortran Logical Names D–3

Contents of the HP Fortran System Library

FORSYSDEF

Table E–1 lists the library modules contained in the HP Fortran system library

FORSYSDEF.TLB, a text library.

The library modules consist of definitions, in Fortran source code, of related groups of system symbols that can be used in calling OpenVMS system services. FORSYSDEF also contains library modules that define the condition symbols and the entry points for Run-Time Library procedures.

Each new version of the operating system may add new FORSYSDEF library modules to the text library FORSYSDEF. To determine whether a particular library module is installed on your system, use the LIBRARY/LIST command.

For example, the following command sequence searches for the library module named $SMGDEF:

$ LIBRARY/LIST/ONLY=$SMGDEF SYS$LIBRARY:FORSYSDEF.TLB

For More Information:

• On including files and text library modules and INCLUDE statement forms, see Section 2.2.4.

• On including FORSYSDEF library modules, see Section 10.8.1.

• On condition values and symbols, see Section 14.4.3.

• On example programs that use system services, see Appendix F.

Contents of the HP Fortran System Library FORSYSDEF E–1

Table E–1 Contents of System Library FORSYSDEF

Module Name Description

$ACCDEF

$ACEDEF

$ACLDEF

$ACRDEF

$AFRDEF

$AGNDEF

$ALPHADEF

$ARGDEF

$ARMDEF

$ATRDEF

$BRKDEF

$CHFDEF

$CHKPNTDEF

$CHPDEF

$CLIDEF

$CLIMSGDEF

$CLISERVDEF

$CLIVERBDEF

$CLSDEF

$CLUEVTDEF

$CMBDEF

$CQUALDEF

$CRDEF

$CREDEF

$CRFDEF

$CRFMSG

$CVTDEF

Accounting manager request type codes

Access control list entry structure definitions

Access control list interface definitions

Accounting record definitions

Alignment fault reporting

$ASSIGN flags bit definitions

Alpha system hardware model identification

Argument descriptor for object language procedure records

Access rights mask longword definitions

File attribute list description—used to read and write file attributes

Breakthru ($BRKTHRU) system service input definitions

Condition handling argument list offsets

Create checkpointable processes flag definitions

Check protection ($CHKPRO) system service definitions

Command language interface definitions—define the offset values for structures used to communicate information to CLI

Command language interface message definitions

CLI service request code definitions

CLI generic verb codes definitions

Security classification mask block—contains security and integrity level categories for nondiscretionary access controls

Cluster Event Notification Services definitions

$CREMBX flags bit definitions

Common qualifier package definitions

Card reader status bits

Create options table definitions for library facility

CRF$_INSRTREF argument list

Return status codes for cross reference program

RTL floating-point conversion routines

(continued on next page)

E–2 Contents of the HP Fortran System Library FORSYSDEF

Table E–1 (Cont.) Contents of System Library FORSYSDEF

Module Name Description

$CVTMSG

$DCDEF

$DDTMDEF

$DEVDEF

$DIBDEF

$DMTDEF

$DSCDEF

$DSTDEF

$DTIDEF

$DTKDEF

$DTKMSG

$DVIDEF

$DVSDEF

$EEOMDEF

$EGPSDEF

$EGSDEF

$EGSTDEF

$EGSYDEF

$EIDCDEF

$EMHDEF

$ENVDEF

$EOBJRECDEF

$EOMDEF

$EOMWDEF

$EPMDEF

$EPMMDEF

$EPMVDEF

RTL floating-point conversion routines messages

Device adapter, class, and type definitions

DECdtm transaction manager services structure definitions

I/O device characteristics

Device information block definitions

Flag bits for the Dismount ($DISMOU) system service

Descriptor type definitions

Debug symbol table definitions

Distributed Transaction Information flag definitions

Definitions for RTL DECtalk management facility

Return status codes for RTL DECtalk management facility

Device and volume information data identifier definitions

Device scan data identifier definitions

End of module record

Global section descriptor entry - program section definition

Global symbol definition record

Universal symbol definition (used by Linker)

Global symbol definition entry

Random entity ident consistency check

Module header record

Environment definitions in object file

Object file record formats

End of module record in object/image files

End of module record in object/image with word of psect value

Global symbol definition record in object file—entry point definitions

Global section string descriptor entry point definition, version mask symbols

Global section string descriptor entry point definition, vectored symbols

(continued on next page)

Contents of the HP Fortran System Library FORSYSDEF E–3

Table E–1 (Cont.) Contents of System Library FORSYSDEF

Module Name Description

$EPMWDEF

$ERADEF

$ESDFDEF

$ESDFMDEF

$ESDFVDEF

$ESGPSDEF

$ESRFDEF

$ETIRDEF

$EVAX_INSTRDEF

$EVX_OPCODES

$FABDEF

$FALDEF

$FDLDEF

$FIBDEF

$FIDDEF

$FLTDEF

$FMLDEF

$FOR_FP_CLASS

$FORDEF

$FORIOSDEF

$FSCNDEF

$GPSDEF

$GSDEF

$GSYDEF

$HLPDEF

$HWDEF

$IACDEF

Global symbol definition record in object file—entry point definitions with word of psect value

Erase type code definitions

Universal symbol definition (used by linker)

Symbol definition for version mask symbols

Symbol definition for vectored symbols

Global section descriptor entry - program section definition in shareable image

Symbol reference

Text, information, and relocation record

Instruction class definition

Alpha instruction format definitions

RMS File access block definitions

Messages for the FAL (File Access Listener) facility

File Definition Language call interface control flags

File identification block definitions

File ID structure

Flag bits for $SETFLT system service

Formal argument definitions appended to procedure definitions in global symbol definition record in object file

Return values for HP Fortran FP_CLASS intrinsic procedure

Condition symbols for HP Fortran Run-Time Library

HP Fortran IOSTAT error numbers

Descriptor codes for SYS$FILESCAN

Global symbol definition record in object file—psect definitions

Global symbol definition (GSD) record in object file

Global symbol definition record in object file—symbol definitions

Data structures for help processing

Architecture identification

Image activation control flags

(continued on next page)

E–4 Contents of the HP Fortran System Library FORSYSDEF

Table E–1 (Cont.) Contents of System Library FORSYSDEF

Module Name Description

$IDCDEF

$IEEEDEF

$IMPDEF

$INITDEF

$IODEF

$JBCMSGDEF

$JPIDEF

$KGBDEF

$LADEF

$LATDEF

$LATMSGDEF

$LBRCTLTBL

$LBRDEF

$LCKDEF

$LEPMDEF

$LHIDEF

$LIBCLIDEF

$LIBDCFDEF

$LIBDEF

$LIBDTDEF

$LIBFISDEF

$LIBICB

$LIBVMDEF

$LICENSEDEF

$LKIDEF

$LMFDEF

$LNKDEF

$LNMDEF

Object file IDENT consistency check structures

IEEE floating-point control register definitions

$PERSONA_xxx service definitions

Values for INIT$_DENSITY item code (media format)

I/O function codes

Job controller message definition

Job/process information request type codes

Key grant block definitions—formats of records in rights database file

Laboratory peripheral accelerator device types

LAT facility definitions

Error messages for LAT facility

Librarian control table definitions

Library type definitions

Lock manager definitions

Global symbol definition record in object file—module local entry point definitions

Library header information array offsets

Definitions for LIB$ CLI callback procedures

Definitions for LIB$DECODE_FAULT procedure

Condition symbols for the general utility library

Interface definitions for LIB$DT (date/time) package

LIB$FIND_IMAGE_SYMBOL flags

LIB$GET_INVO_CONTEXT definitions

Interface definitions for LIB$VM (virtual memory) package

License Management Facility definitions

Get lock information data identifier definitions

License Management Facility definitions

Linker option record definition in object file

Logical name flag definitions

(continued on next page)

Contents of the HP Fortran System Library FORSYSDEF E–5

$LSDFDEF

$LSRFDEF

$LSYDEF

$MAILDEF

$MHDDEF

$MHDEF

$MMEDEF

$MMEMSGDEF

$MMIDEF

$MNTDEF

$MSGDEF

$MSGHLPDEF

$MT2DEF

$MTADEF

$MTDEF

$MTHDEF

$NAMDEF

$NCSDEF

$NETDEF

$NSADEF

$NSARECDEF

$OBJRECDEF

$OPCDEF

Table E–1 (Cont.) Contents of System Library FORSYSDEF

Module Name Description

$LPDEF

$LPRODEF

$OPCMSG

$OPRDEF

Line printer characteristic codes

Global symbol definition record in object file—module local procedure definition in object file

Module local symbol definition in object file

Module local symbol reference in object file

Module local symbol definition

Callable mail definitions

Main header record definitions

Module header record definition in object file

Media management extensions definitions

Media management extensions messages

Media management interface definitions

Flag bits and function codes for the MOUNT system service

Symbolic names to identify mailbox message senders

Message help values

Extended magnetic tape characteristic bit definition

Magnetic tape accessibility routine codes

Magnetic tape characteristic codes

Condition symbols from the mathematical procedures library

RMS name block field definitions

Interface definitions for National Character set package

DECnet-VAX identification definitions

Security auditing packet header and record type definitions

Security auditing record definitions

Object language record definition

Operator communication manager request type codes–return status codes

OPCOM message definitions

Operator communications message types and values

(continued on next page)

E–6 Contents of the HP Fortran System Library FORSYSDEF

Table E–1 (Cont.) Contents of System Library FORSYSDEF

Module Name Description

$OSSDEF

$OTSDEF

$PAGEDEF

$PQLDEF

$PRCDEF

$PRDEF

$PRODEF

$PROMDEF

$PROVDEF

$PROWDEF

$PRTDEF

$PRVDEF

$PSCANDEF

$PSIGDEF

$PSLDEF

$PSMMSGDEF

$PTDDEF

$QUIDEF

$RABDEF

$RMEDEF

$RMSDEF

$RNHBLKDEF

$SBKDEF

$SCRDEF

$SDFDEF

$SDFMDEF

Object security service definitions

Language-independent support procedure (OTS$) return status codes

Page size and limit definitions

Quota types for process creation quota list

Create process ($CREPRC) system service status flags and item codes

Processor register definitions

Global symbol definition record in object file—procedure definition

Global section string descriptor entry: procedure definition, version mask symbols

Global section string descriptor entry: procedure definition, vectored symbols

Global symbol definition record in object file—procedure definition with word of psect value

Protection field definitions

Privilege bit definitions

Process scan item code definitions

Signature block offset definitions for calling standard

Processor status longword (PSL) mask and symbolic names for access modes

Print symbiont message definitions

Processor status word mask and field definitions

Get queue information service definitions

RMS record access block definitions

RMS escape definitions

RMS return status codes

Get Queue Information Service ($GETQUI) definitions, item codes

Open file statistics block

Screen package interface definitions

Symbol record in object file

Symbol definitions

(continued on next page)

Contents of the HP Fortran System Library FORSYSDEF E–7

Table E–1 (Cont.) Contents of System Library FORSYSDEF

Module Name Description

$SDFVDEF

$SDFWDEF

$SECDEF

$SGPSDEF

$SHRDEF

$SJCDEF

$SMBMSGDEF

$SMGDEF

$SMGMSG

$SMGTRMPTR

$SMRDEF

$SNAPEVTDEF

$SORDEF

$SRFDEF

$SRMDEF

$SSDEF

$STENVDEF

$STRDEF

$STSDEF

$SYIDEF

$SYSSRVNAM

$TIRDEF

$TPADEF

$TPUDEF

$TRMDEF

$TT2DEF

$TT3DEF

Symbol definitions for vectored symbols

Symbol record in object file with word of psect value

Attribute flags for private/global section creation and mapping

Global symbol definition record in object file—P-section definition in shareable image

Definitions for shared messages

Send to job controller service definitions

Symbiont manager message definitions

Definitions for RTL screen management

Messages for the Screen Management facility

Terminal capability pointers for RTL SMG$ facility

Define symbiont manager request codes

System snapshot/reboot status definitions

Messages for the Sort/Merge facility

Global symbol definition record in object file—symbol reference definitions

SRM hardware symbol definitions

System service failure and status codes

Assign symbiont manager print job/record option codes

String manipulation procedures (STR$) return status codes

Status codes and error codes

Get system information data identifier definitions

System service entry point descriptions

Text information and relocation record in object file

TPARSE control block

TPU callable interface definitions

Define symbols to the item list QIO format

Terminal special symbols

(continued on next page)

E–8 Contents of the HP Fortran System Library FORSYSDEF

Table E–1 (Cont.) Contents of System Library FORSYSDEF

Module Name Description

$TTCDEF

$TTDEF

$UAIDEF

$UICDEF

$UIDDEF

$USGDEF

$USRIDEF

$VAXDEF

$XABALLDEF

$XABCXFDEF

$XABCXRDEF

$XABDATDEF

$XABDEF

$XABFHCDEF

$XABITMDEF

$XABJNLDEF

$XABKEYDEF

$XABPRODEF

$XABRDTDEF

$XABRUDEF

$XABSUMDEF

$XABTRMDEF

$XADEF

$XKDEVDEF

$XKSTSDEF

$XMDEF

$XWDEF

CMA$DEF

CVT$ROUTINES

Character code format

Terminal device characteristic codes

User Authorization Information data identifier definitions

Format of user identification code (UIC)

Universal identifier definitions

Disk usage accounting file produced by ANALYZE/DISK_STRUCTURE

User image bit definitions

VAX model definitions

Allocation XAB definitions

RMS context XAB associated with FAB

RMS context XAB associated with RAB

Date/time XAB definitions

Definitions for all XABs

File header characteristics XAB definitions

Item list XAB

Journal XAB definitions

Key definitions XAB field definitions

Protection XAB field definitions

Revision date/time XAB definitions

Recovery unit XAB

Summary XAB field definitions

Terminal control XAB field definitions

DR11-W definitions for device specific characteristics

3271 device status block

Definitions for 3271 line status block (returned by IO$_RDSTATS)

DMC-11 device characteristic codes

System definition for software DDCMP

DECthreads definitions

Floating-point conversion routines

(continued on next page)

Contents of the HP Fortran System Library FORSYSDEF E–9

Table E–1 (Cont.) Contents of System Library FORSYSDEF

Module Name Description

DTK$ROUTINES

LIB$ROUTINES

MTH$ROUTINES

NCS$ROUTINES

OTS$ROUTINES

PPL$DEF

PPL$MSG

PPL$ROUTINES

SMG$ROUTINES

SOR$ROUTINES

STR$ROUTINES

Routine definitions for DECtalk facility

Routine definitions for general purpose run-time library procedures

Routine definitions for mathematics run-time library procedures

Routine definitions for National Character set procedure

Routine definitions for language-independent support procedures

Definitions for Parallel Processing library facility

Message definitions for Parallel Processing library facility

Routine definitions for Parallel Processing library facility

Routine definitions for Screen Management procedures

Routine definitions for Sort/Merge procedures

Routine definitions for string manipulation procedures

E–10 Contents of the HP Fortran System Library FORSYSDEF

Using System Services: Examples

This appendix contains examples that involve accessing OpenVMS system services from HP Fortran programs. The individual examples address the following operations:

• Section F.1, Calling RMS Procedures

• Section F.2, Using an AST Routine

• Section F.3, Accessing Devices Using Synchronous I/O

• Section F.4, Communicating with Other Processes

• Section F.5, Sharing Data

• Section F.6, Displaying Data at Terminals

• Section F.7, Creating, Accessing, and Ordering Files

• Section F.8, Measuring and Improving Performance

• Section F.9, Accessing Help Libraries

• Section F.10, Creating and Managing Other Processes

Each example includes the free-form source program (with comments), a sample use of the program, and explanatory notes.

See the HP Fortran Web site at more examples.

http://www.hp.com/software/fortran for

F.1 Calling RMS Procedures

When you explicitly call an RMS system service, the order of the arguments in the call must correspond with the order shown in the OpenVMS Record

Management Services Reference Manual. You must use commas to reserve a place in the call for every argument. If you omit an argument, the procedure uses a default value of zero.

Using System Services: Examples F–1

When calling an RMS routine from HP Fortran, the procedure name format is SYS$procedure_name. The following example shows a call to the RMS procedure SYS$SETDDIR. This RMS procedure sets the default directory for a process.

Source Program:

File: SETDDIR.F90

This program calls the RMS procedure $SETDDIR to change

the default directory for the process.

IMPLICIT INTEGER (A - Z)

CHARACTER(LEN=17) DIR /’[EX.PROG.FOR]’/

STAT = SYS$SETDDIR (DIR,,)

IF (.NOT. STAT) TYPE *, ’ERROR’

END PROGRAM

Sample Use:

$ DIRECTORY

Directory WORK$:[EX.PROG.FOR.CALL]

BASSUM.BAS;1

GETMSG.EXE;1

BASSUM.OBJ;1

GETMSG.F90;4

SETDDIR.F90;3 SETDDIR.LIS;1

Total of 10 files.

COBSUM.COM;1

GETMSG.LIS;2

The DIRECTORY command executed before the SETDDIR program is run shows that the following directory is the default:

DOCOMMAND.F90;2

GETMSG.OBJ;1

$ FORTRAN SETDDIR

$ LINK SETDDIR

$ RUN SETDDIR

$ DIRECTORY

Directory WORK$:[EX.PROG.FOR]

CALL.DIR;1

HAND.DIR;1

RMS.DIR;1

COMU.DIR;1

INTR.DIR;1

SHAR.DIR;1

Total of 12 files.

DEVC.DIR;1

LNKR.DIR;1

SYNC.DIR;1

FIL.DIR;1

MNAG.DIR;1

TERM.DIR;1

The default directory name is initialized into a CHARACTER variable.

The call to $SETDDIR contains one argument, the directory name, which is passed by descriptor, the default argument passing mechanism for

CHARACTERs. The omitted arguments are optional, but commas are necessary to reserve places in the argument list.

WORK$:[EX.V4PROG.FOR.CALL]

This directory contains the file SETDDIR.F90.

F–2 Using System Services: Examples

$ Another DIRECTORY command after the SETDDIR program is run shows that the default directory has changed. The following directory is the new default directory:

WORK$:[EX.PROG.FOR]

For More Information:

On calling RMS system services, see Chapter 11.

F.2 Using an AST Routine

The following example demonstrates how to request and declare an AST procedure. It consists of the following:

• The main program CTRLC defines a common block AST_COM that contains the logical variable CTRLC_FLAG and integer channel number, calls the ENABLE_AST routine to set up Ctrl/C trapping, and contains a

DO loop that allows Ctrl/C interruption.

• A subroutine named ENABLE_AST that enables Ctrl/C trapping using the SYS$QIOW system service. It is called by the main program and the

AST_ROUTINE subroutine.

• A subroutine named AST_ROUTINE that gets called when a Ctrl/C is pressed. It resets the logical variable CTRLC_FLAG and calls the

ENABLE_AST subroutine to allow repetitive Ctrl/C use.

For More Information:

On AST routines, see the HP OpenVMS System Services Reference Manual.

Source Programs:

Sample program to show enabling of an AST in Fortran

The program uses a Ctrl/C AST to interrupt a work loop in the

main program.

PROGRAM CTRLC

IMPLICIT NONE

LOGICAL CTRLC_FLAG

INTEGER (KIND=2) CHANNEL

! Set to TRUE when Ctrl/C is pressed

! Channel for terminal

COMMON /AST_COM/ CTRLC_FLAG,CHANNEL

VOLATILE CTRLC_FLAG ! Required because variable !

! can change at any time

INTEGER ITERATIONS,I

Do first-time initialization

Using System Services: Examples F–3

CHANNEL = 0

CTRLC_FLAG = .FALSE.

CALL ENABLE_AST

Read iteration count

100 WRITE (*,’($,A)’) ’ Enter iteration count (0 to exit): ’

READ (*,*) ITERATIONS

DO I=1,ITERATIONS

IF (CTRLC_FLAG) GOTO 200 ! Was Ctrl/C pressed?

WRITE (*,*) ’Count is ’,I

CALL LIB$WAIT (2.0)

END DO

IF (ITERATIONS .EQ. 0) GOTO 999

GOTO 100 ! Loop back

! Pause 2 seconds

200 WRITE (*,*) ’Ctrl/C pressed’

CTRLC_FLAG = .FALSE.

GOTO 100

999 END PROGRAM CTRLC

Subroutine ENABLE_AST

SUBROUTINE ENABLE_AST

IMPLICIT NONE

INCLUDE ’($SYSSRVNAM)’

INCLUDE ’($IODEF)’

LOGICAL CTRLC_FLAG

VOLATILE CTRLC_FLAG

INTEGER (KIND=2) CHANNEL

COMMON /AST_COM/ CTRLC_FLAG,CHANNEL

! System services

! $QIO function codes

EXTERNAL AST_ROUTINE

INTEGER ASSIGN_STATUS, QIO_STATUS, IOSB(2)

Assign channel if not already assigned

IF (CHANNEL .EQ. 0) THEN

ASSIGN_STATUS = SYS$ASSIGN (’TT:’, CHANNEL,,,)

IF (.NOT. ASSIGN_STATUS) CALL LIB$SIGNAL(%VAL(ASSIGN_STATUS))

END IF

Enable AST so that AST_ROUTINE is called when Ctrl/C is pressed.

QIO_STATUS = SYS$QIOW (, &

%VAL(CHANNEL), &

%VAL(IO$_SETMODE .OR. IO$M_CTRLCAST), &

IOSB,,, &

AST_ROUTINE,,,,,)

IF (.NOT. QIO_STATUS) CALL LIB$SIGNAL(%VAL(QIO_STATUS))

F–4 Using System Services: Examples

RETURN

END SUBROUTINE ENABLE_AST

Subroutine AST_ROUTINE

SUBROUTINE AST_ROUTINE

IMPLICIT NONE

LOGICAL CTRLC_FLAG

VOLATILE CTRLC_FLAG

INTEGER (KIND=2) CHANNEL

COMMON /AST_COM/ CTRLC_FLAG,CHANNEL

Indicate that a CTRL/C has been pressed

CTRLC_FLAG = .TRUE.

Reenable the AST.

This must be done by calling ENABLE_AST rather than

doing it here as we would need a recursive reference to AST_ROUTINE,

which is disallowed unless /RECURSIVE is used.

CALL ENABLE_AST %

RETURN

END SUBROUTINE AST_ROUTINE

Sample Use:

$ RUN CTRLC

Enter iteration count (0 to exit):

Count is

Ctrl/C

Cancel

Ctrl/C pressed

Enter iteration count (0 to exit):

The CTRLC_FLAG logical variable is declared volatile in the routines that reference it because its value could change at any point during program execution (other than an assignment statement or subroutine argument).

" By providing two subroutines, you allow the Ctrl/C AST routine to be executed repeatedly, rather than just once. The ENABLE_AST subroutine is called by the main program and the AST_ROUTINE subroutine. It enables Ctrl/C trapping using the SYS$QIOW system service and sets the

CTRLC_FLAGS logical variable. For a subroutine to call itself, it must be recursive.

Using System Services: Examples F–5

# The call to the SYS$QIOW system service enables Ctrl/C AST use by specifying that the subroutine AST_ROUTINE be called when Ctrl/C is pressed.

$ When the AST is delivered, the AST_ROUTINE receives control, resets the

CTRLC_FLAG logical variable, and returns control back to where Ctrl/C was pressed (main program), which eventually displays ‘‘Ctrl/C pressed’’.

The arguments to AST_ROUTINE are platform dependent.

% The example shows the program executing within the DO loop in the main program (with a two second delay between DO loop executions). When the user types Ctrl/C, control is transferred briefly to the AST_ROUTINE subroutine and it then returns back to the main program. Within the DO loop, the main program tests the value of logical variable CTRLC_FLAG and, if set to .TRUE., transfers control to label 200 which displays ‘‘Ctrl/C pressed’’.

For More Information:

On the VOLATILE statement, see the HP Fortran for OpenVMS Language

Reference Manual.

F.3 Accessing Devices Using Synchronous I/O

The following example performs output to a terminal via the SYS$QIOW system service.

Source Program:

File: QIOW.F90

This program demonstrates the use of the $QIOW system service to

perform synchronous I/O to a terminal.

IMPLICIT

INCLUDE

INTEGER (KIND=4) (A - Z)

’($SYSSRVNAM)’

INCLUDE ’($IODEF)’

CHARACTER(LEN=24) TEXT_STRING /’This is from a SYS$QIOW.’/ !

CHARACTER(LEN=11) TERMINAL /’SYS$COMMAND’/

INTEGER KIND=2) TERM_CHAN

STRUCTURE /TT_WRITE_IOSB/

INTEGER (KIND=2) STATUS

INTEGER (KIND=2) BYTES_WRITTEN

INTEGER (KIND=4) %FILL

END STRUCTURE

RECORD /TT_WRITE_IOSB/ IOSB

Assign the channel number

STAT = SYS$ASSIGN (TERMINAL, TERM_CHAN,,)

IF (.NOT. STAT) CALL LIB$STOP (%VAL(STAT)) "

F–6 Using System Services: Examples

Initialize STATUS to zero (0)

STATUS = 0

Output the message twice

DO I=1,2

STAT = SYS$QIOW (%VAL(1),%VAL(TERM_CHAN), &

%VAL(IO$_WRITEVBLK),IOSB,,, &

%REF(TEXT_STRING), &

%VAL(LEN(TEXT_STRING)),, &

%VAL(32),,)

IF (.NOT. STAT) CALL LIB$STOP (%VAL(STATUS))

IF (.NOT. IOSB.STATUS) CALL LIB$STOP (%VAL(IOSB.STATUS))

ENDDO

END PROGRAM

Sample Use:

$ FORTRAN QIOW

$ LINK QIOW

$ RUN QIOW

This is from a SYS$QIOW.

If SYS$QIO and a SYS$WAITFR are used instead of SYS$QIOW, you must use a VOLATILE declaration for any program variables and arrays that can be changed while the operation is pending.

" TERM_CHAN receives the channel number from the SYS$ASSIGN system service.

The process permanent logical name SYS$COMMAND is assigned to your terminal when you log in. The SYS$ASSIGN system service translates the logical name to the actual device name.

# SYS$QIO and SYS$QIOW accept the CHAN argument by immediate value, unlike SYS$ASSIGN, which requires that it be passed by reference. Note the use of %VAL in the call to SYS$QIOW but not in the previous call to

SYS$ASSIGN.

The function IO$_WRITEVBLK requires values for parameters P1, P2, and

P4.

• P1 is the starting address of the buffer containing the message. So,

TEXT_STRING is passed by reference.

• P2 is the number of bytes to be written to the terminal. A 24 is passed, since it is the length of the message string.

• P4 is the carriage control specifier; a 32 indicates single space carriage control.

Using System Services: Examples F–7

A SYS$QIOW is issued, ensuring that the output operation will be completed before the program terminates.

F.4 Communicating with Other Processes

The following example shows how to create a global pagefile section and how two processes can use it to access the same data. One process executes the program PAGEFIL1, which must first be installed. When run, PAGEFIL1 creates and writes to a global pagefile section. PAGEFIL1 then waits for a second process to update the section. The second process executes PAGEFIL2, which maps and updates the pagefile section.

Because PAGEFIL2 maps to the temporary global pagefile section created in

PAGEFIL1, PAGEFIL1 must be run first. The two processes coordinate their activity through common event flags.

Source Program: PAGEFIL1.F90

File: PAGEFIL1.F90

This program creates and maps a global page frame section.

Data in the section is accessed through an array.

IMPLICIT INTEGER (KIND=4)

INCLUDE

(A-Z)

’($SECDEF)’

INCLUDE

DIMENSION

’($SYSSRVNAM)’

’($SYIDEF)’

MY_ADR(2),OUT_ADR(2)

COMMON /MYCOM/

CHARACTER(LEN=4)

VOLATILE /MYCOM/

IARRAY(50)

NAME/’GSEC’/

Associate with common cluster MYCLUS

STATUS = SYS$ASCEFC (%VAL(64),’MYCLUS’,,) #

To calculate the ending address of the page boundary, call

LIB$GETSYIW to get the processor-specific page size, PAGE_MAX

STATUS = LIB$GETSYI(SYI$_PAGE_SIZE,PAGE_MAX,,,,)

IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))

MY_ADR(1) = %LOC(IARRAY(1))

MY_ADR(2) = MY_ADR(1) + PAGE_MAX -1

Flags for call to SYS$CRMPSC

SEC_FLAGS = SEC$M_PAGFIL.OR.SEC$M_GBL.OR.SEC$M_WRT.OR.SEC$M_DZRO

Create and map the temporary global section

F–8 Using System Services: Examples

STATUS = SYS$CRMPSC(MY_ADR,OUT_ADR,,%VAL(SEC_FLAGS), & $

NAME,,,,%VAL(1),,,)

IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))

Manipulate the data in the global section

DO 10 I = 1,50

IARRAY(I) = I

END DO

STATUS = SYS$SETEF(%VAL(72))

IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))

TYPE *,’Waiting for PAGEFIL2 to update section’

STATUS = SYS$WAITFR(%VAL(73))

Print the array modified by PAGEFIL2 in the global section

TYPE *, ’Modified data in the global section:’

WRITE (6,100) (IARRAY(I), I=1,50)

100 FORMAT(10I5)

END PROGRAM

Source Program: PAGEFIL2.F90

File: PAGEFIL2.F90

This program maps and modifies a global section after PAGEFIL1

creates the section.

Programs PAGEFIL1 and PAGEFIL2 synchronize

the processing of the global section through the use of common

event flags.

IMPLICIT INTEGER (KIND=4)

INCLUDE

(A - Z)

’($SECDEF)’

INCLUDE

’($SYSSRVNAM)’

’($SYIDEF)’

DIMENSION

COMMON /MYCOM/

VOLATILE /MYCOM/

MY_ADR(2)

IARRAY(50)

Call LIB$GETSYIW to get page size, PAGE_MAX

STATUS = LIB$GETSYI(SYI$_PAGE_SIZE,PAGE_MAX,,,,)

IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))

MY_ADR(1) = %LOC(IARRAY(1))

MY_ADR(2) = MY_ADR(1) + PAGE_MAX -1

Associate with common cluster MYCLUS and wait for

event flag to be set

# STATUS = SYS$ASCEFC(%VAL(64),’MYCLUS’,,)

IF (.NOT. STATUS) CALL LIB$STOP (%VAL(STATUS))

STATUS = SYS$WAITFR (%VAL(72))

IF (.NOT. STATUS) CALL LIB$STOP (%VAL(STATUS))

Set flag to allow section to be written

Using System Services: Examples F–9

FLAGS = SEC$M_WRT

Map the global section

STATUS = SYS$MGBLSC(MY_ADR,,,%VAL(FLAGS),’GSEC’,,)

IF (.NOT. STATUS) CALL LIB$STOP (%VAL(STATUS))

Print out the data in the global section and

multiply each value by two

TYPE *, ’Original data in the global section:’

WRITE (6,100) (IARRAY(I), I=1,50)

100 FORMAT (10I5)

DO I=1,50

IARRAY(I) = IARRAY(I) * 2

END DO

’

(

Set an event flag to allow PAGEFIL1 to continue execution

STATUS = SYS$SETEF(%VAL(73))

IF (.NOT. STATUS) CALL LIB$STOP (%VAL(STATUS))

END PROGRAM

The options file PAGEFIL.OPT contains the following line of source text:

PSECT_ATTR=MYCOM,PAGE,SHR,WRT,SOLITARY

COLLECT=SHARED_CLUS,MYCOM

)

Sample Use:

$ FORTRAN /ALIGN=NATURAL PAGEFIL1

$ FORTRAN/ALIGN=NATURAL PAGEFIL2

$ LINK PAGEFIL1,PAGEFIL/OPTIONS

$ LINK PAGEFIL2,PAGEFIL/OPTIONS

$ RUN PAGEFIL1 !***Process 1***

Waiting for PAGEFIL2 to update section

Modified data in the global section:

2 4 6 8 10 12 14 16 18 20

22 24 26 28 30 32 34 36 38 40

42 44 46 48 50 52 54 56 58 60

62 64 66 68 70 72 74 76 78 80

82 84 86 88 90 92 94 96 98 100

$ RUN PAGEFIL2 !***Process 2***

Original data in the global section:

1 2 3 4 5 6 7 8 9 10

11 12 13 14 15 16 17 18 19 20

21 22 23 24 25 26 27 28 29 30

31 32 33 34 35 36 37 38 39 40

41 42 43 44 45 46 47 48 49 50

PAGEFIL1 and PAGEFIL2 are linked with the same options file, which

F–10 Using System Services: Examples

specifies that the COMMON block program section is shareable, can be written to, and starts on a page boundary. The first argument to the

SYS$CRMPSC (and SYS$MGBLSC) system service is a two-element array

MYADR which specifies the starting and ending address.

If any variables or arrays are used or modified, you should declare them as volatile in the other routines that reference them.

Associate to a common event flag cluster to coordinate activity. The processes must be in the same UIC group.

$ The $CRMPSC system service creates and maps a global pagefile section.

The starting and ending process virtual addresses of the section are placed in MY_ADR. The SEC$M_PAGFIL flag requests a temporary pagefile section. The flag SEC$M_GBL requests a global section. The flag SEC$M_

WRT indicates that the pages should be writable as well as readable. The

SEC$M_DZRO flag requests pages filled with zeros.

Data is written to the pagefile section by PAGEFIL1.

PAGEFIL2 maps the existing section as writable by specifying the SEC$M_

WRT flag.

’

(

)

PAGEFIL2 reads from the pagefile section.

PAGEFIL2 modifies the data in the pagefile section.

The COLLECT option instructs the linker to create a cluster named

SHARED_CLUS and to put the PSECT MYCOM into that cluster. This prevents the problem of inadvertently mapping another PSECT in a page containing all or part of MYCOM. Clusters are always positioned on page boundaries.

+> After PAGEFIL1 is run, creates the global section, writes out the data, and then displays:

Waiting for PAGEFIL2 to update section

A separate terminal is used to run PAGEFIL2, which displays the original data written by PAGEFIL1 and then modifies that data and exits. Once modified, PAGEFIL1 displays the data modified by PAGEFIL2 and exits.

For More Information:

On the VOLATILE statement, see the HP Fortran for OpenVMS Language

Reference Manual.

Using System Services: Examples F–11

F.5 Sharing Data

The program called SHAREDFIL is used to update records in a relative file.

The SHARE qualifier is specified on the OPEN statement to invoke the RMS file sharing facility. In this example, the same program is used to access the file from two processes:

Source Program:

File: SHAREDFIL.F90

This program can be run from two or more processes to demonstrate the

use of an RMS shared file to share data.

The program requires the

relative file named REL.DAT.

IMPLICIT INTEGER (KIND=4) (A - Z)

CHARACTER(LEN=20) RECORD

INCLUDE ’($FORIOSDEF)’ !

OPEN (UNIT=1, FILE=’REL’, STATUS=’OLD’, SHARED, & "

ORGANIZATION=’RELATIVE’, ACCESS=’DIRECT’, FORM=’FORMATTED’) #

Request record to be examined

100 TYPE 10

10 FORMAT (’$Record number (Ctrl/Z to quit): ’)

READ (*,*, END=999) REC_NUM

Get record from file

READ (1,20, REC=REC_NUM, IOSTAT=STATUS), REC_LEN, RECORD

20 FORMAT (Q, A)

Check I/O status

IF (STATUS .EQ. 0) THEN

TYPE *, RECORD(1:REC_LEN)

ELSE IF (STATUS .EQ. FOR$IOS_ATTACCNON) THEN

TYPE *, ’Nonexistent record.’

GOTO 100

ELSE IF (STATUS .EQ. FOR$IOS_RECNUMOUT) THEN

TYPE *, ’Record number out of range.’

GOTO 100

ELSE IF (STATUS .EQ. FOR$IOS_SPERECLOC) THEN

TYPE *, ’Record locked by someone else.’

GOTO 100

ELSE

CALL ERRSNS (, RMS_STS, RMS_STV,,)

CALL LIB$SIGNAL (%VAL(RMS_STS), %VAL(RMS_STV))

ENDIF

Request updated record

F–12 Using System Services: Examples

TYPE 30

30 FORMAT (’$New Value or CR: ’)

READ (*,20) REC_LEN, RECORD

IF (REC_LEN .NE. 0) THEN

WRITE (1,40, REC=REC_NUM, IOSTAT=STATUS) RECORD(1:REC_LEN)

40 FORMAT (A)

IF (STATUS .NE. 0) THEN

CALL ERRSNS (, RMS_STS, RMS_STV,,)

CALL LIB$SIGNAL(%VAL(RMS_STS),%VAL(RMS_STV))

ENDIF

Loop

GOTO 100

999 END PROGRAM

Sample Use:

$ FORTRAN SHAREDFIL

$ LINK SHAREDFIL

$ RUN SHAREDFIL

Record number (Ctrl/Z to quit): 2

MSPIGGY

New Value or CR: FOZZIE

Record number (Ctrl/Z to quit): 1

KERMIT

New Value or CR:

Record number (Ctrl/Z to quit): Ctrl/Z

$ RUN SHAREDFIL

Record number (Ctrl/Z to quit): 2

Record locked by someone else.

Record number (Ctrl/Z to quit): 2

Record locked by someone else.

Record number (Ctrl/Z to quit): 2

FOZZIE

New Value or CR: MSPIGGY

Record number (Ctrl/Z to quit): Ctrl/Z

The library module FORIOSDEF must be included to define the symbolic status codes returned by HP Fortran I/O statements.

This program requires a relative file named REL.DAT.

The SHARED qualifier is used on the OPEN statement to indicate that the file can be shared. Because manual locking was not specified, RMS automatically controls access to the file. Only read and update operations are allowed in this example. No new records can be written to the file.

$ The second process is not allowed to access record #2 while the first process is accessing it.

Using System Services: Examples F–13

% Once the first process has finished with record #2, the second process can update it.

F.6 Displaying Data at Terminals

The following example calls SMG routines to format screen output.

No sample run is included for this example because the program requires a video terminal in order to execute properly.

Source Program:

File: SMGOUTPUT.F90

This program calls Run-Time Library Screen Management routines

to format screen output.

IMPLICIT INTEGER (KIND=4) (A-Z)

INCLUDE ’($SMGDEF)’

Establish terminal screen as pasteboard

STATUS = SMG$CREATE_PASTEBOARD (NEW_PID,,,)

IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))

Establish a virtual display region

STATUS = SMG$CREATE_VIRTUAL_DISPLAY (15,30,DISPLAY_ID,,,)

IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))

Paste the virtual display to the screen, starting at

row 2, column 15

STATUS = SMG$PASTE_VIRTUAL_DISPLAY(DISPLAY_ID,NEW_PID,2,15)

IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))

Put a border around the display area

STATUS = SMG$LABEL_BORDER(DISPLAY_ID,’This is the Border’,,,,,) %

IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))

Write text lines to the screen

STATUS = SMG$PUT_LINE (DISPLAY_ID,’ ’,,,,,)

IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))

STATUS = SMG$PUT_LINE (DISPLAY_ID,’Howdy, pardner’,2,,,,)

IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))

STATUS = SMG$PUT_LINE (DISPLAY_ID,’Double spaced lines...’,2,,,,)

IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))

F–14 Using System Services: Examples

STATUS = SMG$PUT_LINE (DISPLAY_ID,’This line is blinking’,2, &

SMG$M_BLINK,0,,)

’

IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))

STATUS = SMG$PUT_LINE (DISPLAY_ID,’This line is reverse video’,2, &

’

SMG$M_REVERSE,0,,)

IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))

DO I = 1, 5

STATUS = SMG$PUT_LINE (DISPLAY_ID,’Single spaced lines...’,,,,,)

IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))

ENDDO

(

END PROGRAM

The INCLUDE statement incorporates the $SMGDEF library module from

FORSYSDEF.TLB into the source program. This library module contains symbol definitions used by the screen management routines.

# The created virtual display is 15 lines long and 30 columns wide. The virtual display initially contains blanks.

The call to SMG$CREATE_PASTEBOARD creates a pasteboard upon which output will be written. The pasteboard ID is returned in the variable

NEW_PID.

No value is specified for the output device parameter, so the output device defaults to SYS$OUTPUT. Also, no values are specified for the PB_ROWS or PB_COLS parameters, so the pasteboard is created with the default number of rows and columns. The defaults are the number of rows and the number of columns on the physical screen of the terminal to which

SYS$OUTPUT is assigned.

The virtual display is pasted to the pasteboard, with its upper left corner positioned at row 2, column 15 of the pasteboard. Pasting the virtual display to the pasteboard causes all data written to the virtual display to appear on the pasteboard’s output device, which is SYS$OUTPUT—the terminal screen.

At this point, nothing appears on the screen because the virtual display contains only blanks. However, because the virtual display is pasted to the pasteboard, the program statements described below cause text to be written to the screen.

A labeled border is written to the virtual display.

Using a call to the RTL routine SMG$PUT_LINE, the text line (‘‘Howdy, pardner’’ is written to the virtual display.

To specify double spacing, a call to SMG$PUT_LINE displays ‘‘Double spaced lines...’’ by specifying the line-adv (third) argument to SMG$PUT_

LINE as 2.

Using System Services: Examples F–15

’ Two subsequent calls to SMG$PUT_LINE specify the SMG$M_BLINK and SMG$M_REVERSE parameters (rendition-set argument) display the double-spaced lines ‘‘This line is blinking’’ as blinking and ‘‘This line is reverse video’’ in reverse video. The parameter mask constants like SMG$M_BLINK are defined in the $SMGDEF library module in

FORSYSDEF.TLB.

( The program displays single-spaced text by omitting a value for the lineadv argument (third argument) to SMG$PUT_LINE. The DO loop displays the line ‘‘Single spaced lines...’’ five times.

F.7 Creating, Accessing, and Ordering Files

In the following example, each record in a relative file is assigned to a specific cell in that file. On sequential write operations, the records are written to consecutive empty cells. Random write operations place the records into cell numbers as provided by the REC=n parameter.

Source Program:

File: RELATIVE.F90

This program demonstrates how to access a relative file

randomly. It also performs some I/O status checks.

IMPLICIT INTEGER (KIND=4) (A - Z)

STRUCTURE /EMPLOYEE_STRUC/

CHARACTER(LEN=5)

CHARACTER(LEN=6)

ID_NUM

NAME

CHARACTER(LEN=3)

CHARACTER(LEN=2)

CHARACTER(LEN=4)

END STRUCTURE

DEPT

SKILL

SALARY

RECORD /EMPLOYEE_STRUC/ EMPLOYEE_REC

INTEGER (KIND=4) REC_LEN

INCLUDE ’($FORIOSDEF)’ !

OPEN (UNIT=1, FILE=’REL’, STATUS=’OLD’, ORGANIZATION=’RELATIVE’, & "

ACCESS=’DIRECT’, FORM=’UNFORMATTED’,RECORDTYPE=’VARIABLE’)

Get records by record number until e-o-f

Prompt for record number

100 TYPE 10

10 FORMAT (’$Record number: ’)

READ (*,*, END=999) REC_NUM

Read record by record number

READ (1,REC=REC_NUM,IOSTAT=STATUS) EMPLOYEE_REC

Check I/O status

F–16 Using System Services: Examples

IF (STATUS .EQ. 0) THEN

WRITE (6) EMPLOYEE_REC

ELSE IF (STATUS .EQ. FOR$IOS_ATTACCNON) THEN

TYPE *, ’Nonexistent record.’

ELSE IF (STATUS .EQ. FOR$IOS_RECNUMOUT) THEN

TYPE *, ’Record number out of range.’

ELSE

CALL ERRSNS (, RMS_STS, RMS_STV,,)

CALL LIB$SIGNAL (%VAL(RMS_STS), %VAL(RMS_STV))

ENDIF

Loop

GOTO 100

999 END

Sample Use:

$ FORTRAN RELATIVE

$ LINK RELATIVE

$ RUN RELATIVE

Record number: 7

08001FLANJE119PL1920

Record number: 1

07672ALBEHA210SE2100

Record number: 30

Nonexistent record.

Record number: Ctrl/Z

The INCLUDE statement defines all Fortran I/O status codes.

The OPEN statement defines the file and record processing characteristics.

Although the file organization is specified as relative, RMS would in fact obtain the file organization from an existing file. If the file’s organization were not relative, the file OPEN statement would fail.

The file is being opened for unformatted I/O because the data records will be read into an HP Fortran record (EMPLOYEE_REC), and HP Fortran does not allow records to be used in formatted I/O.

# The READ statement reads the record specified in REC_NUM, rather than the next consecutive record. The status code for the record operation is returned in the variable STATUS.

$ These statements test the record operation status obtained in comment

3. Note, the status codes returned by RMS and HP Fortran are not numerically or functionally similar.

% RMS status codes actually require two parameters. These values can be obtained using the ERRSNS subroutine.

Using System Services: Examples F–17

F.8 Measuring and Improving Performance

This example demonstrates how to adjust the size of the process working set from a program.

Source Program:

File: ADJUST.F90

This program demonstrates how a program can control

its working set size using the $ADJWSL system service.

IMPLICIT

INCLUDE

INTEGER (A-Z)

’($SYSSRVNAM)’

INTEGER (KIND=4) ADJUST_AMT

INTEGER (KIND=4) NEW_LIMIT

/0/

CALL LIB$INIT_TIMER

DO ADJUST_AMT= -50,70,10

Modify working set limit

RESULT = SYS$ADJWSL( %VAL(ADJUST_AMT), NEW_LIMIT) !

IF (.NOT. RESULT) CALL LIB$STOP(%VAL(RESULT))

TYPE 50, ADJUST_AMT, NEW_LIMIT

50 FORMAT(’ Modify working set by’, I4, ’ New working set size =’, I5)

END DO

CALL LIB$SHOW_TIMER

END PROGRAM

Sample Use:

$ SET WORKING_SET/NOADJUST

$ SHOW WORKING_SET

Working Set /Limit=2000 /Quota=4000 /Extent=98304

Adjustment disabled Authorized Quota=4000 Authorized Extent=98304

Working Set (8Kb pages) /Limit=125 /Quota=250 /Extent=6144

Authorized Quota=250 Authorized Extent=6144

$ FORTRAN ADJUST

$ LINK ADJUST

F–18 Using System Services: Examples

$ RUN ADJUST

Modify working set by -50 New working set size = 1936 #

Modify working set by -40 New working set size = 1888

Modify working set by -30 New working set size = 1856

Modify working set by -20 New working set size = 1824

Modify working set by -10 New working set size = 1808

Modify working set by 0 New working set size = 1808

Modify working set by 10 New working set size = 1824

Modify working set by 20 New working set size = 1856

Modify working set by 30 New working set size = 1888

Modify working set by 40 New working set size = 1936

Modify working set by 50 New working set size = 2000

Modify working set by 60 New working set size = 2064

Modify working set by 70 New working set size = 2144

ELAPSED: 0 00:00:00.01

CPU: 0:00:00.01

BUFIO: 13 DIRIO: 0 FAULTS: 24

The call to SYS$ADJWSL call uses a function invocation.

The DCL SHOW WORKING_SET command displays the current working set limit and the maximum quota.

# The SYS$ADJWSL is used to increase or decrease the number of pages in the process working set.

The program cannot decrease the working set limit beneath the minimum established by the operating system, nor can the process working set be expanded beyond the authorized quota.

F.9 Accessing Help Libraries

The following example demonstrates how to obtain text from a help library.

After the initial help request has been satisfied, the user is prompted and can request additional information.

Source Program:

File: HELPOUT.F90

This program satisfies an initial help request and enters interactive

HELP mode.

The library used is SYS$HELP:HELPLIB.HLB.

IMPLICIT INTEGER (KIND=4) (A - Z)

CHARACTER(LEN=32) KEY

EXTERNAL LIB$PUT_OUTPUT,LIB$GET_INPUT

Request a HELP key

WRITE (6,200)

200 FORMAT(1X,’What Topic would you like HELP with? ’,$)

READ (5,100) KEY

100 FORMAT (A32)

Using System Services: Examples F–19

Locate and print the help text

STATUS = LBR$OUTPUT_HELP(LIB$PUT_OUTPUT,,KEY, & "

’HELPLIB’,,LIB$GET_INPUT)

IF (.NOT. STATUS) CALL LIB$STOP (%VAL(STATUS))

END PROGRAM

Sample Use:

$ FORTRAN HELPOUT

$ LINK HELPOUT

$ RUN HELPOUT

What topic would you like HELP with? TYPE

TYPE

Displays the contents of a file or a group of files on the current output device.

Format:

TYPE file-spec[,...]

Additional information available:

Parameters Qualifiers

/BACKUP

/EXACT

/BEFORE /BY_OWNER /CONFIRM /CONTINUOUS /CREATED

/EXCLUDE /EXPIRED /HEADER /HIGHLIGHT /MODIFIED /OUTPUT

/PAGE

Examples

/SEARCH /SINCE /TAIL /WRAP

TYPE Subtopic? /HIGHLIGHT

TYPE

/HIGHLIGHT

/HIGHLIGHT[=keyword]

/NOHIGHLIGHT (default)

Use with the /PAGE=SAVE and /SEARCH qualifiers to specify the type of highlighting you want when a search string is found. When a string is found, the entire line is highlighted. You can use the following keywords: BOLD, BLINK, REVERSE, and UNDERLINE. BOLD is the default highlighting.

TYPE Subtopic?

Ctrl/Z

To pass the address of LIB$PUT_OUTPUT and LIB$GET_INPUT, they must be declared as EXTERNAL. You can supply your own routines for handling input and output.

" The address of an output routine is a required argument. When requesting prompting mode, the default mode, an input routine must be specified.

F–20 Using System Services: Examples

F.10 Creating and Managing Other Processes

The following example demonstrates how a created process can use the

SYS$GETJPIW system service to obtain the PID of its creator process. It also shows how to set up an item list to translate a logical name recursively.

Source Program:

File: GETJPI.F90

This program demonstrates process creation and control.

It creates a subprocess then hibernates until the subprocess wakes it.

IMPLICIT

INCLUDE

INTEGER (KIND=4) (A - Z)

’($SSDEF)’

’($LNMDEF)’

INCLUDE ’($SYSSRVNAM)’

CHARACTER(LEN=255) TERMINAL

CHARACTER(LEN=9)

CHARACTER(LEN=5)

FILE_NAME

SUB_NAME

INTEGER (KIND=4)

CHARACTER(LEN=17)

PROCESS_ID

TABNAM

CHARACTER(LEN=255) RET_STRING

CHARACTER(LEN=2) ESC_NULL

/’SYS$OUTPUT’/

/’GETJPISUB’/

/’OSCAR’/

/0/

/’LNM$PROCESS_TABLE’/

INTEGER (KIND=4)

RET_ATTRIB

RET_LENGTH

STRUCTURE /ITMLST3_3ITEMS/

STRUCTURE ITEM(3)

INTEGER (KIND=2) BUFFER_LENGTH

INTEGER (KIND=2) CODE

INTEGER (KIND=4) BUFFER_ADDRESS

INTEGER (KIND=4) RETLEN_ADDRESS

END STRUCTURE

INTEGER (KIND=4) END_OF_LIST

END STRUCTURE

RECORD /ITMLST3_3ITEMS/ TRNLST

/10/

Translate SYS$OUTPUT

Set up TRNLST, the item list for $TRNLNM

TRNLST.ITEM(1).CODE = LNM$_STRING

TRNLST.ITEM(1).BUFFER_LENGTH = 255

TRNLST.ITEM(1).BUFFER_ADDRESS = %LOC(RET_STRING)

TRNLST.ITEM(1).RETLEN_ADDRESS = 0

TRNLST.ITEM(2).CODE = LNM$_ATTRIBUTES

TRNLST.ITEM(2).BUFFER_LENGTH = 4

TRNLST.ITEM(2).BUFFER_ADDRESS = %LOC(RET_ATTRIB)

TRNLST.ITEM(2).RETLEN_ADDRESS = 0

TRNLST.ITEM(3).CODE = LNM$_LENGTH

TRNLST.ITEM(3).BUFFER_LENGTH = 4

TRNLST.ITEM(3).BUFFER_ADDRESS = %LOC(RET_LENGTH)

TRNLST.ITEM(3).RETLEN_ADDRESS = 0

Using System Services: Examples F–21

TRNLST.END_OF_LIST = 0

Translate SYS$OUTPUT

100 STATUS = SYS$TRNLNM (,TABNAM,TERMINAL(1:RET_LENGTH),,TRNLST)

IF (.NOT. STATUS) CALL LIB$STOP (%VAL(STATUS))

IF (IAND(LNM$M_TERMINAL, RET_ATTRIB).EQ. 0) THEN

TERMINAL = RET_STRING(1:RET_LENGTH)

GO TO 100

ENDIF

Check if process permanent file

ESC_NULL(1:2) = char(’1B’x)//char(’00’x)

IF (RET_STRING(1:2) .EQ. ESC_NULL) THEN

ENDIF

RET_STRING = RET_STRING(5:RET_LENGTH)

RET_LENGTH = RET_LENGTH - 4

Create the subprocess

STATUS = SYS$CREPRC (PROCESS_ID, FILE_NAME,, &

RET_STRING(1:RET_LENGTH),,,, &

SUB_NAME,%VAL(4),,,)

IF (.NOT. STATUS) CALL LIB$STOP (%VAL(STATUS))

TYPE 10, PROCESS_ID

10 FORMAT (’ PID of subprocess OSCAR is ’, Z)

Wait for wakeup by subprocess

STATUS = SYS$HIBER ()

IF (.NOT. STATUS) CALL LIB$STOP (%VAL(STATUS))

TYPE *, ’GETJPI has been awakened.’

END PROGRAM

File: GETJPISUB.F90

This separately compiled program is run in the subprocess OSCAR

which is created by GETJPI.

It obtains its creator’s PID and then

wakes it.

F–22 Using System Services: Examples

IMPLICIT

INCLUDE

INTEGER (KIND=4) (A - Z)

’($JPIDEF)’

INCLUDE ’($SYSSRVNAM)’

STRUCTURE /GETJPI_IOSB/

INTEGER(KIND=4) STATUS

INTEGER(KIND=4) %FILL

END STRUCTURE

RECORD /GETJPI_IOSB/ IOSB

STRUCTURE /ITMLST3_1ITEM/

STRUCTURE ITEM

INTEGER (KIND=2) BUFFER_LENGTH

INTEGER (KIND=2) CODE

INTEGER (KIND=4) BUFFER_ADDRESS

INTEGER (KIND=4) RETLEN_ADDRESS

END STRUCTURE

INTEGER (KIND=4)

END STRUCTURE

END_OF_LIST

RECORD /ITMLST3_1ITEM/ JPI_LIST

Set up buffer address for GETJPI

JPI_LIST.ITEM.CODE = JPI$_OWNER

JPI_LIST.ITEM.BUFFER_LENGTH = 4

JPI_LIST.ITEM.BUFFER_ADDRESS = %LOC(OWNER_PID)

JPI_LIST.ITEM.RETLEN_ADDRESS = 0

Get PID of creator

STATUS = SYS$GETJPIW (%VAL(1),,, JPI_LIST,IOSB,,)

IF (.NOT. STATUS) CALL LIB$STOP (%VAL(STATUS))

IF (.NOT. IOSB.STATUS) CALL LIB$STOP (%VAL(IOSB.STATUS))

Wake creator

TYPE *, ’OSCAR is waking creator.’

STATUS = SYS$WAKE (OWNER_PID,)

IF (.NOT. STATUS) CALL LIB$STOP (%VAL(STATUS))

END PROGRAM

Sample Use:

$ FORTRAN GETJPI,GETJPISUB

$ LINK GETJPI

$ LINK GETJPISUB

$ RUN GETJPI

PID of subprocess OSCAR is 2120028A

OSCAR is waking creator.

GETJPI has been awakened.

The subprocess is created using SYS$CREPRC.

The process hibernates.

Using System Services: Examples F–23

# The INCLUDE statement defines the value of all JPI$ codes including

JPI$_OWNER. JPI$_OWNER is the item code which requests the PID of the owner process. If there is no owner process (that is, if the process about which information is requested is a detached process), the system service

$GETJPIW returns a PID of zero.

$ Because of the item code JPI$_OWNER in the item list, $GETJPIW returns the PID of the owner of the process about which information is requested.

If the item code were JPI$_PID, $GETJPIW would return the PID of the process about which information is requested.

Because the default value of 0 is used for arguments PIDADR and

PRCNAM, the process about which information is requested is the requesting process, namely, OSCAR.

% The item list for SYS$GETJPIW consists of a single item descriptor followed by a zero longword.

F–24 Using System Services: Examples

Index

A

Abort

See Ctrl/C; Ctrl/Y

ACCEPT statement, 6–4

See also LRM

Access modes

See Record access mode

ACCESS specifier, 6–24, 6–30

See also LRM

Accuracy and dummy aliases, 5–61 hoisting divide operations, 5–61 numerical data I/O formatted and unformatted, 5–34 qualifiers affecting argument use, 2–38, 5–61 constants, 2–38 floating-point, 2–36, 2–38, 2–42,

2–65, 2–79, 5–60 floating-point underflow, 2–42 source code changes affecting calculations,

5–39

ACTION specifier, 6–24

See also LRM

Actual arguments, 10–2

See also Arguments

Address correlation table effect of /DEBUG qualifier, 2–49

Addresses

64-bit (cDEC$ ATTRIBUTES ADDRESS64 directive), 10–20

ADVANCE specifier, 6–36

See also LRM

Advancing I/O, 6–36

AIMAG intrinsic function

See also LRM qualifier controlling size returned, 2–76

Alignment argument passing, 5–20

HP Fortran and C structures, 10–58 array elements, 5–20 cDEC$ OPTIONS directive, 2–31 checking for unaligned data, 2–90, 5–21 common block data, 5–22 derived-type data, 5–24 detecting unaligned data (compile-time),

2–89, 5–21 detecting unaligned data (run-time), 5–21 condition handler, 14–23 debugger, 4–27 effect of declaration statements, 5–18 to

5–26 locating unaligned data (debugger), 4–27 naturally aligned data (definition), 5–17 of data types, 2–27, 5–17 to 5–28 qualifiers controlling, 2–27 to 2–31, 5–26 to 5–28 messages (compile-time), 2–89, 5–21 warnings for unaligned data, 2–90 record structures, 5–26

SEQUENCE statement effect on derived-type data, 5–24,

5–27 unaligned data (definition), 5–18 warning messages for unaligned data,

2–90

Index–1

/ALIGNMENT=COMMONS qualifier, 2–27 effect of /FAST qualifier, 2–31, 5–26

/ALIGNMENT=NOSEQUENCE qualifier,

5–24, 5–27

/ALIGNMENT qualifier, 2–27, 5–26

[NO]SEQUENCE keyword, 2–30

Allocating disk space

SYS$EXTEND (RMS), 11–21

Allocating virtual memory

See also LRM

LIB$GET_VM, 10–27

Allocation control block

XABALL (RMS), 11–13

Allocation listing, memory linker output, 3–3, 3–6 to 3–7

Alpha processor generation specifying code generation instruction types, 2–33, 5–60 specifying for optimization, 2–74, 5–58

Alternate key fields (indexed files) definition, 12–2 discussion of use, 12–2 to 12–6

ANA file type, 2–32

Analysis file created by FORTRAN command, 2–31

/ANALYSIS_DATA qualifier, 2–31

Annotations example, 2–111

/ANNOTATIONS qualifier, 2–32

APPEND specifier, 6–35

See also LRM

/ARCHITECTURE (Alpha only) qualifier,

2–33

/ARCHITECTURE qualifier, 5–60

Argument passing alignment of data passed, 5–20

64-bit addressing (cDEC$ ATTRIBUTES),

10–16

C and HP Fortran, 10–16 to 10–21,

10–49 alignment of structures, 10–58 arrays, 10–61 cDEC$ ATTRIBUTES C directive,

10–15

Argument passing

C and HP Fortran (cont’d) changing default mechanisms, 10–15,

10–16, 10–55 common block values, 10–63 complex data example, 10–56 data types, 10–51 to 10–55 examples, 10–55, 10–59, 10–62 integer data example, 10–55 pointer data, 10–59 to 10–61 structures, 10–58 using C conventions, 10–18 character constant actual arguments,

2–40 characters, 10–6 null terminated, 10–55

Compaq Fortran 77 and HP Fortran,

10–44 to 10–49, B–6 to B–9 alignment qualifiers, 10–48 common block values, 10–48 data type sizes, 10–45 data types to avoid, 10–44 derived-type data, 10–45 differences, B–14 to B–16 examples, 10–46 function values, 10–44, 10–46

I/O compatibility, 10–49 mechanisms, 10–45 passing target or pointer data, 10–47 pointer data, 10–45 similarities, 10–6 using Compaq Fortran 77 features,

10–44 directives (cDEC$ ATTRIBUTES), 10–16 efficient array use, 5–28

HP Fortran, 10–2 to 10–9 array descriptor format, 10–10 arrays, 10–8 array temporary creation, 5–32 built-in functions, 10–11 to 10–14 by address (%LOC), 10–13 by descriptor (%DESCR), 10–12 by reference (%REF), 10–14 by value (%VAL), 10–13

Index–2

Argument passing

HP Fortran (cont’d) changing default mechanisms, 10–11,

10–15, 10–16 characters, 10–6 default passing mechanism, 10–6 explicit interface, 10–3 to 10–5 implicit interface, 10–3 omitted arguments (extra comma),

10–6 pointers, 10–9 rules, 10–6 to 10–9

OpenVMS calling standard, 10–24

OpenVMS mechanisms, 10–11

RMS arguments, 11–16 when temporary array copy is created,

5–28

Arguments, 10–2

See also Argument passing; LRM actual, 10–2 character constant, 2–40 differences between Compaq Fortran

77 and HP Fortran, B–16 dummy, 10–2 aliasing and accuracy, 2–35, 5–61 and implied-DO loop collapsing, 5–37 maximum allowed in a function reference, 2–102 on CALL statement, 2–102 memory allocation, 10–24

OpenVMS standard for, 10–24 qualifier controlling warning messages,

2–90

Arithmetic exception handling

See also Condition-handler routines causes of exceptions, 14–2 compiler options

/CHECK, 2–42 to 2–45

/FAST, 2–53

/FLOAT, 2–54

/IEEE_MODE qualifier, 2–58

/MATH_LIBRARY, 2–65

/SYNCHRONOUS_EXCEPTIONS,

2–86 continuation, 7–2

Arithmetic exception handling (cont’d) controlling reporting of exceptions, 2–43,

2–45, 2–86 error reporting, 7–2 exceptional value message reporting,

2–43 floating point array bounds checking, 2–42 certain exponentiation expressions,

2–44 control IEEE exceptions, 2–58 controlling reporting of exceptions,

2–43, 2–58, 2–86 exceptional values, 2–43, 2–58, 8–19 to 8–23 handling of minus zero, 2–39 math library used, 2–53, 2–65 reporting underflow messages, 2–45 types used in memory, 2–54 underflow, 2–45, 2–58, 8–20

IEEE NaN values (quiet and signaling),

8–20 infinity values, 8–20 integer overflow, 2–42, 2–44 locating exceptions in debugger, 4–25 qualifiers needed to obtain traceback information, 3–14 setting breakpoints in the debugger, 4–25 using a condition handler routine, 14–22,

14–24

Arithmetic exceptions

See Arithmetic exception handling;

Exception conditions

Arithmetic operators for efficient run-time performance, 5–39

Array references

/CHECK options at compilation, 2–42

Arrays

See also Argument passing; LRM accessing in debugger, 4–17 alignment, 5–20 allocatable, 10–10 and explicit interface, 10–7, 10–8, 10–10 arguments, 2–42, 10–8, 10–10

See also LRM

Index–3

Arrays arguments (cont’d)

Compaq Fortran 77 and HP Fortran similarities, 10–6 example, 1–6, 10–47 example (C and HP Fortran), 10–62 array temporary creation, 5–32 assumed-shape, 10–6, 10–10, 10–11,

10–45 bounds run-time checking, 2–42 character, 10–6 column-major order, 5–29, 10–61 compiler checking for out-of-bounds references, 2–42 conformable, 10–8 declaring

See LRM deferred-shape, 10–6, 10–11 differences between HP Fortran and C,

10–61 dimension limits, 2–102 efficient combinations of input and output arguments, 5–28 efficient syntax in I/O list, 5–34 efficient use, 5–28 element sequence association, 10–9 explicit-shape, 10–10 example passing, 10–46, 10–62 natural storage order, 5–29 optimizations, 5–43, 5–50 output listing information, 2–113 passing as arguments example, 1–7 row-major order, 5–29, 10–61 syntax for run-time efficiency, 5–28 using efficiently, 5–28 when temporary copy is created for argument passing, 5–28 writing for efficiency, 5–35

Assembly code used to represent object code, 2–65

ASSIGN command (DCL), D–1

ASSOCIATEVARIABLE specifier, 6–24

See also LRM

Association host, 10–4 procedure interface, 10–5 use, 10–3 procedure interface block, 1–6 to 1–8,

10–5

/ASSUME qualifier, 2–35

ALTPARAM keyword, 2–37

BUFFERED_IO keyword, 2–37

BYTERECL keyword, 2–37

DUMMY_ALIASES keyword, 2–38, 5–61 to 5–63

FP_CONSTANT keyword, 2–38, 2–39

MINUS0 keyword, 2–39

NOACCURACY_SENSITIVE keyword,

2–36, 5–60

PROTECT_CONSTANTS keyword, 2–39

SOURCE_INCLUDE keyword, 2–39

Asynchronous reentrancy effect on RTL, 2–79

Asynchronous System Trap (AST) procedures example use, F–3 to F–6

/AUTOMATIC qualifier, 2–40, 2–78

Automatic storage arguments, 10–7 of variables on run-time stack, 2–78

B

BACKSPACE statement, 6–4, 6–35

Basic linear algebra routines (Compaq

Extended Math Library), 15–2

Batch job compiler errors during, 2–102 effect on /LIST qualifier default, 2–14

Bit manipulation functions

See LRM

$BLANK program section use and attributes, 13–2

BLANK specifier, 6–24

See also LRM

Compaq Fortran 77 differences, B–10

Index–4

BLAS routines (Compaq Extended Math

Library), 15–2

Block IF statement

See also LRM nesting limit, 2–102

BLOCKSIZE specifier, 5–35, 6–24

See also LRM

Bottleneck reduction of I/O, 5–33

$BSS$ program section use and attributes, 13–2

BUFFERCOUNT specifier, 5–35, 6–24

See also LRM

Buffers for record I/O, 5–35

Built-in functions

See also LRM; cDEC$ ATTRIBUTES

%DESCR function, 10–12

%LOC function, 10–13

%REF function, 10–14 used in passing arguments, 10–11 to

10–14

%VAL function, 10–13

/BY_REF_CALL qualifier, 2–40

C

Calling interface

See Argument passing; Language interface

Call stack use by CHF, 14–2

CALL statement, 10–2

See also LRM maximum arguments allowed, 2–102 used to call system services, 10–31

CARRIAGECONTROL specifier, 2–41, 6–14,

6–23

See also LRM effect of /CCDEFAULT qualifier, 2–41

Case sensitive external names in C controlling with cDEC$ directives,

10–15, 10–16

Case-sensitive names flagging lowercase (/STANDARD), 2–84 option controlling, 2–67

Catchall condition handler, 14–5

/CCDEFAULT qualifier, 2–41

CDD

See also CDDL

CDD/Repository, 2–96 to 2–101

See also CDDL (Common Data Dictionary

Language)

See also CDO (Common Data Dictionary

Operator) accessing from HP Fortran programs,

2–98

CDD records including in source listing, 2–83 data types, 2–99

CDDL (Common Data Dictionary Language),

2–96 cDEC$ ALIAS directive, 10–15 cDEC$ ATTRIBUTES

ADDRESS64 directive, 10–20

ALIAS directive, 10–19

C directive, 10–17 example, 10–18

EXTREN directive, 10–20

REFERENCE directive, 10–19

VALUE directive, 10–19

VARYING directive, 10–20 cDEC$ ATTRIBUTES directive, 10–16 cDEC$ directives, 5–63, 10–15 cDEC$ OPTIONS directive and alignment, 2–31 cDEC$ PSECT directive changing attributes, 13–2

CDO (Common Data Dictionary Operator) data types, 2–99 definition, 2–96 using, 2–98

Cells in relative files, 6–8

CHARACTER

See also LRM data type representation, 8–23

Index–5

Character arguments constant actual arguments, 2–40 passing between HP Fortran and C, 10–6

Character data checking for out-of-bounds references,

2–42 constant actual arguments, 2–40 using whole character string operations for run-time efficiency, 5–34

Characters flagging lowercase (/STANDARD), 2–84

Character set

See LRM

CHAR intrinsic, B–11

CHAR intrinsic procedure to null-terminate a C string, 10–6

/CHECK qualifier, 2–42

ALL keyword, 2–45

ARG_INFO (I64 only) keyword, 7–2

ARG_INFO keyword (I64 only), 2–42

ARG_TEMP_CREATED keyword, 2–42

BOUNDS keyword, 2–42

FORMAT keyword, 2–43

FP_EXCEPTIONS keyword, 2–43

FP_MODE (I64 only) keyword, 7–2

FP_MODE keyword (I64 only), 2–43

NONE keyword, 2–45

OUTPUT_CONVERSION keyword, 2–44

OVERFLOW keyword, 2–44

POWER keyword, 2–44

UNDERFLOW keyword, 2–45

CHF

See Condition-Handling Facility (CHF);

Condition-handler routines

$CHFDEF library module in FORSYSDEF, 14–11, 14–13

C language

See also Argument passing; Language interfaces argument passing with HP Fortran examples, 10–55, 10–59, 10–62 calling between HP Fortran and C, 10–16 to 10–21, 10–49 compiling programs, 10–49 example array passing, 10–62

C language (cont’d) example of function call by HP Fortran,

10–55, 10–59, 10–62 handling arrays, 10–61

Close operations

CLOSE statement, 6–4, 6–28 closing a file using RMS, 11–19

CLOSE statement, 6–4, 6–28

See also LRM

CMPLX intrinsic function

See also LRM qualifier controlling size returned, 2–76

$CODE$ program section use and attributes, 13–2

Code generation for specific Alpha processor generation,

5–60

Code hoisting in divide operations, 5–61 in optimization, 5–48

COM file type, 13–14

Command line

See also Compiler options; FORTRAN command; LINK command; DEBUG command; DEFINE command;

DEASSIGN command abbreviating list of input files, 2–3 abbreviating qualifier names and keywords, 2–18 consistent use of qualifiers for multiple compilations, 2–5 differences from Compaq Fortran 77 for

OpenVMS VAX Systems, B–19 to

B–23 specifying multiple keywords for a qualifier, 2–18

Command procedures returning status values to, 3–12 to measure run-time performance, 5–13

Comment lines

See also LRM

D in column 1 (/D_LINES), 2–49

Common blocks

See also LRM accessing variables in debugger, 4–15

Index–6

Common blocks (cont’d) alignment of data in, 5–22 causes of misalignment, 5–18 changing program section attributes,

13–2 installed creation, installation, and use, 13–5 to 13–9 synchronizing access, 13–9 to 13–10 order of data in, 5–22 program section (PSECT) attributes,

13–6 qualifiers controlling alignment, 5–26 shared interprocess example, F–8 use of VOLATILE statement, 13–4

Common Data Dictionary

See CDD; CDDL

COMMON statement

See also LRM; Common block and data-flow and split lifetime analysis,

5–49 causes of misalignment, 5–18 data alignment, 2–27, 5–26

Common subexpression elimination, 5–43

Communications, network task-to-task,

13–13 to 13–15

Compaq Extended Math Library

See CXML

Compaq Fortran 77 compiler diagnostic detection differences,

B–14 for OpenVMS Alpha systems argument passing, 10–44 calling between HP Fortran, 10–44 to 10–49

I/O to same unit number, 10–49 passing aligned data, 10–48 passing common block values, 10–48 passing pointers, 10–45 passing same size data, 10–48 for OpenVMS I64 and Alpha systems compiler detection differences, B–14 language features not supported, B–6 for OpenVMS VAX systems

Compaq Fortran 77 for OpenVMS VAX systems (cont’d) compatibility, B–19 to B–26 equivalent record types, B–24 floating-point format differences, B–8

FORTRAN command qualifier, 2–88 language features not supported, B–6 porting data, B–24

VAX H_float representation, B–26 other platforms language compatibility (summary),

B–1 record type portability, 6–11 request Fortran 77 compiler (/OLD_F77),

2–68

Compaq Fortran 77 OpenVMS Alpha systems mixed language example, 10–46

Compatibility

See also LRM

DO loop minimum iteration count

(/NOF77), 2–53

OPEN statement specifier defaults

(/NOF77), 2–53

PARAMETER syntax (/ASSUME), 2–37 request Compaq Fortran 77 compiler

(/OLD_F77), 2–68 translated images

FORTRAN command, 2–88

LINK command, 3–3, 3–5 unformatted files record length unit,

RECL (/ASSUME), 2–37 with Compaq Fortran 77 for OpenVMS

Alpha Systems command line, B–19 to B–23 feature summary, B–1

I/O compatibility, 10–49 language features, B–4, B–6, B–9 request Fortran 77 compiler

(/OLD_F77), 2–68 with Compaq Fortran 77 for OpenVMS

VAX systems architectural differences, B–8 with Compaq Fortran 77 for OpenVMS

VAX Systems

Index–7

Compatibility with Compaq Fortran 77 for OpenVMS

VAX Systems (cont’d) command line, B–19 to B–23 converting data, 9–3 feature summary, B–1 interpretation differences, B–13 language features, B–4, B–6, B–9 porting data, B–24 record types, 6–11 translated images, B–24

/VMS qualifier, 2–88 with Compaq Visual Fortran (CVF) feature summary, B–1 with HP Fortran for Tru64 UNIX systems feature summary, B–1 record types, 6–11 with HP Fortran on other platforms, B–1

Compiler

See also FORTRAN command assumptions (/ASSUME), 2–35 coding restrictions summary of, 2–101 data format assumptions (/CONVERT),

2–45 data format assumptions (/FLOAT), 2–54 data porting assumptions, 2–45 default file names, 6–18 effect of directives on performance, 5–63 effect of optimization level on compilation time and object file size, 5–40 functions, 2–1 to 2–2 input to linker, 2–1 to 2–2 limits, 2–101 messages issued by compiler-fatal messages, C–4 general description, 2–102 limiting, 2–52 source program messages, C–2 to

C–4 process memory size, 1–3 process open file limit, 1–3 request Compaq Fortran 77 compiler

(/OLD_F77), 2–68 request threaded run-time execution,

2–78

Compiler (cont’d) using latest version for run-time efficiency, 5–1

Compiler directives, 5–63

See also LRM cDEC$ ALIAS, 10–15 cDEC$ ATTRIBUTES, 10–15 cDEC$ OPTIONS directive, 2–31 cDEC$ PSECT, 13–2

OPTIONS statement, 2–18, 9–13

Compiler options

See also FORTRAN command accuracy checking overflow, bounds, underflow

(/CHECK), 2–42 dummy variable use (/ASSUME),

2–35 floating-point calculations

(/ASSUME), 2–36 floating-point format (/FLOAT), 2–54 handling of single-precision constants

(/ASSUME), 2–38

IEEE exception handling (/IEEE_

MODE), 2–58

IEEE rounding mode (/ROUNDING_

MODE), 2–79 math routines used (/MATH_

LIBRARY), 2–65

REAL and COMPLEX declarations

(/REAL_SIZE), 2–76 set multiple qualifiers (/FAST), 2–53 size of DOUBLE PRECISION declarations (/DOUBLE_SIZE),

2–51

Alpha processor code generation

(/ARCHITECTURE), 2–33 arguments case sensitivity of external names

(/NAMES), 2–67 character constant actual arguments,

2–40 dummy variable use (/ASSUME),

2–35 code generation for Alpha processor

(/ARCHITECTURE), 2–33

Index–8

Compiler options (cont’d)

Compaq Fortran 77 for OpenVMS VAX

Systems specific, B–22 compatibility

Compaq Fortran 77 compiler

(/OLD_F77), 2–68

Compaq Fortran 77 for OpenVMS

VAX Systems (/VMS), 2–88 data alignment errors, 2–27 dummy arguments (/ASSUME), 2–38 floating-point constants (/ASSUME),

2–38

FORTRAN 66 processing (/F77),

2–53

Fortran 90 standard conformance

(/STANDARD), 2–84

Fortran 95 standard conformance

(/STANDARD), 2–84 integer constants (/ASSUME), 2–39 pad source lines with spaces

(/PAD_SOURCE), 2–76

PARAMETER syntax (/ASSUME),

2–37 requesting compiler diagnostics

(/WARNINGS), 2–89 translated images (/TIE), 2–88 unformatted files record length unit,

RECL (/ASSUME), 2–37 compatibility with Compaq Fortran 77 for

OpenVMS VAX Systems, B–19 to data

B–23 alignment (/ALIGNMENT), 2–27 automatic storage (/AUTOMATIC),

2–78

DOUBLE PRECISION declaration size (/DOUBLE_SIZE), 2–51 floating-point constants (/ASSUME),

2–38

IEEE exception handling (/IEEE_

MODE), 2–58

IEEE floating-point value of -0.0

(/ASSUME), 2–39

IEEE rounding mode (/ROUNDING_

MODE), 2–79

Compiler options data (cont’d)

INTEGER and LOGICAL declaration size (/INTEGER_SIZE), 2–62 integer constants (/ASSUME), 2–39 memory floating-point data type

(/FLOAT), 2–54

REAL and COMPLEX declaration size (/REAL_SIZE), 2–76 recursive procedures (/RECURSIVE),

2–78 shared memory granularity

(/GRANULARITY), 2–57 unformatted file data types

(/CONVERT), 2–45 unformatted files record length unit,

RECL (/ASSUME), 2–37 debugging fixed-form source (/D_LINES), 2–49

/OPTIMIZE, 2–68 suggested /OPTIMIZE use, 2–50 symbol table and traceback

(/DEBUG), 2–49 files directory search for include or module files (/INCLUDE), 2–60 directory to place module files, 2–67

DML preprocessing (/DML), 2–51 locating and placing include files,

2–8 object file (/OBJECT), 2–68 requesting analysis file (/ANALYSIS_

DATA), 2–31 requesting diagnostic file

(/DIAGNOSTICS), 2–50 request listing file (/LIST), 2–63 specify text library file (/LIBRARY),

2–63 using module (F90$MOD) files, 2–5 fixed-form source

D in column 1 (/D_LINES), 2–49 pad source lines with spaces

(/PAD_SOURCE), 2–76 source line length (/EXTEND_

SOURCE), 2–53

Index–9

Compiler options fixed-form source (cont’d) specify source form (/SOURCE_

FORM), 2–84 functional groups of qualifiers, 2–24 listing file controlling contents of (/SHOW),

2–83 object code listing (/MACHINE_

CODE), 2–65 request listing file (/LIST), 2–63 messages accurate reporting of exceptions

(/SYNCHRONOUS_

EXCEPTIONS), 2–86 changing severity of (/SEVERITY),

2–82 limiting (/ERROR_LIMIT qualifier),

2–52 requesting additional (/WARNINGS),

2–89 requesting fewer (/WARNINGS),

2–89 run-time checking (/CHECK), 2–42 standard conformance (/STANDARD),

2–84 not available in Compaq Fortran 77 for

OpenVMS VAX Systems, B–20 object file name (/OBJECT), 2–68 one or multiple modules in object file

(/SEPARATE_COMPILATION),

2–81 prevent creation of (/NOOBJECT),

2–68 symbol table and traceback

(/DEBUG), 2–49 translated images (/TIE), 2–88 only check for syntax (/SYNTAX_ONLY),

2–87 optimization (/OPTIMIZE), 2–68 output buffer use (/ASSUME), 2–37 pad source lines with spaces (/PAD_

SOURCE), 2–76 performance

Compiler options performance (cont’d) alignment (/ALIGNMENT), 2–27 controlling Alpha code generation

(/ARCHITECTURE), 2–33 floating-point calculations

(/ASSUME), 2–36 floating-point format (/FLOAT), 2–54

IEEE exception handling (/IEEE_

MODE), 2–58

INTEGER and LOGICAL defaults

(/INTEGER_SIZE), 2–62 math routines used (/MATH_

LIBRARY), 2–65 optimization (/OPTIMIZE), 2–68 set multiple qualifiers (/FAST), 2–53 summary, 5–4 recursive procedures (/RECURSIVE),

2–78 reentrancy during RTL calls

(/REENTRANCY), 2–78 run-time checking accurate reporting of exceptions

(/SYNCHRONOUS_

EXCEPTIONS), 2–86

IEEE exception handling (/IEEE_

MODE), 2–58 requesting additional (/CHECK),

2–42 version number (/VERSION), 2–87

Compiler summary output listing section, 2–114

Compile-time operations, 5–44, 5–45

Compiling C language programs, 10–49

Completion status values returning to command procedure, 3–12

Complex data types, 2–54, 8–9, 8–15 to

8–18

See also LRM declarations and qualifiers, 8–10 native representation, 8–15 to 8–18 ranges, 8–4

VAX representation, 8–16 to 8–18

Index–10

COMPLEX declarations option to control size of, 2–76

Condition-handler routines

See also Condition-Handling Facility

(CHF); Error handling catchall condition handler, 14–4 checking for arithmetic exceptions,

14–22, 14–24 checking for data alignment traps, 14–23 coding requirements, 14–13 converting signal to return status

LIB$SIG_TO_RET, 14–21 definition of, 14–1 establishing handlers

LIB$ESTABLISH, 14–6 to 14–7 examples of use, 14–24 to 14–27 matching condition values

LIB$MATCH_COND, 14–19 removing handlers

LIB$REVERT, 14–6 to 14–7 returning from a handler, 14–17 return values

SS$_CONTINUE, 14–18

SS$_RESIGNAL, 14–18 signaling exception conditions

LIB$SIGNAL or LIB$STOP, 14–7 to

14–9 terminating handling for signals

LIB$SIG_TO_STOP, 14–22 traceback condition handler, 14–4 unwinding the call stack

SYS$UNWIND, 14–18 to 14–19 user written, 14–12 to 14–19 use of variables, 14–17 values and symbols passed, 14–9 to

14–12

Condition-Handling Facility (CHF), 14–2

See also Condition-handler routines default condition handlers, 14–4 to 14–5 overview, 14–3 use of call stack, 14–2

Condition signals changing to return status

LIB$SIG_TO_RET, 14–21

Condition symbols, Fortran summary of, 7–8 to 7–14

Constant operation

See Compile-time operations

Constants

See also LRM alternate PARAMETER syntax

(/ASSUME), 2–37 character actual arguments, 2–40 floating-point double precision, 2–38 maximum size, 2–102 ranges, 8–2 to 8–5

CONTAINS statement, 10–4

See also LRM

Continuation lines

See also LRM maximum allowed, 2–102

CONTINUE command (DCL), 3–11

/CONVERT qualifier, 2–45, 9–5, 9–14

BIG_ENDIAN keyword, 2–46

CRAY keyword, 2–46

FDX keyword, 2–46

FGX keyword, 2–47

IBM keyword, 2–47

LITTLE_ENDIAN keyword, 2–47

NATIVE keyword, 2–47

VAXD keyword, 2–48

VAXG keyword, 2–48

CONVERT specifier, 6–24, 9–4

See also LRM

Cross-reference information linking

/CROSS_REFERENCE qualifier, 3–3

Ctrl/C handling example routine, 10–43, F–3 handling routine, 3–12 interrupting interactive program execution, 3–11 to 3–12

Ctrl/Y interrupting interactive program execution, 3–11 to 3–12

Index–11

CVT$CONVERT_FLOAT example use, B–25

CXML, 15–1 to 15–5 example program, 15–4 groups of routines, 15–2 linking, 15–3 types of libraries provided, 15–3

CXML library for efficient run-time performance, 5–2

D

D, in column 1 qualifier controlling debugging indicator,

2–49

Data

See also Data types; Files; I/O; LRM alignment, 2–27 checking for unaligned data, 5–21 definition, 5–17 detecting unaligned data, 2–90, 4–27 effect of FORTRAN command qualifiers, 5–26 effect of statements, 5–22 placing declaration statements to avoid unaligned data, 5–22 unaligned arguments, 5–22 big endian definition, 9–2 numeric formats, 9–3 to 9–6 unformatted file formats, 2–45 comparison of formatted and unformatted,

6–5

COMPLEX setting default lengths, 2–76 converting unformatted files, 2–45, 9–2 to

9–15

DOUBLE PRECISION setting default lengths, 2–51 equivalent types for C and HP Fortran,

10–53 exchanging using mailboxes (SYS$CREMBX),

13–10 to 13–12

Data exchanging (cont’d) using network task-to-task communications, 13–13 to 13–15 floating-point formats used in memory,

2–54 formats for unformatted files, 2–45, 9–3 to 9–6 formatted I/O statements, 6–5

Compaq Fortran 77 differences, B–10 granularity of shared access, 2–57

INTEGER setting default lengths, 2–62 items in common blocks controlling alignment, 2–27, 5–22 items in derived-type data controlling alignment, 2–27, 5–22 items in record structures controlling alignment, 2–27, 5–22 list-directed I/O

Compaq Fortran 77 differences, B–11 statements, 6–6 little endian definition, 9–2

LOGICAL setting default lengths, 2–62 namelist I/O statements, 6–6

Compaq Fortran 77 differences, B–10 nonnative numeric formats, 9–3 to 9–6 nonnative VAX H_float formats, B–26 porting between HP Fortran and Compaq

Fortran 77 for OpenVMS VAX

Systems, B–24

REAL setting default lengths, 2–76 representation, 8–1 to 8–24 shared memory access, 2–57, 13–4 sharing in files, 6–32 to 6–34 in installed common areas, 13–8 to

13–9 in shareable image libraries, 13–4 to

13–5 using global pagefile section, F–8 to

F–11

Index–12

Data (cont’d) size and handling qualifiers for DOUBLE PRECISION declarations, 2–51, 2–77 qualifiers for INTEGER and

LOGICAL declarations, 2–62 qualifiers for REAL and COMPLEX declarations, 2–76 storage (automatic or static), 2–78 stored by HP Fortran, 8–1 to 8–24 translation of formatted, 6–6 unformatted I/O statements, 6–6 use of VOLATILE statement, 13–4

VAX floating-point formats, 9–3 to 9–6 zero-extended and sign-extended values,

10–13

$DATA$ program section use and attributes, 13–2

Data file advancing and nonadvancing I/O, 6–36 big endian porting notes, 9–15 unformatted numeric formats, 9–3 to

9–6 characteristics, 6–7 to 6–14

CLOSE statement, 6–28 comparison of formatted and unformatted,

6–5 converting unformatted files, 9–2 to 9–15 limitations, 9–3 efficient run-time performance, 5–33 handling I/O errors, 7–4

I/O unit, 6–2

INQUIRE statement, 6–25 internal, 6–9 nonnative

VAX H_float format, B–26 obtaining file characteristics (INQUIRE statement), 6–25 opening using

OPEN statement, 6–15 to 6–25 preconnected files, 6–15

SYS$OPEN, 11–22, 11–33

USEROPEN routine, 11–21

OPEN statement, 6–15 to 6–25

Data file (cont’d) organization, 6–7

RECL units for unformatted files, 2–37 record

I/O statements, 6–29 position, 6–35 transfer, 6–37 types, 6–10 scratch, 6–9 unformatted nonnative numeric formats,

9–3 to 9–15

VAX floating-point formats, 9–3 to 9–6

Data-flow and split lifetime analysis, 5–48 to 5–50

DATA statement

See also LRM and value propagation, 5–45

Data structures

See Derived-type data; Records; RMS data structures; Structures

Data types

See also Floating-point data types; Integer data type; Logical data type; LRM alignment of, 2–27, 5–17 to 5–28

Alpha IEEE X_float representation

REAL*16, 8–15 big endian definition, 9–2 unformatted file formats, 2–45, 9–3 to 9–6 character representation, 8–23 common block handling between HP

Fortran and C, 10–63 comparison of VAX and Alpha floating-point formats, B–24

COMPLEX representation, 8–9, 8–15 setting default lengths, 2–76 derived-type data alignment, 5–24 differences between HP Fortran and C,

10–54 differences between HP Fortran and

Compaq Fortran 77 for OpenVMS

VAX Systems, B–24

DOUBLE PRECISION declarations

Index–13

Data types

DOUBLE PRECISION declarations

(cont’d) qualifiers controlling size, 2–51, 2–77 equivalent in C and HP Fortran, 10–53 exceptional floating-point numbers, 8–21 for efficient run-time performance, 5–38 formats for unformatted files, 2–45, 9–3 to 9–6

Hollerith representation, 8–24

IEEE S_float representation

COMPLEX*8, 8–15

REAL*4, 8–11

IEEE T_float representation

COMPLEX*16, 8–16

REAL*8, 8–13

IEEE X_float representation

COMPLEX*32, 8–18

INTEGER representation, 8–5 to 8–7 setting default lengths, 2–62 little endian definition, 9–2 unformatted file formats, 2–45, 9–3 to 9–6

LOGICAL representation, 8–7 setting default lengths, 2–62 methods of using nonnative formats, 9–7 mixed operations and run-time performance, 5–38 native data representation, 8–1 to 8–24 native IEEE floating-point representation,

8–9 to 8–17 nonnative formats for unformatted file conversion, 9–3 to 9–6

VAX H_float representation, B–26

OpenVMS calling standard, 10–32 ranges denormalized native floating-point data, 8–3 native numeric types, 8–2 to 8–5

VAX floating-point types, 8–12 to

8–14

REAL

Data types

REAL (cont’d) representation, 8–9 to 8–15 setting default lengths, 2–76 sizes for efficient run-time performance,

5–38

VAX D_float representation

COMPLEX*16, 8–18

REAL*8, 8–14

VAX F_float representation

COMPLEX*8, 8–16

REAL*4, 8–12

VAX G_float representation

COMPLEX*16, 8–18

REAL*8, 8–13

VAX H_float representation, B–26 equivalent on Alpha systems, B–8

Date and time control block

XABDAT (RMS), 11–13

DBG$PROCESS, 4–3

Dead store elimination, 5–45

Deallocating virtual memory

LIB$FREE_VM, 10–27

DEASSIGN command (DCL), D–1

DEBUG command, 3–11

Debugger accessing array variables, 4–17 common block variables, 4–15 derived-type variables, 4–16 record structure variables, 4–16 variables in modules, 4–18 breakpoints, 4–6 character-cell interface line mode, 4–4 screen mode, 4–4 commands call, 4–6 changing values, 4–6 controlling execution, 4–6 deposit, 4–6 displaying source lines, 4–6 displaying values, 4–6 examine, 4–6 exit, 4–6

Index–14

Debugger commands (cont’d) for breakpoints, 4–6 for kept debugger, 4–8 for tracepoints, 4–7 for watchpoints, 4–7 go, 4–6 help, 4–6 spawn, 4–6 step, 4–6 stop, 4–6 type, 4–6 used often, 4–6 command summary, 4–18 to 4–24 compiler qualifier, 2–49 debugging configuration, 4–3 detecting an exception, 4–25 detecting unaligned data, 4–27 displaying online help, 4–6 values, 4–6 examining variables, 4–15 executing DCL commands, 4–6 exiting, 4–8 getting started, 4–1

HP Fortran support, 4–8 invoking, 3–11, 4–4

/KEEP qualifier, 4–5 kept debugger, 4–5 locating an exception, 4–25 locating unaligned data, 4–27 logical names, 4–3

Motif windowing interface, 4–3 restarting, 4–8 sample FORTRAN command, 1–10, 4–2 sample session, 4–9 windowing interface, 4–3

Debugging statement indicator in fixed-form source code, 2–49

/DEBUG qualifier, 3–13, 3–14

ALL keyword, 2–49

NONE keyword, 2–50 on FORTRAN command, 2–49 to 2–50,

4–2 on LINK command, 3–3, 3–13 to 3–16,

4–2

/DEBUG qualifier (cont’d) on RUN command, 3–11

SYMBOLS keyword, 2–49

TRACEBACK keyword, 2–49

Declarations

See also LRM misalignment and COMMON,

STRUCTURE, TYPE statements,

5–18

DECnet using to share and exchange data, 13–13 to 13–15

DECwindows Motif windowing interface to the OpenVMS

Debugger, 1–10

Default file names, 6–18 logical I/O unit names, 6–17 to 6–19

DEFAULTFILE specifier, 6–15, 6–23

See also LRM

DEFINE command (DCL), D–1

DEFINE FILE statement, 6–5

See also LRM

DELETE statement, 6–5

See also LRM

DELIM specifier, 6–24

See also LRM

Denormalized numbers (IEEE), 8–20 double-precision range, 8–3 exponent value of, 8–10

/IEEE_MODE qualifier, 2–58 single-precision range, 8–3

S_float range, 8–3

T_float range, 8–3

X_float range (IEEE Alpha), 8–15

Derived-type data

See also LRM accessing variables in debugger, 4–16 causes of misalignment, 5–18 controlling alignment of multiple data items, 5–22, 5–24 data alignment, 2–27 order of members, 5–19, 5–20, 5–24 qualifiers controlling alignment, 5–18,

5–26

Index–15

Derived-type data (cont’d)

SEQUENCE statement, 5–19, 5–24,

5–27, 10–58

%DESCR function, 10–12

See also Argument passing

Descriptor array format, 10–10, 10–11 character, 10–40

HP Fortran built-in functions, 10–11 memory allocation, 10–24 types of arguments generating, 10–24 used for different argument types, 10–6

DIA file type, 2–50

Diagnostic file created by FORTRAN command, 2–50

Diagnostic Messages

See Messages; Warning messages

/DIAGNOSTICS qualifier, 2–50

DICTIONARY parameter (/SHOW), 2–83

/DICTIONARY statement using for CDD/Repository, 2–97

Differences between OpenVMS I64 and OpenVMS

Alpha, A–1 to A–13

Direct access, 6–31

Direct access file

RECL values, 5–36

Direct access mode

See also Relative file relative files, 6–8 requirements for sequential files, 6–11

Directives

See LRM; OPTIONS statement; cDEC$ cDEC$, 5–63 cDEC$ ALIAS, 10–15 cDEC$ ATTRIBUTES, 10–15, 10–16

ADDRESS64, 10–16

ALIAS, 10–16

C, 10–16

REFERENCE, 10–16

STRUCT, 10–16

VALUE, 10–16 related to performance, 5–63

Directory application of defaults, 6–19 to 6–22 default for OPEN statement, 6–19 effect of DEFAULTFILE specifier, 6–19

I/O statements default use, 6–16 to 6–20 in I/O statements, 6–19 to 6–22

OPEN statement specifiers, 6–19, 6–23 searched for module and include files,

2–5 to 2–13, 2–60 searched for text library files, 2–9

Directory entries system services affecting list of, 11–21

Disk space allocation

SYS$EXTEND (RMS), 11–21

DISPOSE specifier, 6–23, 6–25

See also LRM

DML

See Data Manipulation Language (DML)

DML (Data Manipulation Language), 2–51

/DML qualifier, 2–51

Documentation sending comments to HP, xxvii

DO loops

See also LRM blocking optimization, 2–70, 2–72 distribution optimization, 2–70, 2–72 fusion optimization, 2–70, 2–72 interchange optimization, 2–70, 2–72 limiting loop unrolling, 5–50 outer loop unrolling optimization, 2–70,

2–72 qualifier controlling minimum iteration count (/NOF77), 2–53 scalar replacement optimization, 2–70,

2–72 software pipelining optimization, 2–70,

2–73, 5–53, 5–55 transformation optimizations, 2–70, 2–72,

5–54 use for efficient run-time performance,

5–40

DO statement

See also LRM nesting limit, 2–102

Index–16

Dot product operation and /ASSUME=NOACCURACY_

SENSITIVE qualifier, 5–60

DOUBLE PRECISION declarations option to control size of, 2–51 qualifiers to control size of, 2–77

/DOUBLE_SIZE qualifier, 2–51

Dummy arguments, 10–2, 13–4

See also LRM and accuracy, 5–61 and implied-DO loop collapsing, 5–37 qualifier for aliasing, 2–35, 5–61

DXML

See CXML

D_float data

See Floating-point data types

/D_LINES qualifier, 2–49

E

Edit descriptors

See LRM

END branch specifier, 6–29, 6–36, 7–1, 7–5

See also LRM

ENDFILE statement, 6–4, 6–35

See also LRM

Endian big and little types, 9–2

END statement, 3–13 effect on program execution, 3–11 when not to use, 3–12

Entry point main, 3–10 output listing information, 2–112

ENTRY statement

See LRM

EOR branch specifier, 6–36, 7–5

See also LRM

Equivalenced structures in data-flow and split lifetime analysis,

5–49

EQUIVALENCE statement

See also LRM; Program section and data alignment, 5–18

EQUIVALENCE statement (cont’d) and implied-DO loop collapsing, 5–37 causing data spanning natural boundaries, 5–19 causing unaligned data, 5–19, 5–26 preventing implied-DO loop collapsing,

5–37 preventing optimizations, 5–49

ERR branch specifier, 6–29, 7–1, 7–5

See also LRM example, 7–7

Error handling

See also END; EOR; ERR; IOSTAT;

Run-time messages arithmetic exception handling, 2–44,

2–58 condition handlers, 7–4, 14–1 to 14–27 list of run-time errors (numeric order),

7–8 to 7–14 obtaining secondary status codes, 7–5 processing performed by HP Fortran RTL,

7–2 to 7–14 run-time error explanations, C–5 to C–24 user controls in I/O statements, 6–23,

6–29, 7–4, 7–6

See also LRM

END, EOR, ERR, and IOSTAT specifiers, 6–29, 7–1

Error-related command qualifiers

FORTRAN, LINK, RUN (DCL) summary, 3–13

Errors

See also Error handling; Messages;

Condition-handler routines compiler, 2–102

See also Messages effect on linker, 3–10

/ERROR_LIMIT qualifier, 2–52 fatal, C–4 format, C–1 severity, C–2 source messages, C–2 linker, 3–10 operating system, xxvii, 7–5

Index–17

Errors (cont’d) run-time system, 7–1 to 7–14, C–5 to

C–24 format, 7–3 handling, 7–4 requesting precise reporting, 2–86 requesting traceback information

(FORTRAN), 2–49 requesting traceback information

(LINK), 3–7 severity, 7–3 symbols, 7–6 using debugger to locate, 4–1

/ERROR_LIMIT qualifier, 2–52

ERRSNS (compatibility) example use, F–12, F–16 obtaining secondary status codes, 7–5

Escape sequences, B–11

Event handling

See Condition-handler routines

Exceptional IEEE floating-point values,

2–43, 8–19

Exception condition

See also Condition-handler routines; Error handling common when using indexed files, 12–4 to 12–10 definition, 14–1

Exception handling

See Arithmetic exception handling

/EXECUTABLE option (LINK), 3–3, 3–4

Executable programs

See also Program creating, 1–6, 3–1 effect of optimization level on size, 5–40 naming, 3–4 running, 3–10

Execution interrupting execution of program, 3–11 to 3–12 example of handling Ctrl/C, 10–43,

F–3

EXE file type, 3–2

EXIT command (DCL), 3–11

EXIT system subroutine, 3–12

Expanded String Area (ESA)

RMS control structure, 11–24, 11–25

Explicit interface

See also LRM and array descriptors, 10–10 calling non-Fortran subprograms, 10–3 passing arrays, 10–7, 10–8, 10–10 passing pointers, 10–9, 10–10, 10–59 procedure interface block, 10–5 types of subprograms, 10–3 when calling C subprograms, 10–10

Expressions

See also LRM parentheses in maximum allowed, 2–102

Extended Attributes Block (XAB) general description of use, 11–13 to 11–15 initialized after open, 11–25 kinds of XABs listing of, 11–13

EXTENDSIZE specifier, 6–24

/EXTEND_SOURCE qualifier, 2–53

Extensions

See also LRM compatibility with Compaq Fortran 77,

B–6

External names case-sensitivity, 10–15 cDEC$ ALIAS directive, 10–15, 10–50 controlling with cDEC$ directives, 10–15,

10–16 in C, 10–50 passed between C and HP Fortran,

10–15, 10–16, 10–50 specifying alias names, 10–15

External procedures name passing rule, 10–50 references and optimization, 5–49

EXTERNAL statement, 10–4

See also LRM for C language functions, 10–50

Index–18

EXTERNAL statement (cont’d) qualifier controlling compatibility

(/NOF77), 2–53 when to use for FOR$RAB function, 11–9

F

/F77 qualifier, 2–53

F90 command

See FORTRAN command

F90 file type, 2–3

FAB

See File Access Block (FAB)

$FABDEF library module in FORSYSDEF, 11–6

/FAST qualifier, 2–53 effect on

/ALIGNMENT=COMMONS=keyword,

2–31, 5–26

FDML

See Data Manipulation Language (DML)

Feedback on documentation sending comments to HP, xxvii

F file type, 2–3

Field descriptors

See LRM

Fields in common blocks causes of misalignment, 5–18 controlling alignment, 5–18, 5–26 in derived-type data and record structures causes of misalignment, 5–18 controlling alignment, 5–18, 5–22,

5–26

File access, remote, 13–13 to 13–14

File Access Block (FAB) fields for use by USEROPEN, 11–25 to

11–29 general description, 11–6 to 11–8 symbol naming conventions, 11–6 to 11–8

File format

See also Record type; File organization;

Formatted data; Unformatted files

File handling, 6–4, 6–15 to 6–28 examples of, F–16 to F–17

File header characteristics control block for

XABFHC (RMS), 11–13

File name

See also File specifications application of defaults, 6–19 to 6–22 compiler defaults, 6–18

I/O statements default use, 6–16 to 6–20 in I/O statements, 6–15 to 6–22

OPEN statement specifiers, 6–19, 6–23 using logical names to specify, 6–15

File organization, 6–7

See also Sequential files; Relative files available record types, 6–10 available storage media, 6–8 default, 6–7

I/O statement limitations, 6–5

I/O statements for, 6–5 obtaining, 6–8

INQUIRE statement, 6–25 overview, 6–7 to 6–9 stored in file header, 6–8

Files assigning to logical units default names, 6–15, 6–17 to 6–19 preconnected, 6–15, 6–16 summary of methods, 6–15 to 6–16 using logical name, 6–15, 6–18, 6–19 using OPEN statement, 6–15, 6–19 to 6–25 closing, 6–28 using RMS, 11–19 compiler source checking only (no object file) (FORTRAN), 2–15 compiler source listing (FORTRAN), 2–15 compiling multiple input files

(FORTRAN), 2–16 controlling include file searching, 2–60 created by FORTRAN command, 2–14 created by LINK command, 3–4, 3–6 external, definition, 6–3 input to FORTRAN command, 2–3 input to LINK command, 3–7

Index–19

Files (cont’d) inquiry, 6–25 to 6–28 internal, 6–9 naming object file (FORTRAN), 2–15 opening, 6–2 to 6–3, 6–15 to 6–25 using RMS, 11–18 organization and characteristics, 6–7 preconnected, 6–16

Compaq Fortran 77 differences, B–10 relative organization, 6–8

RMS journaling, 6–39

RMS services list of, 11–21 scratch, 6–10 sequential organization, 6–8 specifying file specification, 6–19 example program, 7–7

File sharing, 6–32 to 6–34 accessing remote files, 13–13 to 13–14

OPEN statement, SHARED specifier,

6–32

RMS file-sharing capability, 6–32 to 6–34 example, F–12 to F–14 shareable image libraries, 13–5

File specifications defining logical names for, 6–16 to 6–17 general DCL rules (FORTRAN command),

2–3

OPEN statement specifiers, 6–19 to 6–22 use in INQUIRE statement, 6–25 use in OPEN statements, 6–15, 6–19 to

6–22

FILE specifier, 6–15, 6–23

See also LRM example, 7–7

File type

EXE, 3–2 executable program, 3–2

F, 2–3

F90, 2–3

F90$MOD, 2–5

FOR, 2–3 for listing files, 2–15 for module files, 2–5 for object files, 2–14

File type (cont’d)

LIS, 2–15

OBJ, 2–14

OLB, 3–7

OPT, 3–9 recognized by compiler, 2–3

STB, 3–9

TLB, 2–63

%FILL example use, F–6

FIND statement, 6–5

See also LRM

Fixed-length records, 6–11 data transferred by I/O statements, 6–37 use for optimal performance, 5–36

FLOAT function example use, 10–27

Floating-point data types accuracy-sensitive optimization, 2–36

Alpha IEEE X_float, 8–15 arithmetic exception handling, 2–44,

2–58 array out-of-bounds checking, 2–42 comparison of VAX and Alpha types,

B–24 constants request double precision, 2–38 controlling size of

COMPLEX declarations, 2–76

DOUBLE PRECISION declarations,

2–51

REAL declarations, 2–76 controlling type in unformatted files,

2–45 conversion, 9–3 to 9–15 limitations, 9–3 converting H_float data, B–25

CRAY big endian formats, 9–5

CVT$CONVERT_FLOAT RTL routine,

B–25 declarations and qualifiers, 8–10 declaring, 8–10

See also LRM denormal values, 8–20

Index–20

Floating-point data types (cont’d) differences between Compaq Fortran 77 for OpenVMS VAX Systems and HP

Fortran, B–24 digits of precision, 8–11 to 8–15

D_float differences between VAX and Alpha systems, 2–55 endian (big and little), 9–2 endian order of native formats, 8–1 exceptional values, 2–58, 8–19 to 8–23 formats used in memory, 2–54 handling of certain exponentiation expressions, 2–44 handling of minus zero (IEEE), 2–39 handling of single-precision constants,

2–38

IBM big endian formats, 9–5

IEEE big endian formats (conversion), 9–5 controlling exceptions (/IEEE_MODE),

2–58 denormalized values, 8–20 native little endian formats, 8–1 reporting exceptional values, 2–43 rounding modes, 2–79 selecting memory format (/FLOAT),

2–54

S_float, 8–9, 9–6

T_float, 8–9, 9–6

X_float, 8–9, 9–6 infinity, 8–20 in memory and on disk, 9–1 math library used, 2–53, 2–65 methods of specifying nonnative formats,

9–7 minus zero use (IEEE), 2–39

NaN values, 8–20 detecting, 8–22 nonnative formats, 9–3 to 9–6 normal and denormalized values of native formats, 8–3 precision, 8–11 to 8–15 qualifiers controlling size of DOUBLE

PRECISION declarations, 2–77

Floating-point data types (cont’d) qualifiers related to accuracy, 2–35, 2–38,

2–42, 2–51, 2–53, 2–65, 2–76, 2–79 qualifiers related to exceptions, 2–44 ranges, 8–3, 8–9 to 8–15 reporting exceptional values, 2–43 reporting exceptions more precisely, 2–86 reporting underflow messages, 2–43,

2–45 representation of native IEEE and VAX formats, 8–9 to 8–18 representation of VAX H_float format,

B–26 representation of zero, 8–20 rounding modes (IEEE), 2–79 selecting memory format, 2–54 to 2–56 selecting optimal, 2–55 setting default length (/DOUBLE_SIZE),

2–51 setting default length (/REAL_SIZE),

2–76 shared memory granularity, 2–57 underflow run-time checking, 2–42 values for constants, 8–3

VAX D_float format, 9–5, 9–6

VAX F_float format, 9–5, 9–6

VAX little endian formats, B–24 zero values, 8–20

FLOAT intrinsic function

See also LRM qualifier controlling size returned, 2–76

/FLOAT qualifier, 2–54

D_FLOAT keyword, 2–55

G_FLOAT keyword, 2–56

IEEE_FLOAT keyword, 2–56

Flushing data output record buffering, 6–39

FMT specifier, 6–29

See also LRM

FOR$ prefix for condition symbols for run-time errors, 7–8 to 7–11

FOR$CONVERT.ext logical name use with nonnative numeric data, 9–10

Index–21

FOR$CONVERTnnn logical name use with nonnative numeric data, 9–8

FOR$CONVERT_ext logical name, 9–10

FOR$IOS prefix for condition symbols for run-time errors, 7–7, 7–13

FOR$RAB function, 11–8, 11–9

Compaq Fortran 77 for OpenVMS VAX

Systems compatibility, B–5 when to declare EXTERNAL, 11–9

FORALL statement

See also LRM array optimizations, 5–43

$FORDEF library module in FORSYSDEF, 7–13, 14–11

FOR file type, 2–3

$FORIOSDEF library module in FORSYSDEF, 7–7, 7–13

Format descriptors

See LRM

Format groups nesting limits, 2–102

FORMAT statement

See also LRM and implied-DO loop collapsing, 5–37

Formatted data, 6–6 and DO loop collapsing, 5–43 and variable format expressions, 5–37

Compaq Fortran 77 differences, B–10 effect on run-time performance, 5–34

I/O statements for, 6–7

Formatted I/O statements, 6–5

See also LRM

Compaq Fortran 77 differences, B–10 controlling format mismatch handling,

2–43 controlling format truncation handling,

2–44

FORM specifier, 6–5 to 6–7, 6–14, 6–23

See also LRM

FORnnn logical name, 6–16, 6–18

FORSYSDEF

$CHFDEF library module, 14–11, 14–13 condition symbol values, 7–13

FORSYSDEF (cont’d) example of including a module, 7–7

$FABDEF library module, 11–6

$FORDEF library module, 7–13, 14–11

$FORIOSDEF library module, 7–7, 7–13

$LIBDEF library module, 14–11 library search order, 2–9, 2–13 list of library modules, E–1 to E–10

$MTHDEF library module, 14–12

$NAMDEF library module, 11–12 overview of library module contents,

10–30

$RABDEF library module, 11–8

$SSDEF library module, 14–12 symbol naming conventions

PARAMETER declarations, 11–4 to

11–5 use with RMS services, 11–3, 11–4 to

11–5

FORT$LIBRARY, 2–12 to 2–13

Fortran

HP Fortran implementation of

PSECT use and attributes, 13–1 to

13–3

FORTRAN-66

See FORTRAN IV

Fortran 90

Standard, 1–1 and RECL units for unformatted files,

9–15 checking (/STANDARD), 2–84

Fortran 90/95

See also FORTRAN command;

Compatibility; LRM condition symbols

See FORSYSDEF logical names

See Logical names reusing source file code, 1–5 source file contents, 1–4 source form file type, 1–4

Standard

See also LRM

Index–22

Fortran 90/95

Standard (cont’d)

/ASSUME=DUMMY_ALIASES qualifier, 2–38, 5–61 statements

See LRM; appropriate statement name

Fortran 95

Standard, 1–1 and RECL units for unformatted files,

9–15 checking (/STANDARD), 2–84

FORTRAN command, 2–2 to 2–92

See also Compiler options abbreviating qualifier names and keywords, 2–18 alignment qualifiers, 5–26 and other software components, 1–8 to

1–12

C language main program example, 10–49 command qualifiers for efficient run-time performance, 5–3 comma or plus signs between file names,

2–4 consistent use of qualifiers for multiple compilations, 2–5 controlling arithmetic exception handling,

2–58 controlling arithmetic exception reporting,

2–42, 2–86 creating module files, 2–5

CXML library for efficient run-time performance, 5–2 debugging qualifiers, 2–49 directories searched for module and include files, 2–7 to 2–13, 2–60 directories searched for text library files,

2–9 effect of compiler directives on qualifiers,

2–18, 2–31 effect of file type on source form, 2–3 effect of OPTIONS statement on qualifiers, 2–18 examples

FORTRAN command examples (cont’d) application with modules, 1–8 compiling multiple files, 5–3 for debugging, 1–10 module subprogram, 1–8 multiple source files, 2–16, 5–3 naming object files, 2–15 preventing object file creation, 2–15 requesting additional checking, 2–17 requesting additional optimizations,

2–17 requesting Fortran Standard conformance checking, 2–17 request listing file, 2–15 single file, 1–5 source checking only, 2–15 using module files, 1–8, 2–7 file type search order, 2–3 for efficient run-time performance, 5–3 format of, 2–2 for translated shared images, B–24 functional groups of qualifiers, 2–24 multiple source files effect on optimizations, 5–3 one or multiple object files per command line, 2–4, 5–3 specifying directory for module files, 2–6 files, 2–2 to 2–16 include files, 2–7 to 2–13 input files, 2–3 library files, 2–4, 2–9 to 2–13, 2–63 listing, 2–14 listing of include file, 2–8, 2–11, 2–13 multiple keywords for a qualifier,

2–18 object files, 2–14 output files, 2–14 source form, 2–3 summary of qualifiers, 2–18 to 2–27 using include files, 2–7 module files, 2–6, 2–62 multiple FORTRAN commands, 2–4

Index–23

Fortran Data Manipulation Language

See Data Manipulation Language (DML)

FORTRAN IV

/F77 qualifier (FORTRAN), 2–53

FPSR (floating-point status register), 2–43

/FULL qualifier (LINK), 3–3, 3–6

Functions

See also LRM; Intrinsic procedures

C language invoking, 10–50 declaration statements, 10–2

%DESCR, %LOC, %REF, and %VAL,

10–11 example

C language, 10–55, 10–59, 10–62 declaration, 1–8 interface block in module, 1–7 with module, 1–6 with system service, 10–43 explicit interface, 10–3 output listing information, 2–113 return values, 10–6, 10–23 changing default passing mechanisms,

10–11 passing rules, 10–6, 10–7 passing with HP Fortran, 10–6 with C, 10–51 with Compaq Fortran 77, 10–46 setting return values, 10–2 using function reference to call system services, 10–30

FUNCTION statement, 10–2

See also LRM

F_float data

See Floating-point data types

G

General directives

See LRM

General-purpose register

See Register usage

Global pagefile section example use, F–8 to F–11

GOTO statement

See also LRM computed or assigned maximum labels allowed, 2–102

Granularity and unaligned data, 2–57 importance of VOLATILE declarations,

2–57 qualifier controlling warning messages,

2–91 shared memory access, 2–57

/GRANULARITY qualifier, 2–57

BYTE keyword, 2–57

LONGWORD keyword, 2–57

QUADWORD keyword, 2–57

G_float data

See Floating-point data types

/G_FLOATING qualifier (obsolete), 2–56

H

Help (DEBUG)

HELP command, 4–18

Help (online)

FORTRAN command qualifiers, xxvi, 1–2

HP Fortran language, xxvi

HP Fortran release notes, xxv

HP Fortran run-time messages, xxvi,

7–14 operating system messages, xxvii

HELP command for FORTRAN command, 1–2

Help libraries displaying linker message explanations,

C–1 displaying run-time message explanations,

C–6 obtaining text from example of, F–19 to F–20

Hollerith constants

See also LRM maximum size, 2–102 representation, 8–24

Index–24

HP Fortran array temporary creation, 5–32 condition symbols for run-time errors, 7–8 to 7–14 for OpenVMS systems compatibility, B–1 extensions not supported, B–1 logical names defaults and use, 6–18 to 6–19

FOR$ACCEPT, FOR$READ,

FOR$PRINT, FOR$TYPE, 6–18 summary of, D–1 to D–3 logical unit numbers, 6–17 to 6–19 online help, xxvi, 7–14 online language help, xxvi online release notes, xxv sample main and subprogram, 1–5, 1–6 software patch kits, xxvii statements coding restrictions and limits summary, 2–101 version number obtaining from command line, 2–87 obtaining from listing file, 2–64 obtaining from object file, 1–11

Web page, xxvii

I

I/O

See also Files; Record I/O; I/O statements advancing and nonadvancing, 6–36 block mode I/O example of using RMS, 11–31 to

11–37 choosing optimal record type, 5–36 closing files, 6–28

Compaq Fortran 77 and HP Fortran compatibility, 10–49 converting unformatted files, 9–2 to 9–15 data formats for unformatted files, 9–2 to

9–6 device and buffer use for efficient run-time performance, 5–35 eliminating bottlenecks, 5–33

I/O (cont’d) file operations, 6–16 files and file characteristics, 6–7 flushing data, 6–39 guidelines for efficient run-time performance, 5–33 to 5–37 logical units, 6–2 to 6–3 obtaining file information, 6–25 output record buffering, 6–39 performance, 5–35 preconnected files, 6–16

Compaq Fortran 77 differences, B–10 reading data using RMS, 11–20 record access, 6–30 buffer use, 5–35, 6–39 deleting records from a file

(DELETE), 12–4 for internal files, 6–9 general description, 6–37 indexed file record pointers (current and next), 12–4 operations, 6–29 record operations on indexed files,

12–4 to 12–8 specifiers, 6–29 specifying initial position, 6–35 transfer, 6–37 record-processing RMS services list of, 11–21 record types, 6–10 comparison with Compaq Fortran 77,

6–11 portability considerations, 6–11 specifying files, 6–19 specifying record length for efficiency,

5–36 summary of statements, 6–3 synchronous accessing devices using SYS$QIOW,

F–6 to F–8 writing data using RMS, 11–19 to 11–20

I/O statements

See also LRM advancing and nonadvancing I/O, 6–36

Index–25

I/O statements (cont’d) auxiliary, 6–5 available for sequential and direct access,

6–7

CLOSE statement, 6–28 default devices, 6–3, 6–17 file connection, 6–4 file operations, 6–16 for indexed files, 6–5 forms of, 6–5 for relative files, 6–5 for sequential files, 6–5

HP Fortran extensions, 6–4 implicit logical I/O unit, 6–16

INQUIRE statement, 6–25 list of, 6–3

OPEN statement

See also OPEN statement

CONVERT specifier, 9–4

OPEN statement interdependencies file specification, 6–19 to 6–22 preconnected units, 6–3, 6–17 record access modes, 6–30 to 6–32 input, 6–4 operations, 6–29 output, 6–4 position, 6–4 transfer, 6–37 with formatted, unformatted, list-directed, and namelist records, 6–7

/I4 qualifier (obsolete), 2–62

I64 and Alpha differences, A–1 to A–13

IEEE

See also Floating-point data types controlling exceptions (/IEEE_MODE),

2–58 exceptional floating-point numbers, 2–43,

8–21 exception handling, 2–58 floating-point data exceptional values, 8–19 to 8–23 native, 8–2, 8–9 to 8–17 nonnative big endian, 9–3, 9–5 representation of zero, 8–20

IEEE (cont’d) nonnative big endian data, 9–3, 9–5 reporting exceptional values, 2–43 rounding modes floating-point calculations, 2–79 selecting memory floating-point format

(/FLOAT), 2–54

S_float data, 8–10, 8–11 ranges, 8–3

T_float data, 8–10, 8–13 ranges, 8–3

X_float data, 8–10 ranges, 8–3

IEEE, Alpha

X_float data, 8–15

/IEEE_MODE qualifier, 2–58 to 2–60

DENORM_RESULTS keyword, 2–59

FAST keyword, 2–59

UNDERFLOW_TO_ZERO keyword, 2–59

IF statement

See LRM

Image files creating, 3–1

Image termination, 3–11

Implicit interface types of subprograms, 10–3

IMPLICIT NONE statement

See also LRM and /WARNINGS=DECLARATIONS qualifier, 2–90

Implied-DO loop and I/O performance, 5–34 collapsing, 5–36, 5–42

INCLUDE files directory search order, 2–9 including in output listing

/SHOW qualifier, 2–83 locating, 2–7 locating in source libraries, 2–9 specifying directory, 2–8

/INCLUDE qualifier, 2–60

/INCLUDE qualifier (LINK), 3–3, 3–7

INCLUDE statement

See also LRM and modules, 10–4

Index–26

INCLUDE statement (cont’d) file nesting limit, 2–102 forms for include files, 2–8 forms for text library modules, 2–9 library modules in text library, 2–93 specifying directories to search, 2–8 to

2–13 text file library search, 2–11 using on OpenVMS systems, 2–7

Indexed sequential (keyed) access, 12–2

Indexed sequential files, 6–9

See also Keyed access mode creating, 12–2 to 12–4 deleting records, 12–4 exception conditions, 12–4 to 12–10 keyed access, 12–2 reading operations, 12–6 to 12–7 record access, 12–2 record access modes for, 6–30, 12–1 record pointers next and last, 12–4 record types for, 6–10

RMS pointers, 12–8 sequential access, 12–2 specifying, 6–7 specifying RECL when creating, 6–9 updating records, 12–4 writing operations, 12–4 to 12–6

Infinity values representation in Alpha floating-point data, 8–20

Initialization debugger, 4–5

INITIALSIZE specifier, 6–24

Inline expansion, 5–52 of statement functions and intrinsics,

5–42 subprograms, 2–71, 5–39, 5–52, 5–57

INQUIRE statement, 6–4, 6–8, 6–25 to 6–28

See also LRM by file name, 6–26 by output item list, 6–27 by unit number, 6–26

Compaq Fortran 77 differences, B–11 default values returned, 6–26

INQUIRE statement (cont’d)

OPENED specifier, 6–26

RECL specifier qualifier to specify units, 2–37 to an opened file, 9–13

INSTALL command (VMS) use to install shareable images, 13–4,

13–5

Installed common areas creation, installation, and use, 13–5 to

13–9 synchronizing access, 13–9 to 13–10

Integer data type array out-of-bounds checking, 2–42 declarations and qualifiers, 8–5 declaring, 8–5

See also LRM endian order of native formats, 8–1 methods of specifying the format, 9–7 nonnative formats, 9–3 to 9–6 overflow run-time checking, 2–42 ranges, 8–2, 8–6 to 8–7 representation, 8–6 to 8–7 setting default length, 2–62

/INTEGER_SIZE qualifier, 2–62

Interactive program execution continuing, 3–11 interrupting, 3–11 to 3–12

Interface block, 10–2

See also LRM components of, 10–5 declaration statements, 10–2 example, 1–7 for explicit procedure interface, 10–4

INTERFACE statement, 1–7, 10–2, 10–5

See also LRM

Internal file

See also LRM

I/O, 6–9 to 6–10

I/O forms and statements, 6–7

Internal subprograms, 10–4

Interoperability with translated images

FORTRAN command, 2–88, B–24

LINK command, 3–3, 3–5, B–24 summary, B–24

Index–27

Interprocess communication, 13–1 to 13–15 mechanisms supporting, 13–1 to 13–15

Interrupt from terminal user

See Ctrl/C; Ctrl/Y

Intrinsic procedures

See also LRM argument passing differences between Compaq Fortran

77 and HP Fortran, B–16

CHAR, B–11 to null-terminate a C string, 10–6

FLOAT, 10–28

FOR$RAB, 11–8, 11–9 for timing program execution, 5–13 inline expansion of, 5–42

ISNAN, 8–22

LIB$ESTABLISH, 14–6

LIB$REVERT, 14–6 qualifier controlling size returned, 2–51,

2–76 qualifiers controlling DOUBLE

PRECISION size returned, 2–77 requesting faster, less accurate versions,

2–65

RESHAPE, 10–62

SIZEOF, 10–28

SQRT, 10–28

SUM, 1–8

UBOUND, 1–8 using array, 5–28 using existing HP Fortran, 5–31

ZEXT, 10–13

IOSTAT specifier, 6–29, 7–1, 7–5, 7–6 to 7–8

See also LRM example, 7–7

ISHFT intrinsic, 5–44

See also LRM

ISNAN intrinsic, 8–22

See also LRM

Item List control block

XABITM (RMS), 11–13

J

Journaling (RMS), 6–39

Journaling control block

XABJNL (RMS), 11–13

K

Key definition control block

XABKEY (RMS), 11–13

Keyed access mode, 6–32

See also Indexed sequential files exception handling, 12–9 to 12–10 general discussion, 12–2 to 12–10 indexed files, 6–9

KEYEQ specifier, 6–29

Key fields primary and alternate definition, 12–2 discussion of use, 12–2, 12–3, 12–4

KEYGE specifier, 6–29

KEYGT specifier, 6–29

KEYID specifier, 6–29

KEYLE specifier, 6–29

KEYLT specifier, 6–29

KEYNXTNE specifier, 6–29

KEYNXT specifier, 6–29

Keys, primary and alternate

See Key fields

KEY specifier, 6–23, 6–29

Keyword options (command line) abbreviating, 2–18 specifying multiple, 2–18

Kind type parameter

See also LRM

COMPLEX declarations, 8–10

INTEGER declarations, 8–5

LOGICAL declarations, 8–7

REAL declarations, 8–10

Index–28

L

Labels

See also LRM in computed or assigned GOTO list maximum allowed, 2–102

Language compatibility

See Compatibility; Language extensions

Language dialects

HP Fortran compatibility information,

B–1 to B–14

Language extensions

See also LRM compatibility with Compaq Fortran 77,

B–6 compatibility with Compaq Fortran 77 on other platforms, B–1

Language features

Compaq Fortran 77 on other platforms

(summary), B–1

Language interface

C and HP Fortran arrays, 10–61 calling subroutines, 10–53 changing default argument passing mechanisms, 10–15, 10–55 changing default mechanisms, 10–16

C language main program, 10–49 complex arguments, 10–56 handling common blocks, 10–63 integer arguments, 10–55 invoking a C function from HP

Fortran, 10–50 invoking an HP Fortran subprogram from C, 10–51 passing arguments between, 10–16 to 10–21, 10–49 to 10–64 using C conventions, 10–18 using FORTRAN command, 10–49 character constant actual arguments,

2–40

Compaq Fortran 77 and HP Fortran alignment qualifiers, 10–48 common block values, 10–48

Language interface

Compaq Fortran 77 and HP Fortran

(cont’d) data types to avoid, 10–44 derived-type data, 10–45 example, 10–46 function values, 10–44

I/O compatibility, 10–49 mechanisms, 10–45 passing arguments, 10–44 to 10–49 passing target or pointer data, 10–47 pointer data, 10–45 similarities, 10–6 differences from Compaq Fortran 77 for

OpenVMS VAX Systems, B–4 to

B–24 external names controlling with cDEC$ directives,

10–15, 10–16

HP Fortran

See also LRM argument passing rules, 10–6 array descriptor format, 10–10 changing default argument passing mechanisms, 10–11, 10–15 default argument passing mechanism,

10–6 explicit interface, 10–3, 10–5 passing arguments, 10–2 to 10–9,

10–16 to 10–21 passing arrays, 10–8 passing character arguments, 10–6 passing pointers, 10–9

OpenVMS calling standard, 10–21 to

10–24 passing character data between HP

Fortran and C, 10–6

Language Sensitive Editor diagnostic file, 2–50

LAPACK routines (Compaq Extended Math

Library), 15–2

LBR$OUTPUT_HELP example use, F–19

Index–29

Length

DOUBLE PRECISION declarations qualifiers controlling size, 2–77 source line length

/WARNINGS=TRUNCATED_

SOURCE qualifier, 2–91 source line length (fixed form)

/EXTEND_SOURCE qualifier, 2–53

Length, record

See Fixed-length records; Variable-length records; Segmented records; Stream records

LEN specifier, 10–7

See also LRM

Lexical tokens per statement maximum, 2–102

LIB$DATE_TIME example use, F–6

LIB$ESTABLISH

Compaq Fortran 77 for OpenVMS VAX

Systems compatibility, B–4 example use, 14–24 to 14–27 general description, 14–6 to 14–7

LIB$FREE_VM example use, 10–27

LIB$GET_INPUT example use, F–19

LIB$GET_VM example use, 10–27

LIB$INIT_TIMER, 5–9 to 5–12 example use, F–18

LIB$MATCH_COND, 14–19 example use, 14–24

LIB$PUT_OUTPUT example use, F–19

LIB$REVERT general description, 14–6 to 14–7

LIB$SHOW_TIMER, 5–9 to 5–12 example use, F–18

LIB$SIGNAL changing to a stop, 14–22 example use, 10–27, F–3, F–12, F–16 general description, 14–7 to 14–9

LIB$SIG_TO_RET, 14–21

LIB$SIG_TO_STOP, 14–22

LIB$STAT_TIMER, 5–9

LIB$STOP continuing execution after LIB$STOP,

14–18 example use, 10–43, 11–18, 14–24, F–6,

F–8 general description, 14–7 to 14–9

LIB$WAIT example use, B–25, F–3

$LIBDEF library module in FORSYSDEF, 14–11

Library

See also Text file libraries creating and maintaining, 1–11

INCLUDE files, 2–9 obtaining information about, 1–11 search order during compilation, 2–9 to 2–13

LIBRARY command, 2–95

/LIBRARY qualifier on FORTRAN command, 2–4, 2–63 on LINK command, 3–3, 3–7

$LINK$ program section use and attributes, 13–2

LINK command creating image map file, 3–6

/DEBUG, 3–13, 3–14

/DEBUG and /TRACEBACK qualifiers,

3–7 errors, 3–10 format, 3–1 for translated shared images, B–24 input file qualifiers, 3–7 messages, 3–10 options file

/OPTIONS qualifier, 3–9 shared common area (installed shareable image), 13–6 shared common area (mapped global section), F–10 output file qualifiers, 3–3 qualifiers and options file use, 3–1 to 3–9 qualifier summary, 3–2

Index–30

LINK command (cont’d) sample use with FORTRAN command,

1–6, 1–8 symbol table qualifier, 3–9

Linker

See also LINK command

FORTRAN option controlling case-sensitive names, 2–67 functions performed by, 3–1 one or multiple modules in object files

(/SEPARATE_COMPILATION), 2–81 options file, 3–9 routines with opposition settings, 5–63

LINPACK benchmark, 5–63

LIS file type, 2–63

List-directed I/O statements, 6–6

See also LRM

Compaq Fortran 77 differences, B–11

Listing file

See also Source code listing contents, 2–103 to 2–116 controlling lines per page, 2–64 example requesting listing file, 2–15,

2–16 requesting, 2–63

/LIST qualifier, 2–14, 2–63 effect of batch mode, 2–14

$LITERAL$ program section use and attributes, 13–2

Local processes sharing and exchanging data, 13–3 to

13–12

%LOC function, 10–13

See also Argument passing

Logical data type

See also LRM converting nonnative data, 9–15 declarations and qualifiers, 8–5 declaring, 8–7 differences with nonnative formats, 9–15 ranges, 8–8 representation, 8–7 setting default length, 2–62 use of all bits, 4–8

Logical I/O units, 6–2

See also System logical names connection method implicitly by system default, 6–17 to

6–19 default Fortran logical unit numbers,

6–17 to 6–19 for preconnected devices, 6–3

INQUIRE statement, 6–25

OPEN statement options, 6–19 to 6–22 summary, 6–15 system unit numbers and names, 6–16 to

6–17

Logical names

See also DEFINE command; DEASSIGN command; Logical I/O units associating with file specifications, 6–16 to 6–17 commands for setting and unsetting, D–1 converting nonnative numeric data, 9–8,

9–10 displaying values of, D–1

FOR$ACCEPT, D–3

FOR$ACCEPT, FOR$READ, FOR$PRINT,

FOR$TYPE, 6–18

FOR$CONVERT.ext, 9–10, D–3

FOR$CONVERTnnn, 9–8, D–3

FOR$CONVERT_ext, 9–10

FOR$PRINT, D–3

FOR$READ, D–3

FOR$TYPE, D–3

FORnnn, 6–16, 6–18, D–3

FORT$INCLUDE, D–2

FORT$LIBRARY, D–2 recognized at compile time, D–2 recognized at run time, D–2 setting in LOGIN.COM or setting system-wide, 1–4 used by OPEN statement, 6–19

Loop control variable and implied-DO loop collapsing, 5–37

Loops

See also DO loops; Optimization and register use, 5–47 blocking optimization, 2–70, 2–72

Index–31

Loops (cont’d) controlling number of times unrolled,

5–57 distribution optimization, 2–70, 2–72 efficient coding suggestions, 5–28, 5–34,

5–36, 5–40 fusion optimization, 2–70, 2–72 interchange optimization, 2–70, 2–72 limiting loop unrolling, 5–50 loop transformation optimizations, 5–53 optimizations for, 5–42, 5–48, 5–50 to

5–57 outer loop unrolling optimization, 2–70,

2–72 scalar replacement optimization, 2–70,

2–72 software pipelining optimization, 2–70,

2–73, 5–53, 5–55 transformation optimizations, 2–70, 2–72,

5–54

Loop transformation, 5–53

Lowercase characters option controlling case-sensitive names,

2–67

LRM

The acronym LRM in this index refers to the HP Fortran for OpenVMS

Language Reference Manual

M

Machine code listing

MACRO representation, 2–65 output listing section, 2–105 to 2–111

/MACHINE_CODE qualifier, 2–65

Mailboxes

SYS$CREMBX, 13–10 to 13–12

MAIN option program transfer address, 3–10

Main program statements for, 10–2

MAP file type, 3–6

MAP parameter on LINK command, 3–3, 3–6 to 3–7

/SHOW qualifier (FORTRAN command),

2–83

/MATH_LIBRARY qualifier, 2–65

MAXREC specifier, 6–24

See also LRM

Mechanism array contents and use, 14–15

Memory floating-point formats used (/FLOAT),

2–54 for intermediate storage, 5–35 process limits, 1–2 system virtual memory limits, 1–2 very large (64-bit) access, 10–20

Messages

See also Message severity; Warning messages compiler-fatal diagnostic messages, C–4 issued by compiler general description, 2–102 limiting the number, 2–52 linker messages, 3–10 run-time messages, 7–3 to 7–14, C–5 to

C–24 detecting exceptional values, 2–43 displaying online HELP, 7–14 displaying secondary system errors,

7–5 explanations, C–6 to C–24 list, condition symbol order, C–6 to

C–24 list, numeric order, 7–8 to 7–13 source program diagnostic messages, C–2 to C–4 warning and error

/SEVERITY qualifier, 2–82 warning and informational changing severity to error

(/SEVERITY), 2–82

/STANDARD qualifier, 2–84

/WARNING qualifier, 2–89

Message severity meaning to compiler, C–2 meaning to linker, 3–10 meaning to run-time system, 7–3

Index–32

Minus zero (IEEE) handling, 2–39

Misaligned data

See also Unaligned data; Alignment

Mixed real/complex operation, 5–47

/MODULE qualifier, 2–67

Modules, 10–3

See also LRM accessing module variables in debugger,

4–8, 4–18 compiler use of process open file limit,

1–3 creating with FORTRAN command, 2–5 declaration example, 1–7 example compilation, 1–8

F90$MOD file type, 2–5 files created and used by compiler, 2–5 subprograms, 10–4 to contained subprograms, 10–5 use association, 10–5 use of VOLATILE statement for module variables, 13–4 using with FORTRAN command, 2–5 to

2–7 specifying object file, 2–6

MODULE statement, 1–7, 2–5, 10–3

See also LRM

$MTHDEF library module in FORSYSDEF, 14–12

N

$NAMDEF library module in FORSYSDEF, 11–12

Name (NAM) block general description of use, 11–11 to 11–13

Name length, symbolic maximum, 2–102

Namelist I/O statements, 6–6

See also LRM

Compaq Fortran 77 differences, B–10

NAME specifier, 6–23

See also LRM

/NAMES qualifier, 2–67

NaN values (IEEE)

See also ISNAN intrinsic

/CHECK qualifier, 2–43 detecting, 2–43, 2–58, 8–22

/IEEE_MODE qualifier, 2–58

ISNAN intrinsic function, 8–22 representation in Alpha floating-point data, 8–20

/NATIVE_ONLY qualifier (LINK), 3–3, 3–5,

B–24

Natural boundaries (alignment)

See also Alignment definition of, 5–17

Natural storage order (arrays), 5–35

Nesting limits source code, 2–102

Networking environments sharing and exchanging data in, 13–13 to

13–15

NML specifier, 6–29

See also LRM

Nodes file specification default, 6–20

/NOG_FLOATING qualifier (obsolete), 2–55

/NOI4 qualifier (obsolete), 2–62

Nonadvancing I/O, 6–36

/NOOPTIMIZE qualifier effect on debugging, 4–3

NOSPANBLOCKS specifier, 6–23

Null-terminating string

CHAR intrinsic procedure, 10–6

Numerical data output of, 5–34

Numeric range

See Data type

O

Object code listing

See Machine code listing

Object files

See also Compilation options

Index–33

Object files (cont’d) effect of /SEPARATE_COMPILATION qualifier, 2–81 effect of optimization level on size, 5–40,

5–42, 5–57 naming

/OBJECT qualifier, 2–68 obtaining information about, 1–11 one or multiple modules in

/SEPARATE_COMPILATION qualifier, 2–81 prevent creation of, 2–68 with module files when needed on FORTRAN command line, 2–6

/OBJECT qualifier, 2–14, 2–68

OBJ file type, 2–14, 2–68

OLB file type, 3–7

/OLD_F77 qualifier, 2–68

OPENED specifier, 6–26

See also LRM

Open file limit increasing number per process, 1–3

Open operations opening a file using RMS, 11–18 to 11–19 user-written

See USEROPEN routines

OPEN statement, 6–4

See also LRM access mode, 6–30

ACCESS specifier, 6–24, 6–30

ACTION specifier, 6–24

APPEND specifier, 6–35

ASSOCIATEVARIABLE specifier, 6–24

BLANK specifier, 6–24

BLOCKSIZE specifier, 5–35, 6–24

BUFFERCOUNT specifier, 5–35, 6–24

CARRIAGECONTROL specifier, 6–23

CONVERT specifier, 6–24, 9–4, 9–13

DEFAULTFILE specifier, 6–15, 6–19,

6–21, 6–23 defaults

See LRM converting nonnative data, 9–15 units for preconnected files, 6–17

OPEN statement (cont’d)

DELIM specifier, 6–24 directory and file name defaults, 6–19 to

6–22

DISPOSE specifier, 6–23, 6–25 effect of opening previously open file,

6–22 error handling example, 7–7

ERR specifier, 6–24 example, 7–7

EXTENDSIZE specifier, 6–24 file organization, 6–8 file-sharing parameters, 6–32 to 6–33

FILE specifier, 6–15, 6–19, 6–23 example, 7–7 file status, 6–23

FORM specifier, 6–5 to 6–7, 6–23

I/O statement interdependencies, 6–3,

6–20 file specification, 6–22 implied and explicit file open, 6–2 importance of examining defaults, 6–23

INITIALSIZE specifier, 6–24

IOSTAT specifier, 6–25 example, 7–7

KEY specifier, 6–23

MAXREC specifier, 6–24

NAME specifier, 6–23

NOSPANBLOCKS specifier, 6–23

ORGANIZATION specifier, 6–8, 6–23

PAD specifier, 6–24, 6–37

POSITION specifier, 6–24, 6–35 qualifier controlling BLANK specifier default (/NOF77), 2–53 qualifier controlling STATUS specifier default (/NOF77), 2–53

READONLY specifier, 6–24

RECL specifier, 6–8, 6–23 and record data transfer, 6–37, 6–38 for fixed-length records, 6–11 for variable-length records, 6–12 obtaining value for unformatted files,

6–27 qualifier to specify units, 2–37 units, 6–14, 9–15

Index–34

OPEN statement (cont’d)

RECORDSIZE specifier, 6–23

RECORDTYPE specifier, 6–23

SHARED specifier, 6–24, 6–32 specifiers for efficient I/O, 5–35 specifiers identifying error handling capabilities, 6–24 file access and position, 6–24 file allocation, 6–24 file and record characteristics, 6–23 file and unit, 6–23 file close action, 6–25 record transfer characteristics, 6–24 specifying file specification, 6–19

STATUS specifier, 6–10, 6–21, 6–23 summary of specifiers, 6–22

TYPE specifier, 6–23

UNIT specifier, 6–2 to 6–3, 6–15, 6–21,

6–23

USEROPEN specifier, 6–24 use with USEROPEN routines, 11–2 using preconnected files, 6–16

OpenVMS calling standard, 10–21 to 10–24 argument lists, 10–24 argument-passing mechanisms, 10–11 general calling considerations, 10–26

OpenVMS data types, 10–32 register and stack usage, 10–21

OpenVMS Debugger

See Debugger

OpenVMS library routines

See RTL; LIB$name

OpenVMS RMS

See RMS

OpenVMS system services

See SYS$name; System services

OpenVMS Web site, xxvii

Operations mixed real/complex, 5–47

Operators

See also LRM arithmetic for efficient run-time performance,

5–39

OPT file type, 3–9

Optimization, 5–40 to 5–63 additional global, 5–50 and performance measurement, 5–46 automatic inlining, 5–52 code hoisting, 5–48 code replication to eliminate branches,

5–51 common subexpression elimination, 5–43 compiler option summary, 5–4 compile-time operations, 5–44 compiling multiple files for efficient run-time performance, 5–3 constant pooling, 5–42 controlling procedure inlining, 5–57 data-flow and split lifetime analysis,

5–48 dead code, 5–42 dead store elimination (unused variables),

5–45 effect on compilation time, 5–40 debugging, 2–50 object file size, 5–40 output file size, 2–68 program execution, 2–68 for specific Alpha processor generation,

2–74, 5–58 global, 5–48 implied DO loop collapsing, 5–36, 5–42 inline expansion, 5–42 inlining procedures, 2–71, 5–52 instruction scheduling, 5–50, 5–51, 5–53,

5–55 interprocedure analysis, 5–52 level, 2–69 limiting loop unrolling, 5–57 local, 5–43 loop blocking, 2–70, 2–72 loop distribution, 2–70, 2–72 loop fusion, 2–70, 2–72 loop interchange, 2–70, 2–72 loop outer loop unrolling, 2–70, 2–72 loops, 2–70, 2–73 loop scalar replacement, 2–70, 2–72

Index–35

Optimization (cont’d) loop transformation, 2–70, 2–72, 5–53,

5–54 loop unrolling, 5–50 mixed real/complex operations, 5–47 multiplication and division expansion,

5–44 of loops, 5–50 to 5–57 of statement functions and intrinsics,

5–42

/OPTIMIZE=INLINE=keyword, 5–57

/OPTIMIZE=TUNE=keyword, 5–58

/OPTIMIZE=UNROLL=n, 5–50

/OPTIMIZE qualifier, 2–68 to 2–75

INLINE=keyword, 2–71

LEVEL=n, 2–69

LOOPS, 2–72

PIPELINE, 2–73

TUNE=keyword, 2–74

UNROLL=n, 2–75 overview of levels, 5–40 qualifiers for, 2–68, 5–40 summary, 5–3 register use, 5–46 removal optimizations, 5–45 reordering floating-point operations, 5–60 software pipelining, 2–70, 2–73, 5–53,

5–55 source code guidelines for (check list),

5–17 to 5–40 summary of /OPTIMIZE=LEVEL=n, 5–40 to reduce program size (space optimizations), 5–42 using dummy aliases, 5–61 value propagation, 5–45

Optimization techniques, user adjustments to process working set, F–18 to F–19

/OPTIMIZE qualifier, 2–68 to 2–75

INLINE=keyword, 2–71, 5–57

LEVEL=n, 2–69, 5–40 to 5–42

LOOPS, 2–72

NOINLINE, 2–72

PIPELINE, 2–73

TUNE=keyword, 5–58

/OPTIMIZE qualifier (cont’d)

TUNE=keyword (Alpha only), 2–74

UNROLL=n, 2–75, 5–50, 5–57

OPTIONS (MAIN) as program transfer address, 3–10

/OPTIONS qualifier (LINK), 3–3, 3–9

OPTIONS statement

See also LRM specifying unformatted file floating-point format, 9–14 use, 2–18

Order of subscript progression in I/O, 5–35

ORGANIZATION specifier, 6–8, 6–23

See also LRM

Output, screen formatting example, F–14 to F–16

Output listing, 2–102 to 2–116

See also Compilation options compilation summary section, 2–114 lines per page, 2–64 machine code section, 2–105 to 2–111 storage map section, 2–112 to 2–114

Overflow

See also Arithmetic exception handling array bounds, 2–42 floating-point, 2–42 integer, 2–42, 14–24

P

PAD specifier, 6–24, 6–37

See also LRM

/PAD_SOURCE qualifier, 2–76

Page fault and temporary storage, 5–35

PARAMETER statement

See also LRM compiler option for alternate

PARAMETER syntax, 2–37

Parentheses in expressions maximum allowed, 2–102

Passed-length character arguments

See also LRM

Index–36

PCA

See Performance and Coverage Analyzer

(PCA)

Performance

/ALIGNMENT qualifier, 2–27 arithmetic operators and run-time performance, 5–39 array use efficiency, 5–28, 5–34

/ASSUME=DUMMY_ALIASES qualifier,

2–38, 5–61

/ASSUME=NOACCURACY_SENSITIVE qualifier, 2–36, 5–60

/ASSUME qualifier, 2–35 checking for unaligned data, 4–27, 5–21 process limits, 1–3, 5–7 choosing optimal record type, 5–36 compilation, 1–3, 5–7 compilation times and optimization levels,

5–40 controlling procedure inlining, 5–57 data alignment efficiency, 2–27, 5–17 to

5–26 data types and run-time performance,

5–38

DO loop coding and run-time performance,

5–40 effect of formatted files on run-time performance, 5–34 equivalence and run-time performance,

5–39 internal subprograms and run-time performance, 5–39 limiting loop unrolling, 5–57 measuring, 5–8 to 5–17

HP Fortran intrinsic procedures,

5–13

LIB$xxxx_TIMER routines, 5–9 optimized programs, 5–46

Performance and Coverage Analyzer,

5–16 using command procedures, 5–13 mixed data type operations and run-time performance, 5–38

Performance (cont’d)

OPEN statement specifiers for efficient

I/O, 5–35 to 5–36 optimization for Alpha processor generation, 2–74, 5–58 optimization levels, 5–40 to 5–53

/OPTIMIZE qualifier, 2–68 profiling code, 5–16 qualifiers controlling code generation

(/ARCHITECTURE), 2–33 controlling optimizations, 2–68, 5–4 data alignment efficiency, 2–27 dummy alias assumption, 2–38 floating-point calculations, 2–36 for run-time efficiency, 5–3 math library use, 2–65 selecting floating-point data types,

2–55 summary, 2–26 that improve performance, 5–4 that slow performance, 5–6 realistic measurements, 5–46 record I/O buffers, 5–35, 6–39 redirecting scrolled output and run-time performance, 5–8 reordering floating-point operations, 5–60 run-time, 5–1 to 5–63, 15–1 to 15–5

I/O efficiency, 5–33 to 5–37 selecting floating-point data types, 2–55 size of INTEGER and LOGICAL data,

2–62 source code guidelines for run-time efficiency, 5–17 to 5–40 statement functions and run-time performance, 5–39 timings, 5–8 to 5–16

Performance and Coverage Analyzer (PCA),

5–16

Pointers

See also LRM

C language, 10–59 effect of explicit interface, 10–9 passed between HP Fortran and C, 10–59 passing as arguments, 10–9

Index–37

Pointers (cont’d) passing between C and HP Fortran,

10–60 use with Compaq Fortran 77, 10–45

Porting information

See Compatibility

POSITION specifier, 6–24, 6–35

See also LRM

Precision floating-point data types, 8–11 to 8–15

Preconnected files

I/O statements, 6–3

OPEN statement, 6–15 to 6–18

PREPROCESSOR parameter (/SHOW),

2–84

Primary key fields (indexed files) definition, 12–2

PRINT statement, 6–4

See also LRM

Procedure-based signal handling

See CHF

Procedure-calling standard (OpenVMS),

10–21 to 10–24

Procedure interface

See also LRM argument passing rules, 10–6 array arguments, 10–8 changing default passing mechanisms,

10–11, 10–15

Compaq Fortran 77 and HP Fortran passing arguments, 10–44 to 10–49 explicit interface, 10–3, 10–4, 10–5

HP Fortran and C, 10–16 to 10–21,

10–49 to 10–64

HP Fortran array descriptor format,

10–10

HP Fortran subprograms, 10–2 to 10–14 implicit interface, 10–3 modules, 10–3, 10–5 pointer arguments, 10–9 procedure interface block, 10–2, 10–5 types of subprograms, 10–4

Procedures

See also LRM analyzing performance, 5–16

Procedures (cont’d) inlining, 2–71, 5–39, 5–42, 5–52, 5–57 compiling multiple files, 5–3 run-time linking, 3–1 types of subprograms, 10–4

Procedure signature block (PSB), 3–5

Process creation and management of, F–21 to

F–24 example of adjusting process memory limits, F–18 to F–19 for large programs, 1–3 interprocess communication example, F–8 to F–11 limits checking, 1–3, 5–7 increasing memory-limiting SYSGEN parameters, 1–2 increasing memory size, 1–3 increasing open file limit, 1–3 sharing and exchanging data, 13–3 to

13–15, F–8 to F–11

Profiling code command procedures, 5–13

LIB$xxxx_TIMER routines, 5–9

PCA, 5–16

Program

See also Executable program compiling, 2–1 compiling (example), 1–6 execution, 3–10 to 3–13 linking (example), 1–8 name default in debugger, 4–8 section, 5–49, 13–1 to 13–3 mapped global pagefile section, F–8 shareable common area, 13–6 size effect of optimization levels, 5–40 limitations, 2–102 process memory size, 1–3 space optimizations, 5–42 threaded execution related qualifiers, 2–78

Index–38

Program (cont’d) transportability

See Compatibility units creating modules for, 10–4

Program counter (PC), 10–22

Program section (PSECT) attributes in listing file, 2–112 changing attributes, 13–2 characteristics, 13–1 to 13–3 compile-time attributes, 13–1 to 13–3 link-time attributes (LINK/MAP), 3–6 mapped global pagefile section, F–8 shareable common area, 13–6

PROGRAM statement, 1–5, 10–2

See also LRM

Program transportability, B–1 to B–14 data, B–24

Prompt debugger (DBG>), 4–5

Protection control block

XABPRO (RMS), 11–13

PSB

See Procedure signature block (PSB)

PSECT

See Program section (PSECT)

Q

QIO services

See also SYS$QIOW example use, F–8

Qualifier names

See also Compiler options abbreviating, 2–18

Quotation mark character

See also LRM

R

RAB

See Record access block

$RABDEF library module in FORSYSDEF, 11–8

Random number generation (Compaq

Extended Math Library), 15–2

RAN function (compatibility), B–13

See also LRM

Ranges for complex constants, 8–4 for integer constants, 8–2 for logical constants, 8–2 for real constants, 8–3

READONLY specifier, 6–24

See also LRM

Read operations

See I/O operations

READ statement, 6–4

See also LRM

ADVANCE specifier, 6–36

Real data types, 2–54, 8–9, 8–11 to 8–15

See also LRM declarations and qualifiers, 8–10 native representation, 8–10 to 8–15 ranges, 8–3, 8–11

VAX representation, 8–12 to 8–14

REAL declarations option to control size of, 2–76

Real exponentiation (/CHECK), 2–44

REAL intrinsic function

See LRM

/REAL_SIZE qualifier, 2–76

RECL specifier, 6–23

See also LRM for fixed-length records, 6–11 for variable-length records, 6–12

INQUIRE statement

/ASSUME=BYTERECL qualifier,

2–37 obtaining value for unformatted files,

6–27

OPEN statement

/ASSUME=BYTERECL qualifier,

2–37 qualifier to specify units, 2–37 units for formatted files, 6–14

Index–39

RECL specifier (cont’d) units for unformatted files, 6–14

Record length

See also RECL specifier

INQUIRE statement, 6–25 locking, 6–32 memory diagrams of, 5–26

Record Access Block (RAB) fields for use by USEROPEN, 11–29 to

11–31 general description of use, 11–8 to 11–11 obtaining address of, 11–9

Record access mode, 6–30 to 6–32 available for file organizations, 6–30 direct, 6–30 to 6–32 direct access to sequential files, 6–11 for indexed sequential files, 12–2 keyed, 6–30 to 6–32 limitations by file organizations and record types, 6–30

OPEN statement specifiers, 6–30 sequential, 6–30 to 6–31

Record arrays

See also Array output listing information, 2–113

Record I/O

See also I/O; LRM

ADVANCE specifier, 6–36 advancing, 6–36 amount of data transferred by I/O statements, 6–37 available I/O statements and forms, 6–7 buffers and disk I/O, 5–35, 6–39, 11–19,

11–20 data transfer, 6–37 deleting records from a file (DELETE),

12–4

END branch specifier, 6–36

EOR branch specifier, 6–36 flushing buffers, 6–39 indexed file record pointers (current and next), 12–4 in internal files, 6–10 length

Record I/O length (cont’d)

See also LRM effect on performance, 5–36 obtaining using INQUIRE

(unformatted), 6–27 nonadvancing, 6–36 performance, 5–35 position, 6–35 record operations on indexed files, 12–4 to 12–8 record types, 6–10

SIZE branch specifier, 6–36 statement specifiers, 6–29

Record length value qualifiers byte record length value assumption,

2–37

Record locking

RMS facility, 6–33 to 6–34

Record Management Services (RMS) data structures constructed by RTL, 11–24 to 11–31

FAB, 11–6 to 11–8 field use by USEROPEN, 11–25 to

11–31 list of, 11–2

NAM, 11–11 to 11–13

RAB, 11–8 to 11–11 steps to using, 11–3 use by USEROPEN, 11–24 to 11–31

XAB, 11–13 to 11–15 error signaling example, F–12 to F–14 example of calling, F–1 to F–3 file sharing capability, 6–32 to 6–34 output record buffering, 6–39 overview of how to use RMS services,

11–15 to 11–21 pointers into indexed files, 12–8 record locking facility, 6–32, 6–33 to 6–34

Records

See also Record type; RECORD statement output listing information, 2–113 record types, 6–11 to 6–14 structured data items

Index–40

Records structured data items (cont’d) data alignment, 2–27

RECORD statement

See also LRM causes of misalignment, 5–18 data alignment, 2–27, 5–26

Record structures

See also LRM accessing variables in debugger, 4–16 alignment of, 5–26 order of data in, 5–25 qualifiers controlling alignment, 2–27,

5–26 storage of, 5–26

Record type, 6–10 to 6–14 available file organizations, 6–11 choosing for optimal run-time performance, 5–36 converting nonnative data

See also LRM

OPEN statement defaults, 9–15 declaring

See also LRM

RECORDTYPE specifier, 6–23 fixed-length, 6–11 obtaining, 6–8

INQUIRE statement, 6–25 portability considerations, 6–11 segmented, 6–12 stored in file header, 6–8 stream, 6–13 stream_CR, 6–13 stream_LF, 6–13 variable-length, 6–12

RECORDTYPE specifier, 6–23

See also LRM

Recovery unit control block

XABRU (RMS), 11–13

REC specifier, 6–29

See also LRM

Recursion

See also LRM qualifier controlling, 2–78

/RECURSIVE qualifier, 2–78

Reentrancy asynchronous

RTL behavior, 2–79

RTL calls qualifier controlling, 2–78 threaded

RTL behavior, 2–79

/REENTRANCY qualifier, 2–78

Reentrant program threaded execution, 2–78

References

See also LRM unresolved (Linker), 3–10

%REF function, 10–14

See also Argument passing

Register usage array index, 5–47 effect of optimization, 5–46 effect of VOLATILE statement, 5–48 holding variables, 5–46 loops that exhaust available registers,

2–71, 2–74, 5–50 on OpenVMS Alpha systems, 10–21

Relational operators

See also LRM

Relative file

See also Direct access mode

See also LRM general description, 6–8 record access modes for, 6–30 record types for, 6–10 specifying, 6–7 specifying RECL when creating, 6–8

Remote file access, 13–13 to 13–14

Remote processes sharing and exchanging data, 13–13 to

13–15

Removal optimizations, 5–45 to 5–46

RESHAPE intrinsic procedure, 10–62

Resultant String Area (RSA)

RMS control structure, 11–24, 11–25

Index–41

Returning completion status values to a command procedure, 3–12

RETURN statement, 3–13 when not to use, 3–12

Return values, function, 10–23

Revision date and time control block

XABRDT (RMS), 11–13

REWIND statement, 6–4, 6–35

See also LRM

REWRITE statement, 6–5

See also LRM

RMS

See Record Management Services (RMS)

$RMSDEF library module, 11–17

Rounding modes

IEEE floating-point calculations, 2–79

/ROUNDING_MODE qualifier, 2–79

RSA

See Resultant string area (RSA)

RTL

See Run-Time Library (RTL)

RUN command (DCL), 3–11, 4–4 continuing, 3–11 effect of /DEBUG, 3–13, 3–14 interrupting, 3–11

Run-time call stack

See Call stack

Run-time checking of argument list, 2–42 of FPSR, 2–43

Run-Time Library (RTL)

See also LIB$name and implied-DO loop collapsing, 5–36,

5–42 error processing performed by, 7–2 to

7–14

Fortran I/O support routines used as result of USEROPEN, 11–2 general calling considerations, 10–26

OpenVMS data types, 10–32 overview of library routines, 10–25 requesting threaded execution, 2–78 using latest version for run-time efficiency, 5–1

Run-time messages description of each, C–5 to C–24 displaying secondary system errors, 7–5 format, 7–3 format mismatches, 2–43 format truncation, 2–44 handling, 7–4 list, number sequence, 7–2 to 7–14 severity levels, 7–3 using online help, 7–14

Run-time procedures linking, 3–1

S

Scratch files, 6–10

See also LRM

SCRATCH specifier, 6–10

See also LRM

Screen management subroutines

See also SMG$name examples, F–14 to F–16

Screen output formatting example, F–14 to F–16

Segmented records, 6–12

/SELECTIVE_SEARCH qualifier (LINK),

3–7

/SEPARATE_COMPILATION qualifier, 2–81

SEQUENCE statement

See also LRM derived-type data order, 5–19, 5–24,

5–27, 10–58

Sequential access, 6–30 to 6–31

Sequential access mode for indexed organization files, 12–1 optimal record types, 5–36

Sequential file

See also LRM general description, 6–8 record access modes for, 6–30 record types for, 6–10 requirements for direct access mode, 6–11 specifying, 6–7

Index–42

/SEVERITY qualifier, 2–82

Shareable image common area (interprocess communication), 13–6 creating, 3–4 debugger commands, 4–21 input to linker, 3–4, 3–7 installing, 13–7 libraries benefits, 13–4 creating and installing, 13–5 general discussion, 13–4 input to linker, 3–4, 3–7 program section (PSECT) attribute, 13–2,

13–6

/SHAREABLE qualifier (LINK), 3–3, 3–4,

3–7

Shared memory access

See also VOLATILE statement granularity, 2–57 installed common areas, 13–5 mapped global pagefile section, F–8 requesting threaded program execution,

2–78

SHARED specifier, 6–24, 6–32

See also LRM

Sharing data

See Data; File sharing; Shared memory access

Sharing files, 6–32 to 6–34

See also File sharing

OPEN statement, 6–32

SHOW LOGICAL command (DCL), D–1 viewing logical names, D–1

/SHOW qualifier, 2–83

ALL keyword, 2–83

INCLUDE keyword, 2–83

MAP keyword, 2–83

NONE keyword, 2–84

Signal array contents and use, 14–14

Signal handling routines

See Condition-handler routines

Signal processing routines (Compaq

Extended Math Library), 15–2

Signals, condition changing to return status

LIB$SIG_TO_RET, 14–21

SIZE branch specifier, 6–36

SIZEOF function example use, 10–27 using

See LRM

SIZE specifier

See LRM

SMG$CREATE_PASTEBOARD example use, F–14

SMG$CREATE_VIRTUAL_DISPLAY example use, F–14

SMG$LABEL_BORDER example use, F–14

SMG$PASTE_VIRTUAL_DISPLAY example use, F–14

SMG$PUT_LINE example use, F–14

SMG routines examples, F–14 to F–16

SNGL intrinsic function

See also LRM qualifier controlling size returned, 2–76

Software pipelining, 5–53, 5–55

Sorting (Compaq Extended Math Library),

15–2

Source code

See also Source lines; Source code listing checking standards conformance of, 2–84 coding restrictions, 2–101 columns

See LRM diagnostic messages, C–2 to C–4

D in column 1 (/D_LINES), 2–49 file type conventions, 2–3 include files, 2–7 include text library modules, 2–9 limits, 2–101 lines pad with spaces, 2–76

Index–43

Source code (cont’d) listing, 2–102 controlling contents of (/MACHINE_

CODE), 2–65 controlling contents of (/SHOW),

2–83 general description, 2–104 to 2–105 requesting (/LIST), 2–63 maximum line length (fixed form), 2–53 module files, 2–5 option controlling case-sensitive names,

2–67 questionable controlling warning message, 2–92 source forms, 2–3

Source Code Analyzer analysis file, 2–31

Source files building using OpenVMS tools, 1–11 creating and revising, 1–6, 1–8 input to compiler, 2–3 to 2–5 managing, 1–11

Source form

See also LRM file types recognized, 1–4, 2–3 fixed-form source compiler options, 2–49,

2–53, 2–76 qualifiers for specifying, 2–84

Source lines coding restrictions, 2–102 continuation character

See LRM controlling in listing file (/SHOW), 2–83 controlling messages in listing file

(/STANDARD), 2–84 controlling truncation messages

(/WARNINGS), 2–91

D in column 1 (/D_LINES), 2–49 extending length (fixed form), 2–53 form-feed effect on listing file, 2–64

Source programs compile options detecting truncated lines, 2–91

/SOURCE_FORM qualifier, 2–84

Sparse linear system routines (Compaq

Extended Math Library), 15–2

Specifier options (Fortran)

See I/O statements; LRM

SQRT function example use, 10–27

SS$_CONTINUE use in condition handlers, 14–18

SS$_RESIGNAL use in condition handlers, 14–18

$SSDEF library module in FORSYSDEF, 14–12

Standard I/O file

I/O statements default use, 6–16

/STANDARD qualifier, 2–84

Standards

ANSI FORTRAN-77 and FORTRAN 66,

1–1

Fortran 90, 1–1 checking (/STANDARD), 2–84

Fortran 95, 1–1 checking (/STANDARD), 2–84

Statement functions

See also LRM efficient run-time performance, 5–39 in data-flow analysis, 5–42 inline expansion of, 5–42 never called controlling warning messages, 2–91

Statement labels

See also LRM; Labels; Source code output listing information, 2–113

Statements continuation character

See LRM maximum line length (fixed form), 2–53 truncation during compilation, 2–91

STATUS specifier, 6–23

See also LRM

Status values, completion returning to a command procedure, 3–12

Index–44

STB file type, 3–9

STOP command (DCL), 3–11

STOP statement, 3–13 effect on program execution, 3–11 when not to use, 3–12

Storage map listing general description, 2–112 to 2–114

Stream (Stream_CRLF) records, 6–13

Stream_CR records, 6–13 to 6–14

Stream_LF records, 6–13 to 6–14 use for optimal performance, 5–36

Structures

See also Derived-types data; Record structures; LRM nesting limit, 2–102

STRUCTURE statement

See also LRM and data alignment, 2–27 causes of misalignment, 5–18

Subprogram

See also LRM; Procedure interface arguments, 10–2, 10–44

See also LRM

C and Fortran, 10–16, 10–49

Compaq Fortran 77 and HP Fortran,

10–44 definition of, 10–2 explicit interface, 10–3 external, 10–4 inlining, 5–39, 5–52, 5–57 compiling multiple files, 5–3 internal (host association), 10–4 module (use association), 10–4 passing arguments and function return values, 10–6, 10–21 procedure interface block, 10–5 requiring a procedure interface block for explicit interface, 10–4 types of, 10–4

Subroutine calls between HP Fortran and C, 10–53 in data-flow and split lifetime analysis,

5–49

Subroutines

See also LRM declaration statements, 10–2 explicit interface, 10–3 output listing information, 2–113

SUBROUTINE statement, 10–2

See also LRM

Substring references checking boundaries

FORTRAN command option, 2–42

SUM intrinsic, 1–8

Summary control block

XABSUM (RMS), 11–13

Summary listing, compilation, 2–114

Symbol records (DEBUG), 4–2

Symbolic names

See also LRM; FORSYSDEF maximum length, 2–102

Symbol map

/SHOW qualifier affect of MAP parameter, 2–83

Symbol table created by compiler, 2–2, 2–49

/DEBUG qualifier, 2–49 created by linker

/DEBUG qualifier, 3–9 overview of creation and use, 3–13 to

3–14

/SYMBOL_TABLE qualifier (LINK), 3–3,

3–9

Synchronizing access system routines for, 13–10

Synchronous I/O accessing devices using SYS$QIOW, F–6 to F–8

/SYNCHRONOUS_EXCEPTIONS qualifier

(Alpha only), 2–86

/SYNTAX_ONLY qualifier, 2–87

SYS$ADJWSL example use, F–18

SYS$ASCEFC example use, F–9

Index–45

SYS$ASSIGN example use, 10–43, F–3, F–8

SYS$CLOSE (RMS), 11–19 data structure needed to use, 11–6

SYS$CONNECT (RMS) data structure needed to use, 11–8 use to open a file, 11–18, 11–19 example of, 11–33

SYS$CREATE (RMS) data structure needed to use, 11–6 use to open a file, 11–18 example of, 11–23, 11–33

SYS$CREMBX, 13–10 to 13–12 example use, 13–11

SYS$CREPRC example use, F–21

SYS$CRMPSC example use, F–8

SYS$DELETE (RMS), 11–21 data structure needed to use, 11–8

SYS$DEQ synchronizing access, 13–10

SYS$DISCONNECT (RMS), 11–19 data structure needed to use, 11–8

SYS$DISPLAY (RMS), 11–21 data structure needed to use, 11–6

SYS$ENQ synchronizing access, 13–10

SYS$ENTER (RMS), 11–21 data structure needed to use, 11–6

SYS$ERASE (RMS), 11–21 data structure needed to use, 11–6

SYS$EXTEND (RMS), 11–21 data structure needed to use, 11–6

SYS$FIND (RMS), 11–21 data structure needed to use, 11–8

SYS$FLUSH (RMS) data structure needed to use, 11–8 output record buffering, 6–39

SYS$FREE (RMS) data structure needed to use, 11–8

SYS$GET (RMS), 11–20 data structure needed to use, 11–8

SYS$GETJPIW example use, 10–41, F–21

SYS$HIBER example use, F–21 synchronizing access, 13–10

SYS$IEEE_SET_ROUNDING_MODE routine, 2–80

SYS$INPUT default logical unit number, 6–3, 6–17

SYS$LIBRARY, 2–13

SYS$LP_LINES redefining, 2–64

SYS$MGBLSC example use, F–9

SYS$NXTVOL (RMS) data structure needed to use, 11–8

SYS$OPEN (RMS) data structure needed to use, 11–6 example of use, 11–17 when to use, 11–18

SYS$OUTPUT default logical unit number, 6–3, 6–17

SYS$PARSE (RMS), 11–21 data structure needed to use, 11–6

SYS$PUT (RMS), 11–19 data structure needed to use, 11–8

SYS$QIO example use, F–8

SYS$QIOW

See also QIO example use, 10–43, F–3, F–6, F–8

SYS$READ (RMS), 11–20 data structure needed to use, 11–8 example of use, 11–36

SYS$RELEASE (RMS) data structure needed to use, 11–8

SYS$REMOVE (RMS), 11–21 data structure needed to use, 11–6

SYS$RENAME (RMS) data structure needed to use, 11–6

SYS$REWIND (RMS) data structure needed to use, 11–8

SYS$SEARCH (RMS), 11–21 data structure needed to use, 11–6

Index–46

SYS$SETDDIR example use, F–2

SYS$SETEF example use, F–8

SYS$SETEXV, 14–2

SYS$SPACE (RMS), 11–21 data structure needed to use, 11–8

SYS$TRNLNM example use, 10–40, F–21

SYS$TRUNCATE (RMS), 11–21 data structure needed to use, 11–8

SYS$UNWIND, 14–21 use in condition handlers, 14–18 to 14–19

SYS$UPDATE (RMS), 11–21 data structure needed to use, 11–8

SYS$WAIT (RMS) data structure needed to use, 11–8

SYS$WAITFR example use, F–8

SYS$WAKE example use, F–21 synchronizing access, 13–10

SYS$WRITE (RMS), 11–20 data structure needed to use, 11–8 example of use, 11–35

/SYSLIB qualifier (LINK), 3–3

/SYSSHR qualifier (LINK), 3–3

System definition library modules, 2–13

System services

See also SYS$name closing file, 11–19 example programs using, F–1 to F–24 flushing record buffers, 6–39 functional groups, 10–26 general calling considerations, 10–26 to

10–32 opening file, 11–18

OpenVMS data types, 10–32 overview, 10–25 record operations, 11–19 summary of RMS services, 11–21 used for synchronizing access, 13–10 used in condition handler routines, 14–18

System symbols conventions in FORSYSDEF

PARAMETER declarations, 11–4 to

S_float data

11–5

See Floating-point data types

T

Task-to-task communications, network,

13–13 to 13–15

Terminal control block

XABTRM (RMS), 11–13

Terminal I/O

See also Ctrl/C; Ctrl/Y

Compaq Fortran 77 differences, B–10 example of SYS$QIOW, F–6 to F–8 formatting screen output, F–14 to F–16 interrupting interactive program execution, 3–11 to 3–12 example of handling Ctrl/C, 10–43,

F–3

Text file libraries creating and modifying

LIBRARY command, 2–93 to 2–95 defining defaults, 2–12 to 2–13 general discussion, 2–13, 2–93

INCLUDE searches, 2–11

/LIBRARY qualifier, 2–63 search order (compilation), 2–11 specifying, 2–10 to 2–13 on command line (/LIBRARY), 2–63 system-supplied default library

FORSYSDEF.TLB, 2–13

Threaded program execution related qualifiers, 2–78 requesting, 2–78

Threaded reentrancy effect on RTL, 2–79

Thread locking reentrancy during RTL calls, 2–79

/TIE qualifier, 2–88, B–24

TLB file type, 2–63, 2–93

Index–47

Traceback condition handler, 14–4

Traceback mechanism effect of /DEBUG on LINK command, 3–3, 3–7, 3–13 to

3–16 effect of /DEBUG qualifier, 2–49

/TRACEBACK qualifier (LINK), 3–3, 3–7,

3–13 to 3–16

Translated images interoperability

FORTRAN command, 2–88, B–24

LINK command, 3–3, 3–5, B–24 summary, B–24

Transportability

See also Compatibility; Data; Record types; Unformatted files

TYPE specifier, 6–23

See also LRM

TYPE statement, 6–5

See also LRM

T_float data

See Floating-point data types

U

UBOUND intrinsic, 1–8

Unaligned data, 5–18 causes, 5–18 to 5–20 checking for, 5–21 compiler, 5–21 derived-type effect of SEQUENCE statement,

2–28 error messages compiler, 2–90 run-time, 5–21 using debugger to locate, 4–27

Underflow

See also Denormalized numbers (IEEE) controlling handling (/IEEE_MODE qualifier), 2–58 denormalized numbers, 8–3, 8–20 run-time checking (/CHECK), 2–42

Unformatted data, 6–6 and DO loop collapsing, 5–43 and nonnative numeric formats, 9–3 efficient run-time performance, 5–34

I/O statements for, 6–7 inquiry by output item list, 6–27

Unformatted files converting nonnative data record type, 9–15 methods of specifying the format, 9–7 specifying format, 9–3 to 9–6 specifying record type, 6–13 supported numeric formats, 2–45, 9–3 using command qualifier to specify RECL units, 2–37 using FORTRAN /CONVERT qualifier to specify format, 2–45 using logical name method to specify format, 9–8, 9–10 using OPEN Statement

CONVERT=’keyword’ method to specify format, 9–13 using OPTIONS statement /CONVERT to specify format, 9–13

Unformatted I/O statements, 6–6

See also LRM

Units, logical I/O

See Logical I/O units

UNIT specifier, 6–2 to 6–3, 6–15, 6–23

See also LRM

UNLOCK statement, 6–5, 6–34

See also LRM

Unresolved references, 3–10

Unwind operations

See also SYS$UNWIND

User-defined data types

See Derived-type data

/USERLIBRARY qualifier (LINK), 3–3

USEROPEN routines block mode I/O example, 11–33 to 11–35 description of use, 11–2 in-depth discussion of, 11–21 to 11–31 restrictions on use, 11–24 to 11–25

Index–48

USEROPEN specifier, 6–24

See also LRM

User-written open procedures

See USEROPEN routines

USE statement, 1–6, 2–7, 10–3

See also LRM

Utility routines (Compaq Extended Math

Library), 15–2

V

%VAL function, 10–13

See also Argument passing

Value propagation, 5–45

Variable format expression, 5–37

See also LRM

Variable-length records, 6–12 use for optimal performance, 5–36

Variables

See also LRM alignment, 5–17 to 5–28 assigned but never used, 5–45 declared but not used controlling warning message, 2–92 never declared controlling warning messages, 2–90 output listing information, 2–113 used before value assigned controlling warning message, 2–92

Variables declared in other languages, accessing, 10–20

VAX FORTRAN

See Compaq Fortran 77; VAX systems

VAX systems

Compaq Fortran 77 (OpenVMS)

H_float data representation, B–26 converting data to IEEE formats, 9–2,

9–3 floating-point data

COMPLEX, 8–16

COMPLEX*16, 8–18 converting, 9–2, 9–3

D_float, 8–14

F_float, 8–12

VAX systems floating-point data (cont’d)

G_float, 8–13

H_float, B–26

Vector mathematics (Compaq Extended Math

Library), 15–2

Version number obtaining from command line, 2–87 obtaining from listing file, 2–64

/VERSION qualifier, 2–87

Very Large Memory (cDEC$ ATTRIBUTES

ADDRESS64 directive), 10–20

Virtual memory allocating (LIB$GET_VM), 10–27

64-bit (cDEC$ ATTRIBUTES ADDRESS64 directive), 10–20 deallocating (LIB$FREE_VM), 10–27 system and process limits, 1–2 to 1–4

VMS

See OpenVMS

/VMS qualifier, 2–88

VOLATILE statement, 13–4

See also LRM and data-flow and split lifetime analysis,

5–48 and granularity, 2–57 and implied-DO loop collapsing, 5–37 use with %LOC, 10–13 use with shared memory access, 2–57 when to use, 5–48

W

Warning messages argument mismatches, 2–90 arithmetic exception handling (run-time),

2–44 changing severity of (/SEVERITY), 2–82 controlling all messages, 2–91 data granularity, 2–91 exceptional values at run time (/CHECK),

2–43 flagging HP extensions (/STANDARD),

2–84

Index–49

Warning messages (cont’d) flagging HP extensions as error severity

(/SEVERITY), 2–82 floating-point underflow at run time

(/CHECK), 2–43, 2–45 format mismatches at run time (/CHECK),

2–43 format truncation mismatches at run time

(/CHECK), 2–44 integer overflow at run time (/CHECK),

2–44 limiting at compile-time (/ERROR_

LIMIT), 2–52 misalignment (compile-time), 2–90 misalignment (run-time), 5–21 nonprinting ASCII characters, 2–64 questionable programming practices,

2–92 standards conformance (/STANDARD),

2–84 statement functions never called, 2–91 substring references at run time

(/CHECK), 2–42 truncated lines, 2–91 undeclared variable use, 2–90 unused, declared variables, 2–92 use of two-digit year by intrinsic functions, 2–92 variables used before value assigned,

2–92 year 2000 (two-digit year), 2–92

/WARNINGS=ALIGNMENT qualifier, 2–90

/WARNINGS=ALL qualifier, 2–92

/WARNINGS=ARGUMENT_CHECKING qualifier, 2–90

/WARNINGS=DECLARATIONS qualifier,

2–90

/WARNINGS=GENERAL qualifier, 2–91

/WARNINGS=GRANULARITY qualifier,

2–91

/WARNINGS=IGNORE_LOC qualifier, 2–91

/WARNINGS=NONE qualifier, 2–92

/WARNINGS=UNCALLED qualifier, 2–91

/WARNINGS=UNINITIALIZED qualifier,

2–92

/WARNINGS=UNUSED qualifier, 2–92

/WARNINGS=USAGE qualifier, 2–92

/WARNINGS qualifier, 2–89

Web site

OpenVMS, xxvii

Working set, process example of how to adjust, F–18 to F–19

Write operations

See I/O operations

WRITE statement, 6–4

See also LRM

ADVANCE specifier, 6–36

X

XAB

See Extended access block (XAB)

XABALL (RMS) allocation control block, 11–13

XABDAT (RMS) date and time control block, 11–13

XABFHC (RMS) file header characteristics control block,

11–13

XABITM (RMS) item list control block, 11–13

XABJNL (RMS) journaling control block, 11–13

XABKEY (RMS) key definition control block, 11–13

XABPRO (RMS) protection control block, 11–13

XABRU (RMS) recovery unit block, 11–13

XABSUM (RMS) summary control block, 11–13

XABTRM (RMS) terminal control block, 11–13

X edit descriptor

See also LRM

Index–50

Z

Zero representation in Alpha floating-point data, 8–20

ZEXT function, 10–13

See also LRM

Index–51

Përshëndetje! Unë jam një chatbot AI i trajnuar posaçërisht për t'ju ndihmuar me HP for OpenVMS Fortran User Manual. Unë e kam shqyrtuar plotësisht dokumentin dhe mund t'ju ndihmoj të gjeni informacionin e saktë që ju nevojitet ose të shpjegoj përmbajtjen në terma të qartë dhe të thjeshtë. Pavarësisht nëse jeni duke kërkuar udhëzime mbi veçori specifike, hapa zgjidhjeje problemesh ose përdorim të përgjithshëm, mos ngurroni të bëni pyetjet tuaja. Sa më shumë detaje të jepni rreth shqetësimeve ose nevojave tuaja, aq më saktë dhe efektivisht mund t'ju ndihmoj!

Asistenti po shkruan

Asistenti nuk është në tastierë. Ju lutemi, provoni përsëri më vonë.

Duket se keni arritur në një dokument që është shkruar në disa gjuhë, duke përfshirë një që nuk është gjuha juaj amtare. Mund të përdorni lidhjet e mëposhtme për të fshehur përkohësisht faqet pa gjuhën që preferoni.

Reklamë

HP Fortran for OpenVMS

User Manual

Contents

Preface

1 Getting Started

2 Compiling HP Fortran Programs

3 Linking and Running HP Fortran Programs

4 Using the OpenVMS Debugger

5 Performance: Making Programs Run Faster

6 HP Fortran Input/Output

7 Run-Time Errors

8 Data Types and Representation

9 Converting Unformatted Numeric Data

10 Using HP Fortran in the Common Language Environment

11 Using OpenVMS Record Management Services

12 Using Indexed Files

13 Interprocess Communication

14 Condition-Handling Facilities

15 Using the Compaq Extended Math Library (CXML) (Alpha

Only)

A Differences Between HP Fortran on OpenVMS I64 and

OpenVMS Alpha Systems

B Compatibility: Compaq Fortran 77 and HP Fortran

C Diagnostic Messages

D HP Fortran Logical Names

E Contents of the HP Fortran System Library FORSYSDEF

F Using System Services: Examples

Index

Examples

Figures

Tables

Preface

Intended Audience

Document Structure

Related Documents

Reader’s Comments

HP Fortran Web Page

Conventions

Getting Started

1.1 Fortran Standards Overview

1.2 HP Fortran Programming Environment

1.3 Commands to Create and Run an Executable Program

1.4 Creating and Running a Program Using a Module and

Separate Function

1.4.1 Commands to Create the Executable Program

1.4.2 Running the Sample Program

1.4.3 Debugging the Sample Program

1.5 Program Development Stages and Tools

Compiling HP Fortran Programs

2.1 Functions of the Compiler

2.2 FORTRAN Command Syntax, Use, and Examples

2.2.1 Specifying Input Files and Source Form

2.2.2 Specifying Multiple Input Files

2.2.3 Creating and Using Module Files

2.2.4 Using Include Files and Include Text Library Modules

2.2.5 Specifying Output Files

2.2.6 Examples of the FORTRAN Command

2.3 FORTRAN Command Qualifiers

2.3.1 FORTRAN Command Qualifier Syntax

2.3.2 Summary of FORTRAN Command Qualifiers

2.3.3 /ALIGNMENT — Data Alignment

2.3.4 /ANALYSIS_DATA—Create Analysis Data File

2.3.5 /ANNOTATIONS — Code Descriptions

2.3.6 /ARCHITECTURE — Architecture Code Instructions (Alpha only)

2.3.7 /ASSUME — Compiler Assumptions

2.3.8 /AUTOMATIC — Data Storage

2.3.9 /BY_REF_CALL — Character Literal Argument Passing

2.3.10 /CCDEFAULT — Carriage Control for Terminals

2.3.11 /CHECK — Generate Code for Run-Time Checking

2.3.12 /CONVERT — Unformatted Numeric Data Conversion

2.3.13 /D_LINES — Debugging Statement Indicator, Column 1

2.3.14 /DEBUG — Object File Traceback and Symbol Table

2.3.15 /DIAGNOSTICS — Create Diagnostics File

2.3.16 /DML — Invoke Fortran DML Preprocessor

2.3.17 /DOUBLE_SIZE — DOUBLE PRECISION Data Size

2.3.18 /ERROR_LIMIT — Limit Compiler Messages

2.3.19 /EXTEND_SOURCE — Line Length for Fixed-Form Source

2.3.20 /F77 — FORTRAN IV or FORTRAN-77 Compatibility

2.3.21 /FAST — Request Fast Run-Time Performance

2.3.22 /FLOAT — Specify Floating-Point Format in Memory