c
SC26-3985-2
File No. S370-25
VS FORTRAN
Application Programming:
Program Product Guide
Program Numbers 5748-F03 (Compiler
and Library)
5748-LM3 (Ubrary Only)
Release 1.1
This publication was produced using the
IBM Document Composition Facility
(program number 5748-XX9) and
the master was printed on the IBM 3800 Printing Subsystem.
Second Edition (January 1982)
This is a major revision of, and makes obsolete, SC26-3985-1, and
its technical newsletters, SN26-0806 and SN26-0865. /^\
This edition applies to Release 1.1 of VS FORTRAN, Program
Products 5748-F03 (Compiler and Library) and 5748-LM3 (Library
only), and to any subsequent releases until otherwise indicated
in new editions or technical newsletters.
The changes for this edition are summarized under "Summary of
Amendments" following the preface. Specific changes are indicated
by a vertical bar to the left of the change. These bars will be
deleted at any subsequent republication of the page affected.
Editorial changes that have no technical significance are not
noted.
Changes are periodically made to the information herein; before
using this publication in connection with the operation of IBM
systems, consult the latest IBM System/370 and 4300 Processors
Bi bi lographv , GC20-0001, for the editions that are applicable and
current.
It is possible that this material may contain reference to, or
information about, IBM products (machines and programs),
programming, or services that are not announced in your country.
Such references or information must not be construed to mean that
IBM intends to announce such IBM products, programming, or
services in your country.
Publications are not stocked at the address given below; requests
for IBM publications should be made to your IBM representative or
to the IBM branch office serving your locality.
A form for reader's comments is provided at the back of this
publication. If the form has been removed, comments may be
addressed to IBM Corporation, P.O. Box 50020, Programming x
Publishing, San Jose, California, U.S.A. 95150. IBM may use or /iT )
distribute any of the information you supply in any way it I /
beli eves appropriate without incurring any obligation whatever.
You may, of course, continue to use the information you supply.
©Copyright International Business Machi nes Corporation 1981,
1982
ABOUT THIS BOOK
MANUAL ORGANIZATION
g"\
INDUSTRY STANDARDS
This manual describes how to use VS FORTRAN, together with the
supported operating systems, to design, develop, test, and run
programs written in VS FORTRAN at the 1978 language level. It is
designed as a guide for using VS FORTRAN at the current language
level; it is not intended to be used as a reference manual.
This manual is designed for FORTRAN application developers who
use VS FORTRAN in two different ways-'
• Engineers and scientists who use FORTRAN as a tool in
mathematical problem solving
• Application programmers who use all of the FORTRAN features
to code FORTRAN programs for their own use or for others
Because of these differences in FORTRAN usage, this manual is
organized into sections:
"Part 1 — Simplified FORTRAN Programming" describes how to
develop and run mathematical problem-solving FORTRAN programs
that have relatively little system interaction.
"Part 2 — Advanced FORTRAN Programming" describes all aspects
of VS FORTRAN program development, including sophisticated
use of the language and of the operating systems.
Both of these sections are organized in the same way; they
present, in chronological order, the steps you follow in
developing a FORTRAN application program:
1. Designing
2. Coding
3. Compiling
4. Fixing compile-time errors
5. Link-editing
6. Executing (in test mode)
7. Fixing execution-time errors
8. Executing (in production mode)
The rest of the manual describes particular self-contained VS
FORTRAN features:
"Part 3 — FORTRAN Special Features" describes how to use VS
FORTRAN input/output facilities, the facilities for calling
and called programs, and VM/370-CNS with VS FORTRAN. There's
also a brief description of the execution-time library.
Appendixes give useful supplementary information: information
on the hardware devices that can be used, and considerations
for assembler language subroutines.
The VS FORTRAN Compiler and Library program product is designed
according to the specifications of the following industry
standards, as understood and interpreted by IBM as of June, 1980*
About Thi s Book i i i
American National Standard Programming Language FORTRAN, ANSI /f r~ v !
X3. 9-1978 (also known as FORTRAN 77). r
International Organization for Standardization ISO 1539-1980
Programming Languages-FORTRAN.
These two standards are techni cally equivalent. In this
manual, references to the current standard are references to
these two standards.
American Standard FORTRAN, X3. 9-1966.
International Organization for Standardization ISO R
1539-1972 Programming Languages-FORTRAN.
These two standards ar& technically equivalent. In this
manual, references to the old standard are references to
these two standards.
For both current and old standard language, a number of IBM
language extensions are also included in VS FORTRAN. In this book,
references to current FORTRAN or current language are references
to the current standard plus the IBM extensions valid with it;
references to old FORTRAN or old language are references to the
old standard plus the IBM extensions valid with it.
RELATED PUBLICATIONS
This manual is designed as a guide on how to use VS FORTRAN at the
current language level. It is not intended to be used as a
reference manual.
Reference documentation for VS FORTRAN is given in the following
publi cations*
VS FORTRAN Application Programming *
Language Reference manual, GC26-3986 — which describes each
syntactic element available when you're using the current
language
System Servic e s Reference Supplement , SC26-3988 — which
provides FORTRAN-speci f i c system information on running VS
FORTRAN programs under VM/370-CMS, OS/VS, and DOS/VSE
Library Reference manual, SC26-3989- — which describes each
mathematical and service subprogram contained in the
execution-time library: its algorithm, accuracy, range, and
error conditions
Source-Time Reference Summary , SX26-3731 — which is a
pocket-sized reference card containing formats for current
source language and brief descriptions of the compiler
options
IBM Svstem/360 and Svstem/370 FORTRAN IV Language ,
GC28-6515 — -which describes the source language available when
you're using the old language .
FORTRAN Coding Form , 6X28-7327 — useful for coding fixed-form
FORTRAN programs.
The previously listed publi cati ons gi ve documentation only for
application programming.
If you need information on VS FORTRAN installation or
customization, see*
VS FORTRAN Installation and Customi zat i on , SC26-3987-— which
gives information on installation planning, on the compiler
and library installation macros, storage requirements, and
^^
iv VS FORTRAN Application Programming: Guide
administrative information about controlling input/output,
and how to create and alter the option table
The Program Directory for the system you're operating under*
shipped with the product* gives details on installing VS FORTRAN
RELATED SYSTEMS PUBLICATIONS
Detailed system information is not included in the VS FORTRAN
publications. Therefore* in order to use this set of manuals
properly* you should be sure you have on hand one of the following
sets of manuals* depending on the system you're using.
For information on developing algorithms for direct files* see
the Introduction to IBM Direct Access Storgage Devices and
Organization Methods, GC20-1649.
VM/370-CMS Systems Publications
The following publications contain guide and reference
documentation you'll need:
IBM Virtual Machine Faci 1 i tv/370 :
CP Command Reference for General Users , GC20-1820
CMS User's Guide , GC20-1819
CMS Command and Macro Reference , GC20-1818
Terminal User's Guide , GC20-1810
OS/VS Systems Publications
OS/VS Linkage Editor and loader , GC26-3813
OS/VS Virtual Storage Access Method (VSAM) Programmer's
Guide , GC26-3838
OS/VS Tape Labels , GC26-3795
MVS PUBLICATIONS: If you're using MVS, you'll need the following
additional publications:
0S/VS2 MVS Data Management Services Guide * GC26-3875
0S/VS2 Access Method Services , GC26-3841
0S/VS2 MVS JCL * GC28-0692
0S/VS2 Debugging Guide , GT28-0632
0S/VS2 TSO Terminal User's Guide , GC28-0645
0S/VS2 TSO Command Language Reference , GC28-0646
TSQ-3270 Structured Programming Facility (SPF) Program
Reference Manual , SH20-1730
0S/VS1 PUBLICATIONS: If you're using 0S/VS1* you'll need the
following additional publications:
0S/VS1 Data Management Services Guide , GC26-3874
0S/VS1 Access Method Services , GC26-3840
0S/VS1 JCL Services, GC24-5100
About This Book
0S/VS1 JCL Reference , GC24-5099 ^
OS/V51 Debugging Guide , GC24-5093
DOS/VSE Publications
The following publications contain guide and reference
documentation you'll need:
DOS/VSE System Management Guide , GC33-5371
DOS/VSE Data Management Concepts , GC24-5138
DOS/VSE Serviceability Aids and Debugging Procedures ,
GC33-5380
vSE/v'SAM Programmer's Reference , 5C24-51H5
Using VSE/V5AM Commands and Macros , SC24-5144
Using the VSE/VSAM Space Management for SAM Feature ,
SC24-5192
DOS/VSE Tape Labels , GC33-5374
DOS/VSE DASD Labels , GC33-5375
A
^
vi VS FORTRAN Application Programming: Guide
SUMMARY OF AMENDMENTS
c
RELEASE 1.1> JANUARY 1982
FORTRAN INTERACTIVE DEBUG
SERVICE CHANGES
FORTRAN Interactive Debug Release 2.2 runs with VS
FORTRAN-compi led programs.
In addition to minor corrections to examples, the following areas
have been changed:
INCLUDE statement
DATA statement
Block IF statement
Additional coding errors to avoid
^PROCESS statement
OS/VS JOB and DD statements
Optional OS/VS compile-time data sets
TSO LINK command
Command procedures for foreground processing
MAP option
External f i lename
BACKSPACE statement
Subprogram references in FORTRAN
Differences between VS FORTRAN and current implementations
Statement number limits
Two major sections: "Using VM/370-CMS with VS FORTRAN" and "Using
0S/VS2-TS0 with VS FORTRAN" have been moved from Part 3 to Part 2.
RELEASE 1> JUNE 1981
MISCELLANEOUS CHANGES
Page numbers have been changed in the list of figures.
Description of the TERMINAL option has been added.
Examples have been added and changed.
A DOS/VSE load module logical units chart has been added.
The order of variables in the COMMON statement has been
corrected.
Summary of Amendments
VI i
Two appendixes have been added:
~ Differences Between VS FORTRAN and Current
Implementations
Internal Limits in VS FORTRAN
The glossary and index have been corrected.
RELEASE 1* APRIL 1981
OPTIMIZE COMPILER OPTION
The compiler option* OPTIMIZE(O), is available with Release 1.0
of VS FORTRAN. Additional optimization features (OPTIMIZE
(1/2/5)) discussed in this manual are "lannec
at a later time.
■%^jp
©-'
viii VS FORTRAN Application Programming: Guide
CONTENTS
VS FORTRAN Overview 1
VS FORTRAN — Thumbnai 1 Description 1
VS FORTRAN Publications 2
IBM Extension Documentation . 3
Part 1 — Simplified FORTRAN Programming 5
Designing Your Program — Simplified Programming 6
Coding Your Program — Simplified Programming 7
Before You Begin 7
Retrieving Data — The READ Statement 7
Converting Character Data — Internal READ Statement .... 8
Defining Data 8
VS FORTRAN Data Types . . . 9
Defining Data Items 9
Predetermined Data Type Definition 9
Explicit Data Type Definition . 10
Defining Program Constants : . . 11
Using Program Constants Directly 11
Using Names for Program Constants 11
Program Reference Points — Using Statement Numbers . . 12
Defining Arrays and Subscripts 12
Defining and Referring to One-Dimensional Arrays ... 12
Defining and Referring to Multidimensional Arrays . . 13
Using the Assignment Statement . 13
Initializing Variables — Assignment Statement 14
Using Arithmetic Expressions in Assignment Statements . 14
Using Intrinsic Functions 15
Controlling Program Flow 16
Programming Alternative Execution Paths — Arithmetic IF
Statement 16
Programming Alternative Execution Paths — Logical IF
Statement 16
Executing Procedures Repetitively — DO Statement .... 17
Processing One-Dimensional Arrays — DO Statement ... 17
Processing Multidimensional Arrays — Nested DO
Statement * 17
Obtaining Results — Using the WRITE Statement 18
Ending Your Program — END Statement 19
Coding Errors to Avoid 19
Compiling Your Program — Simplified Programming ...... 20
Entering Your Source Program 20
Requesting Compilation ..... 20
Requesting Compilation Only — OS/VS 20
Requesting Compilation Only — DOS/VSE 21
Compiler Output 21
Fixing Compile-time Errors — Simplified Programming .... 22
Using the Messages 23
Link-Editing Your Program — simplified Programming .... 24
Requesting L i nk-Edi ti ng— OS/VS 24
Requesting Link-Editing — DOS/VSE . 24
Using the Link-Edited Program 25
Executing Your Program — Simplified Programming 26
Executing Your Program — OS/VS 26
Setting Up Test Data Files — OS/VS 26
Compile, Link-Edit, and Execute — OS/VS 27
Executing Your Program — DOS/VSE 27
Setting Up Test Data Fi les— DOS/VSE 27
Compile, Link-Edit, end Execute — DOS/VSE 28
Execution Output 28
Fixing Execution-Time Errors — simplified Programming ... 29
Contents
i x
Finding Errors . 29
Execution-Time Error Messages . 29
Endless Loops or Waits 29 zO\
Unexpected Output 30 k^V
Using Debugging Packets 30
Fixing Errors 30
A Sample Program — simplified Programming 31
Part 2 — Advanced FORTRAN Programming 33
Designing Your Program — Advanced Programming 34
Top-Down Design and Development 34
Using Top-Down Design in VS FORTRAN 36
Top-Down Design with a Single Object Modules — INCLUDE
Statement •, * 36
Top-Down Design with Multiple Object Modules — Using
Subprograms 37
k ^,j /
cooing Your program — Advanced programming .... oo
Using Fixed-Form Input: — FORTRAN Coding Form 38
Using Free-Form Input .....; 38
Defining Data 39
Predetermined Data Type Def ini ti on 40
Explicit Data Type Definition 40
Typing Groups of Data Items — IMPLICIT Statement ... 40
Typing for Specific Data Items — Explicit Type
Statements 41
Data Classifications 42
Variables 42
Constants 42
Defining Constants by Value 42
Defining Constants by Name— PARAMETER Statement ... 46
Arrays and Subscripts 46
One-Dimensional Arrays . 47
Multidimensional Arrays 47
Arrays — Implicit Lower Bounds 47
Arrays; — Explicit Lower Bounds 48
Arrays — Signed Subscripts , 48
Arrays — Programming Considerations 49
Substrings of Character Items 49
Using Data Efficiently . 50
Initializing Data — DATA Statement 50
Initializing Arrays — DATA Statement 50
Managing Data Storage — EQUIVALENCE Statement 51
Execution-Time Efficiency Using Equivalence 52
Defining and Using Expressions 53
Arithmetic Expressions 53
Character Expressions 55
Relational Expressions 56
Relational Expressions — Character Operands 57
Logical Expressions .. . . 57
Assigning Values to Data — Assignment Statement 58
Arithmetic Assignments 59
Character Assignments 59
Logical Assignments . . . ".' 60
Saving Coding Effort with Statement Functions 60
Controlling Program Flow 61
Using Structured Programming — Block IF Statement .... 61
Using the CONTINUE Statement 64
Programming Loops — DO Statement 64
Using Program Switches — Assigned GO TO Statement .... 66
Using Conditional Transfers — Computed GO TO Statement . 66
Suspending Program Execution — PAUSE and STOP Statements 67
Suspending Execution Temporari ly— PAUSE Statement . . 67
Stopping Programs Permanently — STOP Statement .... 67
Ending Your Program — END Statement 68
Use Pre-Written Source Code 68
Avoi ding Codi ng Errors ... . . . 68
Compiling Your Program — Advanced Programming 71 /f^\)
Automatic Cross Compilation ........... 71 " ■
Overall Job Control Considerations . . 71
X VS FORTRAN Application Programming? Guide
(O
Syntax for Job Control Statements 71
Using the Compile-Time Options 72
Modifying PROC Statements — OS/VS 82
Modifying EXEC Statements — OS/VS 82
Modifying DD Statements — OS/VS 83
Job Control Considerations — DOS/VSE ... 84
Using DOS/VSE Job Control Statements 85
Identifying a Job — DOS/VSE JOB Statement 85
Specifying Linkage-Editor Options — DOS/VSE OPTION
Statement 85
Defining Files — DOS/VSE ASSGN Statement 85
Defining Files on Direct Access Devices — DOS/VSE .... 86
DLBL Statement — DOS/VSE 86
EXTENT Statement — DOS/VSE 86
Requesting Execution — DOS/VSE EXEC Statement 86
Requesting Compilation — DOS/VSE 87
Compiling a Single Source Program — DOS/VSE 87
Batch Compilation of More Than One Source
Program — DOS/VSE 87
Compile-Time Files — DOS/VSE 88
Writing and Modifying Cataloged Procedures — DOS/VSE ... 88
Retrieving Cataloged Procedures — DOS/VSE 88
Temporarily Modifying Cataloged Procedures — DOS/VSE . . 88
Compiler Output 89
Compiler Output with Default Options 89
Output with Explicit Compiler Options ... 90
Cataloging Your Source Program 90
Cataloging Your Source — OS/VS 90
Cataloging Your Source — DOS/VSE 91
Cataloging Your Object Module — DOS/VSE 92
Cataloging Your Object Module — OS/VS . . . 92
Cataloging Your Object Module — DOS/VSE 92
Using VM/370-CMS Nith VS FORTRAN . 93
The CP and CMS Commands . . , 93
Using Your Terminal with CMS 93
Creating Your Source Program — CMS EDIT Command 93
Using the FORTRAN INCLUDE Statement — CMS 95
Compiling Your Program — Using CMS 95
Compiler Output — CMS . .' 96
The LISTING File — CMS 96
The TEXT File— CMS 96
Making Libraries Available — CMS GLOBAL Command 96
Loading and Executing Your Program under CMS 97
Using the LOAD and INCLUDE Commands — CMS 97
Creating a Nonrelocatable Load Module — GENMOD Command 97
Defining Sequential and Direct Data Files — CMS 98
Specifying a File Identifier — CMS 98
Using the FILEDEF Command — CMS 98
Defining Sequential and Direct Disk Files — CMS .... 98
Defining Tape Files — CMS 98
Defining Terminal Files — CMS 99
Defining Unit Record Files — CMS 99
Defining VSAM Sequential and Direct Files — CMS 99
Defining a VSAM File to CMS 100
Using the DLBL Command — CMS 100
Creating a VSAM DEFINE Command — CMS EDIT Command . . . 100
Making the Catalog Entry — AMSERV Command . 100
Creating and Processing VSAM Files — CMS 101
Using 0S/VS2-TS0 With VS FORTRAN 102
Using the TSO Commands 102
Using Your Terminal with TSO 102
Creating Your Source Program — TSO EDIT Command ...... 102
Compi ling Your Program — TSO ALLOCATE and CALL Commands . . 104
Allocating Compilation Data Sets — TSO ALLOCATE
Command . 104
Requesting Compilation — CALL Command 104
Compiler Output — TSO . 105
The LIST File— TSO . 105
The OBJ File — TSO 105
Link-Editing and Executing Your Program under TSO ..... 105
Link-Editing Your Program — TSO LINK Command 106
Contents xi
Linkage Editor Listings — TSO LINK Command 106
Executing Your Program — TSO 106
Using the CALL Command — TSO Load Module Execution . . .* 106 |
Using the Loadei TSO LOADGO Command 107 /*~V ?
Fixing Execution Errors Under TSO 107 ^V
Requesting Command Procedure Processing Under TSO .... 108
Command Procedures For Foreground Processing 108
Command Procedures for Background Execution . 108
TSO File Naming Conventions 109
File Identification — TSO ALLOCATE Command 110
Defining VSAM Sequential and Direct Files — TSO Ill
System Considerations Under 0S/VS2-TSO Ill
Fixing Compile-Time Errors — Advanced Programming ...... 112
Using the Compiler Output Listing 112
Compilation Identification . 112
Source Program Listing — SOURCE Option ..... 112
Diagnostic Message Listing — FLAG Option 113
OS/VS Cataloged Procedures and Compiler Message Codes 115
DOS/VSE Message Code Considerations 115
Using the MAr" and X'Ktr uptions 115
Source Program Map — MAP Option 116
NAME Column 116
MODE Column 116
TAG Column 117
Address Column 117
COMMON Block Maps — MAP Option .'. 117
Statement Label Map — MAP Option 118
Source Program Cross-Reference Dictionary — XREF Option 118
Data Item Dictionary — XREF Option 119
Statement Label Dictionary — XREF Option 119
End of Compilation Message 120
Using the Standard Language Flaggei FIPS Option 120
Link-Editing Your Program — Advanced Programming 122
Automatic Cross-System Support 122
Linkage Editor Input 122 \
Object Module as Link-Edit Data Set — DECK Option .... 122 (^ /
ESD Record 123 V^
TXT Record 123
RLD Record 123
END Record 124
Producing a Load Module — OBJECT Option 124
Link-Editing for Immediate Execution 124
Link-Editing Your Program — OS/VS 125
Cataloging Your Load Module — OS/VS 125
Executing a Link-Edit — OS/VS 125
Using the Linkage Editoi OS/VS . . 125
Using the Loader — OS/VS 126
Link-Editing Your Program — DOS/VSE 127
Cataloging Your Load Module — DOS/VSE 127
Executing a Link-Edit — DOS/VSE . 128
Logical Units Used for Link-Editing — DOS/VSE 128
Linkage Editor Output 129
Executing Your Program — Advanced Programming 130
Executing Your Program — OS/VS / 130
Using Load Module Data Sets — OS/VS 130
Using Cataloged Load Modules — OS/VS 131
Executing the Load Module — OS/VS 131
Execute Only — OS/VS 131
Link-Edit and Execute — OS/VS ........ 131
Compile, Link-Edit, and Execute — OS/VS 131
Executing Your Program — DOS/VSE . 132
Load Module Logical Units — DOS/VSE 132
Executing the Load Module — DOS/VSE 133
Execute Only— DOS/VSE 133
Link-Edit and Execute — DOS/VSE 133
Compile, Link-Edit, and Execute — DOS/VSE 133
Load Module Execution-Time Output . 134
Execution without Error ...... . . 134
Execution with Errors 134
O-
xi i VS FORTRAN Application Programming* Guide
c
Fixing Execution-Time Errors — Advanced Programming .... 135
Execution-Time Messages 135
Library Diagnostic Messages 135
Using the Optional Traceback Map 135
LIST Compiler Option and Traceback Maps 137
Program Interrupt Messages 137
Operator Messages 138
Using Debug Packets 139
Using Extended Error Handling 140
Extended Error Handling By Default 140
Controlling Extended Error Handling — Call Statements 142
Extended Error Handling — DOS/VSE Considerations . . . 143
Object Module Listing — LIST Option 143
Requesting Dumps . . 149
Requesting Dynamic Dumps — CALL Statement 149
Dynamic Dumps — DOS/VSE Considerations 149
Requesting an Abnormal Termination Dump 150
Requesting a Dump — OS/VS ...... 150
Requesting a Dump — DOS/VSE 150
Part 3 — FORTRAN Special Features 151
Programming Input and output 152
Using VS FORTRAN Input/Output Statements 152
Using Common Options For Input/Output 152
Connecting to a File — OPEN Statement 153
Creating File Records — WRITE Statement 155
Retrieving File Records — READ Statement 155
Obtaining File Information — INQUIRE Statement 156
Disconnecting a File — CLOSE Statement 156
Using Unformatted and Formatted I/O 157
Formatting FORTRAN Records — FORMAT Statement 157
Group FORMAT Specifications 159
Using Specifications Repeatedly — FORMAT Control . . . 160
Using One FORMAT Statement with Variable Formats . . . 160
Using Sequential Files . . . 161
Source Program Considerations 161
Using the OPEN Statement — Sequential Files 161
Using the WRITE Statement — Sequential Files 161
Using the READ Statement — Sequential Files 162
Using the ENDFILE Statement — Sequential Files .... 163
Using the REWIND Statement — Sequential Files 163
Using the BACKSPACE Statement — Sequential Files . . . 163
Using the CLOSE Statement — Sequential Files 164
Using Asynchronous Input/Output 164
Using the Asynchronous WRITE Statement 164
Using the Asynchronous READ Statement 165
Using the Asynchronous WAIT Statement 165
Using List-Directed Input/Output 166
Input Data — list-Directed I/O 166
List-Directed READ Statement . 167
List-Directed WRITE Statement 168
Using Internal Files 168
Using the READ Statement — Internal Files 169
Using the WRITE Statement — Internal Files 169
System Considerations — Sequential Files 170
OS/VS Considerations — Sequential Files 170
DOS/VSE Considerations — Sequential Files 170
Using Direct Files 170
Source Program Considerations 171
Using the OPEN Statement — Direct Files 171
Using the WRITE Statement — Direct Files 171
Using the READ Statement — Direct Files . 172
Using the CLOSE Statement — Direct Files 173
System Considerations- — Direct Files 173
OS/VS Considerations — Direct Files 173
DOS/VSE Considerations — Direct Files . . . 174
Using VSAM Files 174
Source Language Considerations — VSAM Files ....... 175
Processing VSAM Sequential Files 176
Processing VSAM Direct Files 177
Processing VSAM-Managed Sequential Files 179
Obtaining the VSAM Return Code — IOSTAT Option .... 179
Contents xi i i
Defining a VSAM File . . 179
Defining a VSAM Sequential File 180
Defining a VSAM Direct File 180
Defining a DOS/VSE VSAM-Managed Sequential File . . . 181 ^lOy
Processing DEFINE Commands 181 u J
Processing DEFINE Commands — OS/VS 181 ^~"*
Processing DEFINE Commands — DOS/VSE 182
Creating and Processing VSAM Files 182
Creating and Processing VSAM Files — OS/VS 182
Creating and Processing VSAM Fi les — DOS/VSE 182
System Consi derati ons — Input/Output . . . 183
Using Input/Output Labels 183
Magnetic Tape Labels 183
OS/VS Tape Label Considerations 184
DOS/VSE Tape Label Considerations . ..... 184
Direct Access Device Labels 184
Volume Labels 184
Processing Direct Access Device Labels 185
OS/VS Direct Access Label Considerations 185
DOS/VSE Direct Access Label Considerations 185
Defining FORTRAN Records System Considerations .... 185
Record Formats — OS/VS 185
Defining Records — OS/VS 186
Record Formats — DOS/VSE 187
Coding Calling and Called Programs 189
Kinds of Called Programs 189
Sharing Data Between Programs * 190
Passing Arguments Between Programs 190
Passing Arguments to a FUNCTION Subprogram 191
Passing Arguments to a SUBROUTINE Subprogram 191
General Rules for Arguments 192
Assigning Argument Values . 192
Sharing Data Storage — COMMON Statement 193
Data Item Order — COMMON Statement 193
Type and Length Considerations — COMMON Statement . . . 194
Efficient Arrangement of Variables — COMMON Statement 195
EQUIVALENCE Considerations — COMMON Statement 197 ^ N
Blank and Named Common 198 ( J'
Blank Common 199 ^^
Na^ed Common 199
Using Blank Common and Named Common 199
Using Blank and Named Common — Example 200
Coding Main Programs — Calling Programs . . . 201
Naming Your Main Program — PROGRAM Statement 201
Invoking FORTRAN-Suppli ed Functions 201
Using FORTRAN-Supplied Functions as
Arguments — INTRINSIC Statement 202
Comparing Character Operands — FORTRAN-Supplied
Functions . 202
Invoking FUNCTION and SUBROUTINE Subprograms 203
Invoking FUNCTION Subprograms 203
Invoking SUBROUTINE Subprograms — CALL Statement . . . 204
Coding Subprograms — Called Programs 205
Coding FUNCTION Subprograms 205
Coding SUBROUTINE Subprograms 206
Specifying Alternative Entry Points — ENTRY Statement 206
Alternative Entry Points in FUNCTION Subprograms . . . 206
Alternative Entry Points in SUBROUTINE Subprograms . . 207
Specifying Alternative Return Points — RETURN Statement 207
Retaining Subprogram Values — SAVE Statement 208
Initializing Named Common — BLOCK DATA Subprograms . . . 208
System Considerations . 209
Overlaying Programs in Storage 210
Specifying OS/VS Overlays . 210
Specifying DOS/VSE Overlays ... 211
Using the Optimization Feature . 213
Select the Higher Optimization Levels 213
Write Programs of Efficient Size 213
Use Unformatted I/O .213
Use Array Operands for I/O Transfers 213
Use LOGICAL Variables of Length 4 214
xiv VS FORTRAN Application Programming: Guide
Use INTEGER Variables of Length 4 .... ■ 214
Eliminate EQUIVALENCE Statements 214
Initialize Large Arrays During Execution 214
Use COMMON Blocks Efficiently 215
Pass Subroutine Arguments in COMMON Blocks 215
Don't Use Variably Dimensioned Arrays . 215
WriteCriticalLoopsInline . . 216
Ensure Recognition of Duplicate Computations 216
Ensure Recognition of Constant Computations 217
Ensure Recognition of Constant Operands ... 217
Eliminate Scaling Computations 217
Define Arrays with Identical Dimensions ... 217
Define Arrays with Identical Element Specifications . . 217
Use Critical Variables Carefully 218
Avoid Unneeded Fixed/Float Conversions 218
Minimize Conversions Between Single and Double Precision 218
Use Scalar Variables as Accumulators 218
Use Efficient Arithmetic Constructions , . . . 218
Use IF Statements Efficiently 219
Use the Object Program Listing 219
Source Considerations with 0PTIMIZEC3) 219
Common Expression Elimination — 0PTIMIZEC3) 220
Computational Reordering — 0PTIMIZE(3) 220
Instruction Elimination — 0PTIMIZEC3) 220
Using The Execution-Time Library 222
Mathematical and Character Functions 222
Service Routines 222
Error-Handling Routines 223
Automatic Error Handling . . 223
Error Handling Under Your Control 223
Appendixes 225
Appendix A. Device Information . 226
Minimum and Maximum Block Size Values 226
Direct Access Device Capacities 227
Appendix B. Assembler Language considerations 228
Subprogram References in FORTRAN 228
The Argument List 228
The Save Area 229
The Calling Sequence 229
Linkage in Assembler Subprograms 229
Called Assembler Subprograms 229
Called and Calling Assembler Subprograms 230
Main Programs 230
Using FORTRAN Data in Assembler Subprograms 230
Using COMMON Data in Assembler Subprograms 230
Using Blank Common Data in Assembler Programs 231
Using Named Common Data in Assembler Programs 231
Retrieving Arguments in an Assembler Program 231
Retrieving Variables from the Argument List 231
Retrieving Arrays and Array Elements from the
Argument List 232
Returning to Alternative Return Points 232
Internal Representation of FORTRAN Data ... 232
CHARACTER Items in Internal Storage 232
LOGICAL Items in Internal Storage 232
INTEGER Items in Internal Storage 233
REAL Items in Internal Storage 233
COMPLEX Items in Internal Storage 234
Appendix C. Differences Between vs FORTRAN and Current
Implementations 236
Appendix D. Internal Limits in VS FORTRAN 238
Nested DO Loops 238
Expression Evaluation 238
Nested Statement Function References . 238
Nested INCLUDE Statements 238
Nested Block IF Statements 238
Character Constants 238
Contents xv
Referenced Variables . . . . 238
Parentheses Groups ..... 238 )
Statement Labels . . .'* 239 /f~\J
Glossary 240 ^
Index 245
f
^Lj
xvi VS FORTRAN Application Programming* Guide
FIGURES
O
1. VS FORTRAN Application Programming Publications .... 3
2. IBM Extensions in Examples and Figures 3
3. Two-Dimensi onal Array — Physical Layout in Storage . . 13
4. Arithmetic Operators and Operations . 15
5. VS FORTRAN Error Message Example 22
6. Example of Top-Down Program Design 36
7. Data Types and Valid Lengths 39
8. Three-Dimensional Array — Implicit and Explicit
Lower Bounds 48
9. Arrays — Effect of Negative Lower Bounds 49
10. Sharing Storage Between Arrays — EQUIVALENCE Statement 52
11. Storage Efficiency and the EQUIVALENCE Statement . . 54
12. Arithmetic Operators and Operations 55
13. Relational Operators and their Meanings 56
14. Logical Operators and their Meanings 57
15. Block IF Statement — Valid Forms 63
16. Cataloged Procedure FORTVC, OS/VS 78
17. Cataloged Procedure FORTVCL, OS/VS 78
18. Cataloged Procedure FORTVCLG, OS/VS 79
19. Cataloged Procedure FORTVLG, OS/VS 80
20. Cataloged Procedure FORTVG, OS/VS 80
21. Cataloged Procedure FORTVCG, OS/VS 81
22. Cataloged Procedure FORTVL, OS/VS 81
23. Compiler Output Using Explicit Options 91
24. VM/370-CMS Commands Often Used with VS FORTRAN ... 94
25. 0S/VS2-TS0 Commands Often Used with VS FORTRAN ... 103
26. Allocating TSO Compilation Data Sets 104
27. Source Program Listing Example — SOURCE Option .... 113
28. Examples of Compile-Time Messages — FLAG Option . . . 114
29. Example of a Storage Map — MAP Option 116
30. Module Identification Codes 118
31. Example of a Cross-Ref erence Dictionary — XREF Option 120
32. Object Module Structure 124
33. Load Module Data Sets — OS/VS 130
34. Load Module Logical Units — DOS/VSE . 132
35. Operator Message Format 139
36. Using Batch Symbolic Debugging Statements 141
37. Library Names for DOS/VSE Error Handling and Service
Routines 143
38. Object Module Listing Example — LIST Compiler Option 145
39. Some Codes Used with the FORMAT Statement 158
40. Display for FORMAT E14.5E2 159
41. FORTRAN Statements Valid with VSAM Files 175
42. DOS/VSE Logical Units and Devices Allowed 187
43. Example of Shared Data Areas — COMMON Statement . . . 193
44. Transmitting Values Between Common Areas 194
45. Blank and Named Common Storage Sharing 201
46. CALL Statement Execution 204
47. VS FORTRAN Devices — Minimum and Maximum Block Sizes 226
48. Direct Access Device Capacities 227
Figures xvi i
%^
x>'
VS FORTRAN OVERVIEW
c
FORTRAN (FORmula TRANslator) is a programming language especially
useful for applications involving mathematical computations and
other manipulations of numeric data. It's particularly suited to
scientific and engineering applications.
FORTRAN looks and reads much like mathematical equations, so that
you can use conventional mathematical symbols and constructions
to control computer operations. FORTRAN is problem-oriented and
relatively machine-independent; this frees you from machine
restrictions and lets you concentrate on the logical aspects of
your data processing problems.
Compared with machine-oriented languages* FORTRAN gives you easy
program development, decreased debugging effort, and overall
greater data processi ng ef f i ci ency .
Source programs written in VS FORTRAN consist of statements you
write to solve your problem; the statements must conform to the VS
FORTRAN programming rules.
The VS FORTRAN compiler then analyzes your source program
statements and translates them into machine language, which is
suitable for execution on a computer system. The VS FORTRAN
compiler also produces other output to help you debug your source
and object programs.
The VS FORTRAN compiler generates object programs that use the
services of the VS FORTRAN execution-time library, and of the
supporting operating systems. It depends upon them for the
programming services it must use.
The VS FORTRAN compiler operates under control of one of the
following operating systems: VM/370-CMS, 0S/VS2 MVS with or
without TSO, 0S/VS1, or DOS/VSE. You can compile your program
under any one of these systems and then link-edit the program and
its subroutines to execute under any of the others.
VS FORTRAN — THUMBNAIL DESCRIPTION
VS FORTRAN is a program product that runs under VM/370-CM5, under
MVS or 0S/VS1, or under DOS/VSE. It's compatible in language,
because it accepts two language levels:
Current FORTRAN — 1978 American National Standard FORTRAN
(technically equivalent to ISO FORTRAN 1980), plus IBM
extensions. (The language features described in this manual
are current FORTRAN.)
Old FORTRAN — 1966 American National Standard FORTRAN
(technically equivalent to ISO FORTRAN 1972), plus IBM
extensions. (Old FORTRAN language is documented in IBM
Svstem/360 and Svstem/37Q: FORTRAN IV Language . )
The current FORTRAN language has a number of features never before
available in System/370 FORTRAN:
Added Control Over Input/Output — through the OPEN, CLOSE, and
INQUIRE statements
VSAM Sequential and Direct File Processing — through VSAM ESDS
and RRDS data sets.
CHARACTER data type — gives you more flexible end direct
control of character variables and arrays; this is useful
when you're using READ and WRITE statements to process
internal files.
VS FORTRAN Overview 1
Internal File Processing — lets you transfer data from one
internal storage area to another. The READ statement converts
the data from character to internal data types; the WRITE
statement converts the data from internal data types to
character data.
Structured Programming Aids — the block IF statement? plus the
INCLUDE and CONTINUE statements, makes structured code
sequences easy to implement.
Constant Names — let you name constants and define their
values once at the beginning of a program; later in the
program, a reference to the constant name is a reference to
that value.
In addition, VS FORTRAN lets you write your source programs in
either free or fixed format, lets you use the standard language
flagger to identify nonstandard source language elements in your
programs, and gives you diagnostics that are more informative
than ever before.
VS FORTRAN PUBLICATIONS
The VS FORTRAN publications are designed to help you develop your
programs with a minimum of wasted effort.
This book, VS FORTRAN Application Programming* Guide , gives
guidance information on designing, coding, debugging, testing,
and executing VS FORTRAN programs written at the current language
level. It is not intended to be used as a reference manual.
A series of related publications give you detailed reference
documentation you can use when you're actually performing the
tasks this manual describes:
VS FORTRAN Application Programming '
Language Reference manual, GC26-3986 — gives you the semantic [
rules for coding VS FORTRAN programs when you're using
current FORTRAN. This manual also documents the differences
between the old FORTRAN language and the current FORTRAN
language.
Library Reference manual, SC26-3989 — gives you detailed
information about the execution-time library subroutines.
System Services Reference Supplement , SC26-3988 — gives you
FORTRAN-speci f i c reference documentation for the system
you're operating under.
Source-Time Reference Summary , SX26-3731 — is a pocket-sized
reference card containing current language formats and brief
descriptions of the compiler options.
Svstem/360 and Svstem/370 FORTRAN IV Language manual,
GC28-6515 — gives you the rules for writing VS FORTRAN programs
when you're using old FORTRAN.
Figure 1 shows how these manuals should be used together.
VS FORTRAN Application Programming* Guide
f>\
Application Programming Publications
Design
and code
FORTRAN IV
Language
Reference
Appli cati on
Programme ng
Gui de
VS FORTRAN
Language
Reference
System Services
Reference
Supplement
VS FORTRAN
Reference
Summary
Compi le, _
link* and
execute
Library
Reference
o
Figure 1. VS FORTRAN Application Programming Publications
IBM EXTENSION DOCUMENTATION
Sections of this manual describe VS FORTRAN source language
usage, both usage of standard language and of IBM language
extensions. The IBM extensions are indicated in the following
ways :
IBM EXTENSION
In text, the IBM source language extensions are documented as
this paragraph is shown.
END OF IBM EXTENSION
In examples and figures, IBM extensions are boxed, as shown in
Figure 2.
Data Type
Valid Storage Lengths
Default Length
Integer
2 or 4
\J>
Figure 2. IBM Extensions in Examples and Figures
VS FORTRAN Overview
*%^jp
Jf^^
o
PART 1 — SIMPLIFIED FORTRAN PROGRAMMING
If you are a student, or a scientist, engineer, or other
professional who uses FORTRAN only as a tool for problem solving,
this part of this manual is meant for you. It gives you the
simpler Nays of using current VS FORTRAN, without documenting
data processing details you don't need.
This part is divided into seven sections, which guide you through
the seven steps to follow when developing any VS FORTRAN program?
1. "Designing Your Program — Simplified Programming"
2. "Coding Your Program — Simplified Programming"
3. "Compiling Your Program — Simplified Programming"
4. "Fixing Compile-time Errors — Simplified Programming"
5. "Link-Editing Your Program — Simplified Programming"
6. "Executing Your Program — Simplified Programming"
7. "Fixing Execution-Time Errors — Simplified Programming"
If you find errors in your program at step 4 or 7, you must repeat
the earlier steps. If you don't find any errors, you can of course
omit steps 4 and 7.
The sample program at the end of this part illustrates how you can
use VS FORTRAN to program a problem solution.
Most of the examples in the text for this part are taken from this
sample program.
Part 1 — Simplified FORTRAN Programming
DESIGNING YOUR PROGRAM—SIMPLIFIED PROGRAMMING
Before you begin coding any FORTRAN program* you should first
consider what you want your program to do and the best way to do
it. Every program has a purpose, and that purpose should guide its
design.
Typically, a program reads some data, processes it, and then
writes out the results of the processing. Thus, it's convenient to
think of your program's structure in these three blocks and, in
your logic structure, to take account of each block*
1. Reading in the data — know where the data will come from and
the form it will have once you retrieve it.
uw rv ■ vi ■
o DpM....:.. the " J at3"
order in which you must do it, to get the results you're
looking for. Consider the calculations you must code and
their order, tests, loops, assignments, and so forth.
3. Writing out the results — decide where to print or record
them.
Once you've decided the purpose, you must consider how your
FORTRAN program can best be structured to meet the purpose you
have in mind. After you have a general idea of how your program
will be structured, it's a good idea to write a step-by-step
picture of its logic* possibly through a brief outline or a flow
chart.
Now you're ready to go to the next step, "Coding Your
Program — Simpli f i ed Programming."
^_y
O
VS FORTRAN Application Programming* Guide
CODING YOUR PROGRAM — SIMPLIFIED PROGRAMMING
BEFORE YOU BEGIN
Once you've drawn up an overall design for your program* you can
use VS FORTRAN to implement your design, statement by statement.
The result i s a VS FORTRAN program, a logical solution to your
problem; this program is called the source program — because you
write it in a source language, in this case FORTRAN.
Every FORTRAN program is made up of three elements ' data,
expressions, and statements*
Data is a collection of factual items. In FORTRAN, these data
items are represented by variables, constants, and arrays.
Expressi ons are written representations of data
relationships. The simplest form of an expression is the name
of a single data item; through the use of operators (for
example, arithmetic symbols), you can express more
complicated forms of data relationships.
Statements use data and expressions to tell the FORTRAN
compiler what to do. There are two kinds of statements?
Nonexecutable Statements specify the nature of data you
want to process or define the characteristics of your
source program.
Executable Statements cause operations to be performed.
All of these FORTRAN source program elements are explained in more
detail later in this chapter.
In coding your program, you must follow the rules of the level of
VS FORTRAN you're using:
• If you're coding a new VS FORTRAN program, use the VS FORTRAN
Application Programming: Language Reference manual.
•' If you're updating an existing FORTRAN IV program, use the IBM
Svstem/366 and Svstem/370 FORTRAN IV Language manual.
The easiest way to code FORTRAN programs i s by using the
preprinted F ORTRAN Coding Form ; it's specially designed to help
guide you in program coding.
The rules for writing VS FORTRAN fixed-form programs are easy to
follow when you use the coding form.
IBM EXTENSION
In VS FORTRAN, you can also use free-form input — which frees
you of many of the restrictions imposed by fixed form.
END OF IBM EXTENSION
Programming rules for coding VS FORTRAN source language
statements are given in the VS FORTRAN Application Programming'
Language Reference manual.
RETRIEVING DATA — THE READ STATEMENT
o
Your program probably retrieves data that it needs for
processing; if it does, your program must use a READ statement.
Coding Your Program — Simplified Programming
In the READ statement* you tell the system the unit from which you )
want the data retrieved, and the data items in which you want the /kT>/
data placed. For example: u j
READ(UNIT=5)CHARI0
The meaning of each part of this READ statement is*
The word READ tells the compiler that you want to retrieve
some data.
UNIT=5 identifies the unit that contains the data you want to
retrieve. (The unit number 5 is only an example of a valid
unit number; check with your system administrator for unit
numbers that you can use with READ statements.)
CHARIO is a variable you've defined within your program and,
in which you want the retrieved data placed. (Variables are
uaia i i€iii5 viiav. Com CiiaPiCJS in VSiviS uU"i("g progpairi
execution.)
When your READ statement is executed, the next item of data on the
input device is placed in variable CHARIO.
CONVERTING CHARACTER DATA — INTERNAL READ STATEMENT
DEFINING DATA
^K.^
The preceding external READ statement transfers data into your
storage without any data conversions.
If your input data comes from your terminal, or from the system
card reader, you must then convert the external data (which is in
character format — one byte per character) into an internal format
your program can use.
You can use an internal READ statement to perform the conversion.
For example^
READ (UNIT=CHARIO, FMT= » (F3. 1 ) » ) DELTBS
The meaning of each part of this READ statement is-
The word READ tells the compiler that you want to retrieve
some data.
UNIT=CHARIO identifies the data item CHARIO as the unit that
contains the character data you want to convert.
FMTs'CFS.D" gives the compiler the following information-
FMT= the following codes refer to formatting information.
F the input data i s to be converted to real internal
format; that is, a real number in floating-point
notation, four bytes in length.
3.1 the input character data is contained in three bytes,
with one place as a decimal fraction.
DELTBS tells the compiler to store the converted data in the
real data item named DELTBS in which you want the retrieved
data placed.
Programming rules for coding the READ statement are given in the
VS FORTRAN Application Programming^ Language Reference manual .
All the data you use in a VS FORTRAN program— like the variables 4~~\)
defined in the preceding READ statements, or program constants, il
or arrays— must be defined to the program. The following ^
paragraphs tell you how to define all of them.
t.y
VS FORTRAN Application Programming* Guide
VS FORTRAN DATA TYPES
^\
DEFINING DATA ITEMS
When you're writing a VS FORTRAN program, you must define all the
data you use — its type and its organization. Your definitions can
use default values or can be explicit.
The data types you'll most often use are?
Integer items — made up of whole numbers. They can be signed or
unsigned.
Real items — numbers that contain either a decimal point or an
exponent. They can be fractional; they can be signed or
unsi gned.
Complex items — a pair of integer or real items, written
within parentheses and separated by a comma. The first item is
the real part of the complex number; the second item is the
imaginary part. Either item can be signed or unsigned.
Character items — made up of any characters in the computer's
character set.
Use integer, real, and complex items in mathematical or
relational expressions. Use character items in character
expressions.
In storage, integer items are represented as binary fixed-point
numbers; real and complex items are represented as floating-point
numbers; character items are represented as one byte for each
character in the item.
Reference documentation for these data types is given in the VS
FORTRAN Application Programming? language Reference manual.
You must define every data item you use in your VS FORTRAN
program, such as the variable DELTBS in the example above, either
through predetermined definitions or through explicit
definitions.
Predetermined Data Type Definition
You can define data items (such as the DELTBS variable) by simply
coding them in your READ statement (or any other executable
statement) .
FORTRAN then assigns a data type, predetermined by the initial
character of the name, as follows*
• Names beginning with characters I through N &re predefined as
integer items of length 4.
• Names beginning with any other alphabetic character are
predefined as real items of length 4.
IBM EXTENSION
Names beginning with the currency symbol ($) ere predefined
as real items of length 4.
END OF IBM EXTENSION
(In the preceding example, the VS FORTRAN compiler assumes you
want the variable DELTBS defined as a real item of length 4.)
These are the only data types that FORTRAN can predetermine for
you.
Coding Your Program — Simplified Programming
Explicit Data Type Definition
You can define data items explicitly through the IMPLICIT
statement and through explicit type statements.
USING THE IMPLICIT STATEMENT: Use the IMPLICIT statement to type
groups of items, according to the initial character of their
names. For example:
IMPLICIT CHARACTERX15 (C)
specifies that any item whose initial character is C is a
CHARACTER item of length 15, with one exception. The exception is-
that explicitly typed items are not included; that is, explicit
typing overrides both IMPLICIT type definitions and predetermined
type definitions.
ijcTug EXPLICIT TYPE STATEMENTS* Use explicit t w ~e statements tc '
define the data type for specific data items. For example'
I IBM EXTENSION
REAL*8 S(50),T(50),W(50),CM2
This statement defines the variables as follows*
• REALMS is a type definition that specifies CM2 as a real
variable of length 8, and S, T, and W as real arrayar each
element of which is of length 8.< (Arrays and array elements
are explained later in this chapter.)
END OF IBM EXTENSION
There are several other data types you can explicitly define*
• REAL defines data items as real items of length 4 . V )
• INTEGER defines data items as integer variables of length 4.
• CHARACTER defines data items as character variables.
• DOUBLE PRECISION defines data items as items of length 8.
• COMPLEX defines data items as complex numbers.
If you include the preceding IMPLICIT statement and this explicit
type statement in one program, the program data items are typed as
follows!
Names
S, T, W
Other names beginning with S,T,W
Names beginning with A,B
CM2
Other names beginning with C
Names beginning with D thru H
Names beginning with I thru N
Names beginning with thru Z
IBM EXTENSION
Data Type
Length
REAL
8
REAL
4
REAL
<*
REAL
8
CHARACTER
15
REAL
4
INTEGER
4
REAL
i
4
Names beginning with $ REAL
: — — ■ END OF IBM EXTENSION -
Programming rules for explicit type statements and the IMPLICIT
statement are given in the VS FORTRAN Application Programming**
Language Reference manual.
Note: In this manual, unless the example description explicitly
states otherwise, examples use the predetermined type definition*
for all data items.
vV
10 VS FORTRAN Applicati on Programming* Guide
DEFINING PROGRAM CONSTANTS
There are two ways to define constants in your program. You can
state their values directly* or you can define them through names.
Using Program Constants Directly
O
You can define program constants directly by using their values
within the program. For example, if you code:
TZ = I - 1
you've defined the value 1 as en integer constant of length 4.
However, if you code :
TZ = I - 1.0
you define the value 1.0 as a real constant of length 4. (Because
your statement uses integer data, it's better if you define the
constant as an integer constant; however, it isn't necessary.)
You can also define character constants — a group of characters,
enclosed in apostrophes, that the program treats exactly as
you've specified. For example?
' TC11 FAILED '
is treated by the program as*
bTCllbFAILEDbbb
(Note that the program does not include the apostrophes as part of
the character constant; however, it does include the trailing
blanks enclosed within the apostrophes. In this example the
blanks sre shown as a series of 'b's — however, in actual program
output they would appear as spaces.)
Programming rules for program constants, are given in the VS
FORTRAN Application Programming? Language Reference manual.
Using Names for Program Constants
Suppose that your program must refer frequently to a particular
constant value. In such a case, it may be more convenient to give
the value a name and then use the name to refer to the value
throughout the rest of the program.
In VS FORTRAN, you can use implicit or explicit type definitions
and the PARAMETER statement for this purpose. For example*
PARAMETER(CM2=0.0001D0)
The CM2 in this example has been previously defined as a real item
of length 8. This PARAMETER statement now defines CM2 as a
constant with the value 0.0001. The D in the constant specifies
that the value has the precision of a REAL item of length 8.
Once you've defined CM2 as the name of a constant, you can use the
name CM2 throughout the program in references to the value 0.0001;
for example*
21 IF (W(J-l) - W(J) - CM2) 23,16,16
The compiler treats this statement as exactly equivalent to*
21 IF (W(J-l) - W(J) - 0.0001) 23,16,16
You can use the PARAMETER statement to define constants of the
following data types: INTEGER, REAL, DOUBLE PRECISION, COMPLEX,
LOGICAL, or CHARACTER.
Coding Your Program — Simplified Programming 11
I IBM EXTENSION
You can also use the PARAMETER statement to define constants of
the following data types: REAL*8, REAL*16, C0MPLEX*32,
INTEGERS, or LOGICAL*!.
END OF IBM EXTENSION
Programming rules for program constants and for the PARAMETER
statement are given in the VS FORTRAN Application Programming:
Language Reference manual.
Program Reference Points — Using statement Numbers
The "21" in the previous examples is a statement number. It serves
as a reference point for other statements in the program — such as
the logical Ir statement described later in this chapter.
DEFINING ARRAYS AND SUBSCRIPTS
In FORTRAN* an array is a named set of data items, called array
elements. Each array element in the set is the same size and has
the same data characteri sti cs as all the others; each element can
be referred to in your program through subscripts 5
7 DELS = S(l) - P
The (1) is a subscript, and tells the program you f re referring to
the first array element in the array named S.
You use names to identify arrays; you can implicitly or explicitly
define the data type of an array in the same way as variables or
program constants. For example* f 1 ^^)'
I IBM EXTENSION ,
REAL*8 S(50),T(50),W(50),CM2
The preceding statement defines S, T, and W as REAL arrays, each
containing 50 array elements; each array element is a REAL item
of length 8. (CM2 is the program constant previously
descr i bed. )
1 END OF IBM EXTENSION '
Defining and Referring to One-Dimansional Arrays
A one-dimensional array has a series of elements, each contiguous
with the others and each the same size as the others. For example,
suppose that in ARRAY1 there are four elements, containing the
values 5, 10, 15, and 20, respectively.
You can define this array through a DIMENSION statement:
DIMENSION ARRAYK4)
In this DIMENSION statement, you've defined ARRAY1 as a
one-dimensional array containing four elements, each implicitly
defined as a real item of length 4.
Your program can then refer to the elements in ARRAY1, using
subscripts (integers enclosed in parentheses), as follows:
ARRAY1
(1)
refers
to
the
element
wi th
value
5
ARRAY1
(2)
refers
to
the
element
wi th
value
10
ARRAY1
(3)
refers
to
the
element
wi th
value
15
ARRAY1
(4)
refers
to
the
element
wi th
value
20
(Note that if you refer to ARRAY1 without specifying any
subscripts you are making a collective reference to all four array
12 VS FORTRAN Application Programming: Guide
elements. For most program references, this isn't valid — see the
VS FORTRAN Application Programming* Language Reference manual for
restrictions.)
In VS FORTRAN, you can use an integer variable as a subscript; in
this way, you can place a new value into the variable each time
your program must make a reference to the array. For example, if
you place the value 2 in the variable ISUB1 and then specify*
ARRAY1MSUB1)
you're making a reference to ARRAYK2).
In this example, you've implicitly defined subscript ISUB1 as an
integer data item of length 4.
Defining and Referring to Multidimensional Arrays
In VS FORTRAN, you can define arrays of up to seven dimensions, in
which case, in order to refer to a specific array element, you
must specify as many subscripts as there are dimensions. For
example, the following DIMENSION statement defines an array of
two dimensions*
DIMENSION ARRAY2(4,5)
In this statement, you've defined ARRAY2 as a two-dimenional
array containing 20 elements, each implicitly defined as a real
item of length 4 .
Figure 3 shows how this array is logically laid out, with values
in each sequential element increasing from 5 by 5.
c
4,4
1,5
2,5
3,5
4,5
1 80 |
! 85 |
1 90 |
95 1
1 1001
1,1 2,1 3,1 4,1 1,2 2,2
I 5| 10 | 15 | 20 | 25 | 30 | .
Figure 3. Two-Dimensional Array — Physical Layout in Storage
As with one-dimensional arrays, you can use integer variables as
subscripts.
For example, if you place the value 2 in subscript ISUB1 and the
value 5 in the subscript ISUB2, then the following reference*
ARRAY2 (ISUB1,ISUB2).
is a reference to ARRAY2(2,5) — the element containing the value
90.
When you must make sequential references to one array element
after* another, the value of the first subscript increases most
rapidly, and the value of the last subscript increases least
rapidly.
Programming rules for arrays and subscripts are given in the VS
FORTRAN Application Programming* Language Reference manual.
USING THE ASSIGNMENT STATEMENT
Once your program defines the data it will access, you can use the
assignment statement to manipulate it.
Coding Your Program — Simplified Programming 13
INITIALIZING VARIABLES — ASSIGNMENT STATEMENT
Before you use any item in your program, you must place a valid
value in it. The READ statement in "Retrieving Data — The READ
Statement" does so for the variable DELTBS? the PARAMETER
statement does so for named constants. For variables, you can also
use the assignment statement to initialize values.
For example, the following assignment statements
CHAR1 = * TCU FAILED •
CHAR2 = * TC11 COMPLETED'
initialize CHAR1 to the character value " TC11 FAILED " and
CHAR2 to the character value " TC11 COMPLETED".
Note that the blanks shown are included as part of the character
values.
USING ARITHMETIC EXPRESSIONS IN ASSIGNMENT STATEMENTS
You can also use the assignment statement to evaluate arithmetic
expressi ons :
10 DELT= 0.1 * DELT
When you use the assignment statement in this manner, you're using
it much as you would any mathematical equation.
However, the assignment statement always tells the compiler to
evaluate the expression to the right of the equal sign and to
place the result in the item to its left.
Thus, in this example it's valid to multiply the current value of
DELT by 0.1 and to place the result back into DELT.
The preceding rule also ensures that the two following statements ""^
are not equivalent*
DELT= 0.1 x DELT (valid FORTRAN statement)
DELT x 0.1 = DELT (statement in erroi
cannot be compiled)
In addition, you must specify all computations explicitly. That
is, if you specify the two variables A and B, as follows*
AB
the two variables are not multiplied; instead, they're considered
one variable, with the name AB. To multiply A and B, you must
speci fy*
A x B
or
B * A
The arithmetic operators you can use in mathematical expressions,
and the order in which they're evaluated, are shown in Figure 4.
14 VS FORTRAN Application Programming: Guide
"%
Operation
Arithmetic
Operator
Order of
Evaluation
Evaluation of Functions (none)
Exponentiation **
Multipl icati on
Di vi si on
First
Second
Third
Third
Addi ti on
Subtracti on
Fourth
Fourth
Figure 4. Arithmetic Operators and Operations
The VS FORTRAN compiler always evaluates mathematical expressions
in this order* with the following additional considerations
(important to remember because otherwise you may get results you
don ' t expect) :
• Within the exponentiation evaluation level , operations are
performed right to left; within all other evaluation levels *
operations are performed left to right.
• Parentheses are evaluated as they are in mathematics; they
specify the order in which operations are to be performed.
That is* expressions within parentheses are evaluated before
the result is used. For example, the expression ((A-B)+C)*E
is evaluated as follows*
1. A-B is evaluated* giving resultl
2. resultl +C is evaluated* giving result2
3. result2 *E is evaluated* giving the final result
Don't attempt to write two arithmetic operators consecutively in
the same expression. The following expression is invalid?
A * -B
because the compiler cannot evaluate it properly. If you want to
multiply A by -B* you can write*
A * (-B)
then -B is evaluated and the result is multiplied by A.
Programming rules for the assignment statement are given in the VS
FORTRAN Application Programming* language Reference manual.
USING INTRINSIC FUNCTIONS
The arithmetic operators allow you to code simple arithmetic
operations easily. More complex arithmetic operations would be
difficult to code.
However* VS FORTRAN has a set of mathematical functions you can
use to perform specific operations. For example* to obtain and use
the square root of real item ALG in an equation* you can write*
Coding Your Program — Simplified Programming
15
REL = INT1 + SQRT(ALG)
This statement causes VS FORTRAN to obtain the square root of ALG,
add it to INT1, and place the result in REL.
Mathematical functions you can use include logarithmic,
exponential, trigonometric, and hyberbolic functions, as well as
functions that determine maximum and minimum values.
The mathematical functions are fully described in the VS FORTRAN
Application Programming? Library Reference manual.
CONTROLLING PROGRAM FLOU
In a VS FORTRAN program, statements are ordinarily executed one
after another, just as they appear in the program. However, VS
FORTRAN lets you change the order of execution through FORTRAN
control statements — which include the arithmetic and logical IF
statements and the DO statement.
PROGRAMMING ALTERNATIVE EXECUTION PATHS — ARITHMETIC IF STATEMENT
Programs you write must often decide on alternative paths of
execution, depending on the results of some previous action.
The arithmetic IF statement provides this function for your
programs. For example, the following IF statement?
IF (J - 2) 20,21,20
tells the FORTRAN compiler to?
1. Evaluate the expression (J - 2). (The expression can be any
arithmetic expression.)
2. If the result is less than zero, transfer control to statement
number 20 .
3. If the result is equal to zero, transfer control to statement
number 21 .
4. If the result is greater than zero, transfer control to
statement number 20.
PROGRAMMING ALTERNATIVE EXECUTION PATHS — LOGICAL IF STATEMENT
Another way to program alternative paths of execution, in this
case depending on the evaluation of some condition, is through the
logical IF statement. For example, the following IF statement?
IF (TZ.EQ.5.0) GO TO 25
tells the FORTRAN compiler to?
1. Evaluate the expression
(TZ.EQ.5.0)
which is a relational expression telling FORTRAN to test
whether or not the value in variable TZ is equal to 5.0. If TZ
is equal to 5.0, the expression is "true"; if TZ is not equal
to 5.0, the expression is "false."
(The expressi on can be any relational or logical expression.)
2. If the result of the evaluation is "true," transfer control to \
statement 25. /f~V/
3. If the result of the evaluation is "false," transfer control
to the next executable statement following this IF statement.
- -Jr
16 VS FORTRAN Application Programming? Guide
c
Programming rules for the IF statement are given in the VS FORTRAN
Application Programming* Language Reference manual.
EXECUTING PROCEDURES REPETITIVELY — DO STATEMENT
Another powerful control statement — the DO statement — lets you
repetitively execute a whole series of statements a given number
of times and then exit to continue sequential processing.
The DO statement is particularly useful when you want to
initialize all of the items in an array.
Processing One-Dimensional Arrays — DO Statement
For example* you want to read a specific set of values into
ARRAYO, depending on the current contents pf ARRAY1 . The DO
statement in the following example sets up the loop to process
each array element in turn*
DOUBLE PRECISION ARRAYO
DIMENSION ARRAY0(4), ARRAYK4)
DO 40 INT=1,4,1
(code to set values in ARRAYO,
using values from ARRAY1)
o
40 CONTINUE
This DO statement tells FORTRAN to execute the code to set values
in ARRAYO (that is, the code intervening between the DO statement
and statement number 40) 4 times, as follows*
1. The program is to set INT to the value 1 (INT = 1 tells it
this).
2. The program is to execute the code sequence until INT equals 4
(INT=1,4 tells it this).
3. Each time the code sequence is executed, the value of INT is
to be incremented by 1 (INT=1,4,1 tells it this).
Thus, the code sequence will be executed four times, and then the
next statement after statement number 40 will be executed.
Processing Multidimensional Arrays — Nested DO statement
You can include DO statements completely within the range of a DO
loop — that is, among the statements within the range that the
initial DO statement controls. You can use this FORTRAN feature to
initialize multidimensional arrays. The DO statements in the
following example show how it's done*
Coding Your Program — Simplified Programming 17
DIMENSION ARRAY2 (4,5)
VALU =0.0
DO 40 ISUB2=1,5,1
DO 40 ISUB1=1,4,1
ARRAY2(ISUB1,ISUB2)=VALU
VALU=VALU + 1.0
40 CONTINUE
The first DO statement varies the second subscript from its
minimum to its maximum value. The second DO statement varies the
first subscript from its minimum to its maximum value as the first
subscript is set to each of its specified values. When you specify
these two DO statements in this order, your program places
ascending values in each array element in sequence.
For a four-dimensional table, you'd specify
1. A DO statement controlling references to the fourth
subscri pt .
2. Contained in that DO statement's range would be a second DO
statement controlling references to the third subscript.
3. Contained in that DO statement's range would be a third DO
statement controlling references to the second subscript.
4. Contained in that DO statement's range would be a last DO
statement controlling references to the first subscript.
Programming rules for the DO statement are given in the VS FORTRAN
Application Programming' Language Reference manual.
^s
OBTAINING RESULTS — USING THE WRITE STATEMENT
To print or display the results of your program, use the WRITE
statement .
For example, your program develops two values. TZ and V, which it
then uses to test how the program plots a curve. At the end of
execution, you'll want to save these values. The following
example shows how you can do this*
WRITE (UNIT=8) TZ.V
The meaning of each part of this WRITE statement is«*
WRITE tells FORTRAN that your program is to output some
information, in this case on an external device.
IUNIT=8) specifies that the information produced by the write
statement wi 11 be sent to the output device identified by this
unit number. (The unit number 8 is only an example; check with
your system administrator for valid unit numbers you can use
with the WRITE statement.)
TZ and V ar& the data items to be written to the output
device.
The WRITE statement sends the data contained in each item listed,
and in the order the items are specified.
Reference documentation for the WRITE statement is given in the VS
FORTRAN Appli cati on Programming? language Reference manual .
18 VS FORTRAN Application Programming! Guide
ENDING YOUR PROGRAM — END STATEMENT
Once your program has completed all the processing you want done,
you must tell the VS FORTRAN compiler that there are no further
statements to process.
You do this through the END statement, which is an executable
statement and which must be the last statement on the last line in
your program. For example?
27 END
The statement number (27) on this statement allows you to transfer
control to this END statement from various parts of the program.
When the END statement is executed, program execution is ended,
and control is returned to the system.
Programming rules for the END statement are given in the VS
FORTRAN Application Programming' Language Reference manual.
COD ING ERRORS TO AVOI D
o
While you're coding your program, be careful not to make these
common programming errors*'
1. Misspelling FORTRAN words and data names.
2. Omitting required punctuation.
3. Not observing FORTRAN formatting rules.
4. Forgetting to assign values to variables and arrays before
you use them.
5. Moving data into an item that's too small for it. (This causes
truncati on. )
6. Branching into DO loops from other areas in the program.
Errors like these can either prevent your program from executing
at all or may cause your program to produce erroneous output. For
many of these errors, you'll get compi lati on messages explaining
what's wrong; for others, you may not get any error messages,
because the error won't become evident until you actually execute
the program.
You can quite often detect misspellings and uninitialized items
by examining the source program map and the cross-reference
li st i ng.
Once your program is coded, you use the VS FORTRAN compiler to
compile it, that is, to translate it into machine code. This is
explained in "Compiling Your Program — Simplified Programming."
Coding Your Program — Simplified Programming 19
COMPILING YOUR PROGRAM— SIMPLIFIED PROGRAMHING
Your VS FORTRAN source program is meaningful to you, but it means
nothing to the computer, which understands only a language known
as machi ne code.
For this reason, you must compile your program. That is, you must
request the VS FORTRAN compiler program to translate your FORTRAN
source statements into an "object module" — a machine code
translation of your source program.
ENTERING YOUR SOURCE PROGRAM
Your first step is to enter your source program into the system.
You can, for example, enter the program from a terminal as a CMS
or TSO file, or you can key it onto a diskette, or into a punched
card deck.
For the method your organization uses, see your system
admi ni strator .
Whatever method your organization uses, you must submit the
source program as a file with 80-character records; each record
must follow VS FORTRAN formatting rules.
REQUESTING COMPILATION
Once you've entered your source program into the system, you can
ask the VS FORTRAN compiler to process it. When you request
compilation, the VS FORTRAN compiler reads and analyzes your
source program and translates it into machine code.
You can request compilation along with the other steps needed for
program development — link-editing and execution.
For early debugging, however, it's usually better to request a
compile-only run. That nay, the compiler can find syntax errors in
your program that would prevent a successful execution, and you
don't waste machine time and computer printout paper.
See "Using VM/370-CMS with VS FORTRAN" for information on
compiling programs under CMS.
See "Using 0S/VS2-TS0 with VS FORTRAN" for information on
compiling programs under TSO.
'^j /
REQUESTING COMPILATION ONLY— OS/VS
The easiest way to request compilation under OS/VS is to use the
VS FORTRAN cataloged procedure for compilation only.
Use the following job control statements to execute the
compile-only procedure 5
//jobname JOB
// EXEC FORTVC
//FORT.SYSIN DD *
(source program)
/x
//
where :
jobname
is the name you're giving this compilation-only job.
V
O
20 VS FORTRAN Application Programming: Guide
^h*/
See the VS FORTRAN Application Programmi ng^ System Services
Reference Supplement for more information on these job control
statements.
REQUESTING COMPILATION ONLY — DOS/VSE
COMPILER OUTPUT
c
c
The easiest way to request compilation under DOS/VSE is to use the
following job control statements?
// JOB jobname
// EXEC VFORTRAN
(source program)
/x
/*
where the source program is on SYSIPT, and 1
jobname
is the name you're giving to this compilation-only job.
See the VS FORTRAN Application Programmi ng' System Services
Reference Supplement for more information on the DOS/VSE JOB
statement.
The VS FORTRAN compiler gives you some or all of the following
output, depending on the options in effect for your organi zat i on:
• The Source Program Listing — as you entered it, but with
compilei — generated internal sequence numbers prefixed at the
left; the sequence numbers identify the line-numbers referred
to in compiler messages.
• An object module — a translation of your program in machine
code.
• Messages about the results of the compilation.
• Other listings helpful in debugging.
These listings are described fully in "Fixing Compile-Time
Errors — Advanced Programming" and "Fixing Execution-Time
Errors — Advanced Programming" in Part 2; examples of output for
each feature are also given there.
If your compilation was completed without error messages, you can
proceed to "Link-Editing Your Program — Simplified Programming."
If your compilation caused error messages, you may have to fix up
your errors, as described in "Fixing Compile-time
Errors — Simplified Programming."
Compiling Your Program — Simplified Programming 21
FIXING COMPILE-TIHE ERRORS — SIMPLIFIED PROGRAMMING
For each error it finds in your source program, the compiler gives
you a self-explanatory error message; an example of these
messages is shown in Figure 5.
*** VS FORTRAN ERROR MESSAGES ***
IFX1027I RPLC 12(S) 27 NON-SUBSCRIPTED ARRAY NAME APPEARS AS LEFT-OF-EQUAL
SIGN VARIABLE. SPECIFY A SUBSCRIPTED ARRAY NAME OR
A VARIABLE NAME.
Figure 5^ VS FORTRAN Error Msssags Exsmpls
The way the messages are printed is fixed. Each message begins
with an 8-character identifier and a 4-character pointer,
followed by a level code, followed by the internal sequence
number, followed by the message text. Each part is explained in
the following paragraphs.
MESSAGE IDENTIFIER: Each message begins with an 8-character
identifier^
IFX
identifies the message as one from the VS FORTRAN compiler.
(If the message has some other prefix, it was sent by some
other part of the system; in this case, see your system
admi ni strator . )
nnnnl
uniquely identifies this message.
^-CHARACTER POINTER: The message identifier is followed by a
^-character pointer, which is sometimes needed by system
programmers for detailed error diagnosis.
LEVEL CODE: The 4-character pointer is followed by a code, which
tells you the severity level of the message:
16(U)
for unrecoverable error. The compilation was stopped before
i t was complete.
12(S)
for severe error. The compiler cannot guarantee a
compilation that will execute correctly. The statement in
error was not processed. (Errors after this one in this same
statement couldn't be found in this compilation.)
8(E)
*(W)
0(1)
for error. The compiler found an error and attempted to
correct it; the program may or may not execute correctly.
for warning. The compiler detected a possible error in your
program.
for informational. A note giving you information about
compilei — detected conditions during compilation.
You must always correct U-level, S-level, or E-level errors ^~x )
before attempting another compilation.
\J
22 VS FORTRAN Application Programming: Guide
"Vh
You should review W-level messages to see if they'll let your
program execute correctly; if they won't, you must correct them.
I-level messages do not necessarily indicate an error in your
program. Therefore, you may not need to make any corrections
because of them.
INTERNAL SEQUENCE NUMBER (ISN): This is a compiler-generated
number showing the statement at which the error occurred. It isn't
printed if the error isn't connected with one particular
statement. (This is the sequence number prefixed to each
statement in the source program listing.)
Logical IF statements consist of two parts (heading and
trailing). Normally, an ISN is assigned is assigned to each part
of the statement. However, if the trailer is an unconditional
GOTO, it will not be assigned an ISN, because the effect of this
statement is contained in the evaluation of the header.
MESSAGE TEXT J The self-explanatory text of the message.
Using the Messages
With the information the compiler messages give you, you can go
back, correct your source program as indicated, and then
recompile your program.
When yo
hi gher
as desc
Programme ng
ur program compiles correctly (without any message levels
than I) you can go on to the next step, and link-edit it,
ribed in "Link-Editing Your Program — Simplified
tmino."
Fixing Compile-time Errors — Simplified Programming
23
LINK-EDITING YOUR PROGRAM — SIHPLIFIEP PROGRAMMING
Before you can execute your program, you must link-edit it — even
if you have only one program and want to "link" it only with the
system.
During program development when you're testing one version after
another, or if your program is one you're expecting to execute
only a few times, you can combine the link-editing step with the
execution step; see "Executing Your Program — Simplified
Programming" on how to do this.
However, if you will be executing this program many times, you
should compile and link-edit it, and then file it in a library for
future reference.
For information on link-editing under CMS, see "Using VM/370-CMS
with VS FORTRAN."
For information on link-editing under TSO, see "Using 0S/VS2-TS0
with VS FORTRAN."
REQUESTING LINK-EDITING — OS/VS
The simplest way to link-edit your program under OS/VS is to use
the cataloged procedure, which compiles and link-edits your
program all in one step. The job control statements you use are*
//jobname JOB
// EXEC FORTVCL
//FORT.SYSIN DD *
(source program)
/*
// /
where :
jobnawa
is the name you're giving this compi le-and-1 i nk-edi t job.
See the VS FORTRAN Application Programming^ System Services
Reference Supplement for more information on these job control
statements.
REQUESTING LINK-EDITING — DOS/VSE
The easiest way to request link-editing under DOS/VSE is to use
the following job control statements 1
// JOB jobname
// OPTION CATAL
PHASE FIRST,*
// EXEC VFORTRAN,SIZE=800K
(source program)
/*
// EXEC LINKEDT
/8
where the source program is on SY5IPT, and!
jobname
is the name you're giving to this compi le-and-li nk-edi t job.
OPTION CATAL
causes the system to catalog the relocatable phase (object
module) in the core image library.
V
o
24 VS FORTRAN Application Programming: Guide
PHASE FIRST, X
gives the cataloged phase the name FIRST.
See the VS FORTRAN Application Programming' System Services
Reference Supplement for more information on the DOS/VSE JOB
statement .
USING THE LINK-EDITED PROGRAM
You can catalog the output of your link-edit job and then execute
the link-edited module any time you want.
How you execute your program is described in "Executing Your
Program — Simpli f i ed Programmi ng. "
Link-Editing Your Program — Simplified Programming 25
EXECUTING YOUR PROGRAM — SIMPLIFIED PROGRAMMING
Once you've compiled your program correctly and link-edited it,
you can execute it.
The easiest way to execute it is to combine all three steps into
one: compilation* link-editing, and execution.
During testing, if your program doesn't change existing files of
data, you may want to execute it as it stands, right away.
However, if it alters valuable data files, you should develop
alternative data files for testing, and then try out program
execution, using the alternative test data files. In this way, if
there are execution errors, you won't introduce bad data into the
real f i les.
See "Using VM/370-CMS with VS FORTRAN" for information on
executing your program under CMS.
See "Using 0S/VS2-TS0 with VS FORTRAN" for information on
executing your program under TSO.
EXECUTING YOUR PROGRAM — 05/VS
SETTING UP TEST DATA FILES — OS/VS
The easiest way to set up data files for test execution is to use
standard system files for them. The standard system files, such as
SYSIN, SYSOUT, and SYSPRINT, are predefined, so that the job
control statements are very simple.
Under OS/VS, the simplest way to prepare test data files is to
develop them as 80-character records and then include them in the
input stream. You use the following job control statements:
//FTxxFOOl DD *
(your data records)
/*
where
XX
is the FORTRAN unit number for your test data file.
Note that this is not a standard system file; the standard
system files for input are named either FT05F001 or SYSIN.
,/f">y
The simplest way to execute your program under OS/VS is to use one
of the cataloged procedures 1
• Set up any test data files that you'll need, and then
• Compile, link-edit and execute your source program all in one
job
The following sections outline the job control statements to use. ^X
^i*j
26 VS FORTRAN Application Programming? Guide
c
COMPILE, LINK-EDIT, AND EXECUTE— -OS/VS
The job control statements you use are*
//jobname JOB
EXEC FORTVCLG
//FORT.SYSIN DD *
(VS FORTRAN source program)
/X
(compilation and link-edit steps executed)
//GO.SYSIN DD X
(data)
/*
(program execution step executed)
//
where 1
jobnaire
is the name you're giving this compile, link-edit/ and
execute job.
In this example* both your source program and your test data are
on the system input device (SYSIN).
For reference documentation on these job control statements, see
the VS FORTRAN Application Programming? System Services Reference
Supplement .
EXECUTING YOUR PROGRAM— DOS/VSE
Under DOS/VSE, the simplest way to execute your program is to
request compilation, link-editing, and execution outlined in the
following section :
• Set up your test data files, and then
• Compile, link-edit and execute your source program all in one
job
The following sections outline the job control statements to use.
SETTING UP TEST DATA FILES — DOS/VSE
The easiest way to set up data files for test execution is to use
standard system files for them.
Under DOS/VSE, the simplest way to prepare test data files is to
develop them in card image form, and then include them in the
input stream, following the EXEC statement. See the DOS/VSE
example in the next section.
Executing Your Program — Simplified Programming 27
COMPILE, LIHK-EDIT, AMD EXECUTE — DOS/VSE
EXECUTION OUTPUT
To request compi lati on, link-editing, and execution under
DOS/VSE, you use the following job control statements*
// JOB jobname
// OPTION LINK (to execute without saving the phase)
or
// OPTION CATAL (to execute and save the phase)
// EXEC VFORTRAN,SIZE=800K
(source program)
/*
(compilation step executed)
// EXEC LINKEDT
(link-edit step executed)
// EXEC
(data)
/*
(program execution step executed)
/*
where the source program and the test data are on the system input
device (SYSIPT), and
jobname
is the name you're giving to this job.
For reference documentation on these job control statements, see
the VS FORTRAN Application Programming* System Services Reference
Supplement .
When your program executes without errors and with the results you
expect, you've completed your job of program development.
If you find errors in your program output, and you may, you'll W^
have to go on to the next step and fix up your errors, as
described in "Fixing Execution-Time Errors — Simplified
Programming."
28 VS FORTRAN Application Programming: Guide
FIXING EXECUTION-TIME ERRORS — SIMPLIFIED PROGRAMMING
FINDING ERRORS
Your program may run the first time without any errors at all, in
which case, you've completed your job of program development.
However, you'll often discover that it contains errors, which you
must correct. The following sections outline what you must do.
If your program has errors, you'll find it out in one of three
ways i
• Your program ends prematurely, and you receive an error
message.
• Your program keeps running but never finishes execution.
• The output you're getting is not what you expect.
EXECUTION-TIME ERROR MESSAGES
o
The messages you get at execution time may be from VS FORTRAN or
from some other part of the system.
Execution-time messages from the VS FORTRAN library have message
identifiers beginning with IFY; they're presented in a format
similar to that of the compiler messages (see "Fixing
Compile-time Errors — Simplified Programming").
The text of the message usually explains what the problem is; if
you need supplementary information, you can find it in the VS
FORTRAN Application Programmi ng= L i brarv Reference manual, which
lists all the execution-time messages.
If the message has some other prefix, it comes from another part
of the system. In this case, ask your system administrator for
assi stance.
ENDLESS LOOPS OR WAITS
If your program runs on and on and never finishes, it's caught
either in a closed loop or a wait:
• A closed loop is a series of statements that repeat themselves
endlessly.
• A wai t is a suspension of execution while the program waits
for an action to occur (which may never happen).
When either result occurs, check the logic of your program:
• For Endless Loops — check for any unintentional loops; check
to make sure that e^/ery intentional loop has an exit — that it
either has a finite number of repetitions or a feasible
condition that causes execution to branch out of it.
You can also recompile and run the program again, inserting
WRITE statements to indicate when your program is entering a
specific loop, and when it is exiting from that loop.
• For Endless Waits — check that a PAUSE statement is receiving
the expected operator response, or that the operator has
provided the system resources your program expects, for
example, that a tape was mounted properly.
Fixing Execution-Time Errors — Simplified Programming 29
UNEXPECTED OUTPUT
If you can't find the cause/ even after checking these
possibilities, ask your system administrator for assistance.
If you're getting unexpected output* you may have one or more of
the following problems in your program:
• Your input or output statements (READ or WRITE) are in error.
• Your logic flow is incorrect. For example, a WRITE statement
may not be executed or may be executed at the wrong time, or a
calculation is being skipped over or executed too often.
• Your mathematical calculations themselves are in error, so
that the data is wrong when you write it.
• The input you expect is itself incorrect, so that the program
itself i s executing correctxy, uut appears to u£ in error.
• Your program constants may inadvertently be changed during
execution.
Sometimes the nature of the erroneous output tells you what is
wrong. If it doesn't, double check your source program, looking
for the kinds of errors outlined above.
Sometimes, by inspecting the source program map and the
cross-reference listing, you can find inconsistencies in the way
your program uses variables.
If you can't find the cause, even after checking these
possibilities, ask your system administrator for assistance.
USING DEBUGGING PACKETS
FIXING ERRORS
VS FORTRAN also has a number of source statements that let you ^^
define debugging packets at the beginning of your source program;
a debugging packet lets you obtain information about the
conditions existing during program execution and may help you
pinpoint where your errors are. See "Fixing Execution-Time
Errors — Advanced Programming" for further information.
If, even after using a debugging packet, you still can't find
what's wrong, ask your system administrator for assistance.
If you find errors in your program, you must go back and recode
the erroneous statements. Before you try to execute it to obtain
the desired results, you must then recompile and relink-edit it.
30 VS FORTRAN Appli cation Programming: Guide
A SAMPLE PROGRAM— SIMPLIFIED PROGRAMMING
1
The follouing sample program illustrates most of the programming
capabilities discussed in the previous chapters.
PROGRAM SAMPLE
C GENERALIZED TEST CASE
C TESTS NESTED DO, GO TO AND IF WITHIN DO, VARIABLE SUBSCRIPTS,
C MULTIPLE IFS IN SUCCESSION, PARAMETER AND IMPLICIT STATEMENTS.
C THE ROUTINE ITSELF GENERATES VARIOUS SLOPES. THE TEST
C CASE IS SELF CHECKING. SLOPE IS CALCULATED AT THE 5 POINTS ON THE
C CURVE, l.,2.,3.,4., AND 5.
IMPLICIT CHARACTER*^ (C)
REAL*8 S(50),T(50),W(50),CM2
PARAMETER (CM2 = 0. 001 DO)
CHARIO='0.1 '
CHAR1 = » TC11 FAILED »
CHAR2 = • TC11 COMPLETED'
READ(UNIT=5) CHARIO
READ(UNIT=CHARI0,FMT='(F3.1)») DELTBS
1 DO 25 1=1,6
2 TZ = I - 1
3 P = (TZ + 1.0) * (TZ *TZ>
4 DELT = DELTBS
5 T (1) = TZ + DELT
6 S (1) = (T(l) + 1.0)*(T(1)*T(1))
7 DELS = S(l) - P
8 W(l) = DELS/DELT
9 DO 16 J =2,50
10 DELT= 0.1 * DELT
11 T(J) = TZ + DELT
12 S(J) = (T(J) +1.0)*(T(J)*T(J))
13 DELS = S(J) - P
14 W(J) = DELS/DELT
19 IF (J - 2) 20,21,20
20 A = W(J-l) - W(J)
B = WU-2) - W(J-l)
IF (A - B) 21,22,22
21 IF (W(J-l) - W(J) - CM2) 23,16,16
16 CONTINUE
22 V = W(J-l)
GO TO 24
23 V = W(J)
24 IF (TZ.EQ.0.0.AND.V-0.0.GT.0.1) GO TO 26
IF (TZ.EQ.0.0) GO TO 25
IF (TZ.EQ.1.0.AND.V-5.0.GT.0.1) GO TO 26
IF (TZ.EQ.1.0) GO TO 25
IF (TZ.EQ.2.0.AND.V-16.0.GT.0.1) GO TO 26
IF (TZ.EQ.2.0) GO TO 25
IF (TZ.EQ.3.0.AND.V-33.0.GT.0.1) GO TO 26
IF (TZ.EQ.3.0) GO TO 25
IF (TZ.EQ.4.0.AND.V-56.0.GT.0.2) GO TO 26
IF (TZ.EQ.4.0) GO TO 25
IF (TZ.EQ.5.0.AND.V-85. .GT. .2) GO TO 26
IF (TZ.EQ.5.0) GO TO 25
GO TO 25
26 WRITE (FMT=100,UNIT=6) CHAR1,TZ,V
C WRITE DATA TO DISK FILE, UNFORMATTED
WRITE (UNIT=8) TZ,V
25 CONTINUE
WRITE (6,101) CHAR2
100 FORMAT (A15,» WITH TZ AND V =, RESPECTIVELY, ', F4. 1 , F12 .4)
101 FORMAT (A15)
STOP
27 END
A Sample Program — Simplified Programming 31
^t^
o
PART 2 — ADVANCED FORTRAN PROGRAMMING
If you are a programmer who uses the entire range of FORTRAN
language capabilities in coding your programs, this part of this
manual is meant for you. It tells you how to take advantage of the
current VS FORTRAN language and processing capabilities in order
to create efficient VS FORTRAN programs.
This part is divided into seven sections, to guide you through the
seven steps you follow when developing any VS FORTRAN program?
1. "Designing Your Program — Advanced Programming"
2. "Coding Your Program — Advanced Programming"
3. "Compiling Your Program — Advanced Programming"
<♦. "Fixing Compile-Time Errors — Advanced Programming"
5. "Link-Editing Your Program — Advanced Programming"
6. "Executing Your Program — Advanced Programming"
7. "Fixing Execution-Time Errors — Advanced Programming"
If you find e,rrors in your program at step 4 or 7 > you must repeat
the earlier steps. If you don't find any errors, you can of course
omit steps 4 and 7.
Program development considerations for VS FORTRAN mainline
processing are documented in this part.
Programming considerations for input and output, for calling and
called programs, for the optimization feature, for the
execution-time library, for VM-370/CMS, and for 05/VS2-TS0 are
gi ven in Part 3.
Part 2 — Advanced FORTRAN Programming 33
DESIGNING YOUR PROGRAM — ADVANCED PROGRAMMING
TOP-DOHN DESIGN AND DEVELOPMENT
Vi 4 J
Program design is your first step in application
development — when you design your program* you're setting up the
framework for a proper solution.
In your thinking, of course, you must take into account the
hardware and software available to you; for example, the
processing unit, disk drives, diskettes, tape drives, and
terminals you can use, plus the system you operate under, the
program products available, other application programs your
program can use, and sequences of code you can use in common with
other applications.
Typically, a program reads data, processes it, and then writes out
the results in one form or another. Thus, it's usually convenient
if you think of your program structure in these three blocks:
1. Reading the data. Understand where the data will come from,
and what it will look like.
2. Process the data. Know that you want to do with it — what
results you are looking for. Consider the manipulations and
repetitions to achieve them* mathematical calculations,
tests, loops, moves, and so forth.
3. Write the results. Decide where to print or record them, and
how they should look (if they're for general use, possibly add
explanatory text).
Almost every program is made up of these three basic read,
process, and write elements. However, if the application you're ^^
developing is large and complex, you may find it desirable to \
split up one or more of these basic elements into smaller, more V^
manageable units of processing logic.
If you begin your program design with these most inclusive program
elements, and then develop the logic of each successively more
detailed level of the program design, you're actually using
top-down design — one of the more powerful design tools available
to you — to solve your application problem.
When you're using top-down design and development, you can make
your program design — which usually maps out the larger
relationships between program elements — go hand in hand with the
coding effort. Used as a conscious strategy, it can make your
program development faster and more efficient. You'll do less
backtracking to fill in missing code and remove redundancies in
the program logic.
When you use top-down design and development, you code the most
inclusive logic portions of your program first, and test and debug
them. Then, you code the next successively lower logic portions
and add them to the portions that are already up and running. At
each level, you can code in stubs to represent the next lower
logic level.
A stub is a place holder for an unwritten sequence of code — for
example, something as simple as a comment stating what the code
will do, or something as elaborate as a complete description of
its processing logic together with portions of completed code.
In this way, when you add new modules of code, you're adding them
to code that you've already tested and debugged. You'll usually /f^
find errors only within the new code itself or in the ^y
interconnections between the new and the already existing code.
34 VS FORTRAN Application Programming* Guide
C
You'll find a number of advantages in using this development
strategy:
• You'll detect design logic errors very early. This is because
you're integrating the program's functions as you develop it.
• You'll detect and locate coding errors easily. Any error that
appears in a newly developed sequence of code is usually
within the newly developed sequence itself , or in the
interconnections between the new sequence and the old ones.
• Your program testing begins earlier in the development cycle*
since you test each new module as you add it.
• You don't need temporary drivers to test uncompleted code. (A
driver is a temporary control module not used in the completed
program.) Your control modules are at the highest logic
level, and they are the first modules you'll complete and
test.
By breaking up a large program into smaller logic modules, you get
other added advantages. You make the overall logic of the program
more apparent, so that it's easier to read, easier to understand,
easier to implement, and easier to change.
Figure 6 illustrates the top-down design and development
strategy. In the figure, the following points apply:
1. Module A is the highest-level module of all. It controls
modules B, C, and D.
2. Modules A, B, C, E, and G have been developed and tested.
3. Module B is related to lower-level modules E
(fully-developed) and F (which is an undeveloped stub).
4. Module C is related to lower-level module G
(fully-developed).
5. Stub module D is related to stub proposed submodules H and I.
Stub module D has been written as a stub; stub modules H and I
are provided for in the program design but haven't yet been
written, even as stubs.
6. Even though it's functionally incomplete, this program will
execute to its logical end.
Designing Your Program — Advanced Programming 35
O,/
Stub D
Stub F
Stub H
Stub I
Figure 6. Example of Top-Down Program Design
Once you have a design and program development strategy worked
out, you're ready to proceed to the next task in application
development: writing your source program.
USING TOP-DOWN DESIGN IN VS FORTRAN
To help you use top-down design and development, VS FORTRAN
provides*
IBM EXTENSION
• The nested INCLUDE statement
1 END OF IBM EXTENSION
• SUBROUTINE and FUNCTION Subprograms
I IBM EXTENSION
*%_jp
TOP-DOWN DESIGN WITH A SINGLE OBJECT MODULE— INCLUDE STATEMENT
In VS FORTRAN, you can nest INCLUDE statements to as many as
16, This lets you take advantage of top-down design in a
program that you want to compile as one object module. This is
how you do i t '
Write the highest-level sequences of code in your program
first j these sequences contain INCLUDE statements for the
lower — level code sequences.
During early program development, these INCLUDE statements
can point to undeveloped stubs that stand in for the
lowei — level code.
Later in program development, these same INCLUDE
statements can point to the completed code sequence.
Because INCLUDE statements can be nested, you can code
INCLUDE statements at every code sequence level in your
o
36 VS FORTRAN Application Programming 1 Guide
^*"*lk
program. For example, in the program shown in Figure 6, you
could code the following INCLUDE statements*
1. Code Sequence A could contain 1
INCLUDE (B) (B contains tested and debugged code)
INCLUDE (C) (C contains tested and debugged code)
INCLUDE (D) (D is a stub, to be replaced later)
2. Code Sequence B could contain*
INCLUDE (E) (E contains tested and debugged code)
INCLUDE (F) (F is a stub, to be replaced later)
3. Code Sequence C could contain*
INCLUDE (G) (G contains tested and debugged code)
4. Code Sequence D is a stub; later it could contain*
INCLUDE (H) (H is not yet written, even as a stub)
INCLUDE (I). (I is not yet written, even as a stub)
You get two advantages when you use the INCLUDE statement in
thi s way*
• You can produce a program structure that's syntactically
correct and that you can compile correctly, even before
you've completed all the coding.
• You avoid the execution overhead that CALL statement
linkages entail (although there is some extra compile-time
overhead) .
END OF IBM EXTENSION
TOP-DOWN DESIGN WITH MULTIPLE OBJECT MODULES — USING SUBPROGRAMS
For large or complex programs, you can use SUBROUTINE or FUNCTION
subprograms to separately code logically distinct portions of
your program. Each subprogram is a complete program within
itself, each subprogram communicating with the others through
the parameters they pass and through COMMON data areas.
During program development, you'd develop and code the highest
level control modules first. In the control modules you can code
statements that invoke the next lower level subprograms. During
early development, these subprograms could be stubs; later, they
could be completed subprograms.
Using this method, you can produce a program structure that's
syntactically correct and that you can compile and link-edit
correctly, even at the earliest stages of program development.
, Once you've developed all the programs, you can link-edit them
together into one load module.
Designing Your Program — Advanced Programming
37
CODING YOUR PROGRAM — ADVANCED PROGRAMMING
Once you've completed your program design, you can use the VS
FORTRAN language to create a source program, a logical solution
to your problem that follows your program design.
Every FORTRAN program is made up of three elements' data,
expressions, and statements'
Data is a collection of factual items. In FORTRAN, these data
items are represented by variables, constants, and arrays.
Expressi ons are written representations of data
relationships. The simplest form of an expression is the
name of a single data item; through the use of operators (for
SXaitip^e, 5P1 t,iiinSk i C 3yi"u0i5; j y'Ou Can SXpP £35 ImOPS
complicated forms of data relationships.
Statements use data and expressions to tell the FORTRAN
compiler what the object program must do. There are two kinds
of statements'
Nonexecutable Statements specify the nature of data you
want to process or define the characteristics of your
source program or define the way in which data is to be
read or wri tten.
Executable Statements cause operations to be performed.
All of these FORTRAN source program elements are explained in
more detail later in this chapter.
In coding your program, you must follow the rules of the level of
VS FORTRAN you're using'
• If you're coding a new VS FORTRAN program, use the VS FORTRAN
Application Programming' Language Reference manual.
• If you're updating an existing FORTRAN IV program, use the
IBM Svstem/360 and Svstem/370 FORTRAN IV Language manual.
USING FIXED-FORM INPUT— FORTRAN CODING FORM
Fixed-form input is the traditional way to code FORTRAN
programs; the FORTRAN Coding Form is designed to help guide you
in fixed-form program preparation.
For reference documentation about VS FORTRAN fixed-form input,
see the VS FORTRAN Application Programming' Language Reference
manual.
I IBM EXTENSION
USING FREE-FORM INPUT
In VS FORTRAN, you can also use free-form input — which gets
rid of many restrictions imposed by fixed-format input.
Free-form input is particularly useful if you're coding your
programs at a terminal; there's no artifical dependence on
80-character card image format. Although all your source
program records are 80 characters in length, you can break each
statement (and line of your program) at any convenient logical
point.
/f~V
^J^
r_> \ )
38 VS FORTRAN Application Programming' Guide
r*^
Reference documentation for VS FORTRAN free-form input is given
' n the VS FORTRAN Application Programming' Language Reference
manual.
END OF IBM EXTENSION
DEFINING DATA
When you're writing a VS FORTRAN program, you must define all the
data you use — its type and its organization. Your definitions
can depend upon predetermined definitions or they can be
explici t .
The data type can be integer, real, complex, logical, or
character. In your source program, you code them as described in
the following paragraphs.
Integer items are made up of whole numbers. They can be signed or
unsigned.
Real items are numbers that must contain either a decimal point
or an exponent. They can be fractional; they can be signed or
unsi gned.
Comple x items are represented by a pair of items (either of which
can be real or integer) written wi thi n parentheses and separated
by a comma. The first item is the real part of the complex
number; the second item is the imaginary part. Either item can be
signed or unsigned. A complex item is converted to a pair of real
items of the appropriate length.
You use integer, real, and complex items in mathematical or
relational expressions.
Logi cal items have a value of either "true" or "false." You use
logical items only in logical expressions.
Character items can be made up of any characters in the
computer's character set. You use character items in character
and relational expressions.
Figure 7 shows the lengths valid for each data type.
Reference documentation for these data types is given in the VS
FORTRAN Application Programming' Language Reference manual.
Data Type
Valid Storage
Lengths
Default
Length
Integer
2 or
<j
Real <
Complex \
♦ , 8
I, 16
or 16
or 32
Character
L throi
jgh 500
Logi cal
1 or
<t
Figure 7. Data Types and Valid Lengths
You define the data type of an item either through implicit
naming conventions or through explicit definitions.
Coding Your Program — Advanced Programming
39
PREDETERMINED DATA TYPE DEFINITION
In VS FORTRAN* if you don't otherwise define a named item, it's
given a data type, depending on the initial letter of its name:
Items whose names begin with I through N are integer items of
length 4.
Items whose names begin with any other letter ar& real items
of length 4.
IBM EXTENSION
Items whose names begin with the currency symbol ($) are
real items of length 4.
END OF IBM EXTENSION
No other data tvpes have a predetermined definition.
EXPLICIT DATA TYPE DEFINITION
There are two ways you can define data items explicitly — using
the IMPLICIT statement or using explicit type statements.
Typing Groups of Data Items — IMPLICIT statement
Using the IMPLICIT statement, you can explicitly specify the
data types for items whose names begin with specific letters. For
example, if you specify '
IMPLICIT DOUBLE PRECISION (A-C, F),
LOGICAL (E,L),CHARACTER(D,G,H)
your program will treat data items as shown below.
Names Beginning with
A through C, and F
E and L
D, G, and H
I through K, M, N
Nave Data Type Have Length
DOUBLE PRECISION 8
LOGICAL 4
CHARACTER 1
INTEGER 4 (default)
V-...^
through Z and $
REAL
4 (default)
IBM EXTENSION
If you specify an IMPLICIT statement with the following
initial letters:
(Y - B)
The compiler performs a "wraparound" scan to find the
beginning initial (Y), and the endi ng i ni tial (B) — which is
lower in the FORTRAN collating sequence than Y. That is, you
are implicitly typing all items with names beginning with Y, Z,
$, A, and B. You'll get a warning message when this situation
occurs; however, your program will compile and execute.
END OF IBM EXTENSION
Reference documentation for the IMPLICIT statement is given in
the VS FORTRAN Application Programming: Language Reference
manual.
c
y
40
VS FORTRAN Application Programming: Guide
Typing for Specific Data Items — Explicit Type Statements
C
Explicit type statements define the data type for specific data
items that you name in your program. For such items you can
specify the data type and the length, and/ optionally, initial
values for data items and dimension information for arrays.
For example, you can specify '
DOUBLE PRECISION MEDNUM
CHARACTER *80 INREC
IBM EXTENSION
INTEGER X2 COUNTR
REAL*16 BIGNUM, ARRAY2*4(5,5)
As an alternative for MEDNUM, you can specify:
REAL *8 MEDNUM
1 END OF IBM EXTENSION
These statements specify that*
I IBM EXTENSION
COUNTR is an integer item of length 2.
BIGNUM is a real item of length 16.
END OF IBM EXTENSION -
ARRAY2 is a two-dimensional array, with elements of length
4 (specified by *4). There are five elements in each
dimension (specified by (5,5)). (Arrays are explained in
"Arrays and Subscripts".)
INREC is a character item of length 80.
MEDNUM is a real item of length 8.
If you specify the preceding IMPLICIT statement in the same
program as these explicit type statements, the explicit type
statements override the IMPLICIT statement specifications, and
i n your program*
INREC is a character item of length 80.
MEDNUM is a real item of length 8.
All other items with names beginning with I or M are integer
i terns of length 4 .
IBM EXTENSION
BIGNUM is a real item of length 16.
ARRAY2 is a two-dimensional array, with elements of length
4 (specified by *4). There are five elements in each
dimension (specified by (5,5)).
COUNTR is an integer item of length 2.
END OF IBM EXTENSION
All other data items whose names begin with B or C are real
items of length 8.
Reference documentation for explicit type statements is given
in the VS FORTRAN Application Programming* Language Reference
manual .
Coding Your Program — Advanced Programming 41
DATA CLASSIFICATIONS
All the data you use in your program — whether it's data you've
retrieved from an external device or data your program develops
internally — must be constants* or be contained in variables or
arrays. Data in any of these classifications can be any of the
data types previously described. Data classifications are
discussed in the following sections.
VARIABLES
A variable is a named unit of data, occupying a storage area.
The value of a variable can change during program execution.
The name of a variable can determine its data type, as described
in "Predetermined Data Type Definition," or you can define its
data type explicitly, as described in "Explicit Data Type
Def ini ti on."
The value contained in a variable is always the current value
stored there. Before you've assigned a value to a variable, its
contents are undefined. You can initialize values using the
DATA statement? alternatively, your first executable statement
referring to it — for example, a READ statement or an assignment
statement — can assign a value to it.
Reference documentation for variables is given in the VS
FORTRAN Application Programming? Language Reference manual.
CONSTANTS
A constant is a data item in a program that has a fixed,
unvarying value. You can refer to a constant by its value, or
you can name the constant and use the name in all program
references.
The constants you can use are*
Arithmetic (integer, real, or complex) — use arithmetic
constants for arithmetic operations, and to initialize
integer, real, or complex variables, and as arguments for
subroutines, and so forth.
Logical — use logical constants in logical expressions, and
to initialize logical variables, and as arguments for
subroutines, and so forth.
Character — use character constants in character and
relational expressions, and to initialize character
variables, and as arguments for subroutines, and so forth.
Hollerith — use Hollerith constants to initialize data items
in a FORMAT statement.
"%^
IBM EXTENSION
Literal (old FORTRAN only) — similar in usage to character
constants.
Hexadecimal-
i terns.
-use hexadecimal constants to initialize
END OF IBM EXTENSION
Defining Constants by Value
You can use constants in your program by simply specifying their
values. For example*
CIRC =2*PI*RAD
42 VS FORTRAN Application Programming' Guide
or
CIRC =2.0*PI*RAD
where the value 2 represents an integer constant of that value,
and where the value 2.0 represents a real constant of that
value.
You can specify all types of constants in this way-
Arithmetic Constants — integer, real, or complex.
• Integer Constant — written as an optional sign followed
by a string of digits. For example:
-12345
12345
• Real Constant — can take three forms :
1. Basic Real Constant — written as an optional sign,
followed by an integer part (made up of digits),
followed by a decimal point, followed by a fraction
part (made up of digits). Either the integer or
fraction part can be omitted. For example*
+123.45
0.12345
2. Integer Constant With Real Exponent — written as &r>
integer constant followed by a real exponent in the
form of a letter, followed by a 1- or 2-digit
integer constant. Optionally, the exponent can be
signed. For example*
+12345E+2 E exponent (which occupies four
storage positions and has the value
+1,234,500; the precision is
approximately 7.2 decimal digits)
-12300D-03 D exponent (which occupies eight
storage positions and has the
value -12.3; the precision is
approximately 16.8 decimal digits)
IBM EXTENSION
12345Q03 Q exponent (which occupies 16
storage positions and has the
value +12,345,000; the precision
is approximately 35 decimal
digits)
END OF IBM EXTENSION
Basic Real Constant Ulith Real Exponent — written as
a basic real constant followed by a real exponent;
the real exponent is written as one of the letters
D, E, or Q, followed by a 1- or 2-digit integer
constant. Optionally, the exponent can be signed.
For example*
0.12345E+2 E exponent (which occupies four
storage positions and has the
value +12.345; the precision is
approximately 7.2 decimal digits)
0.12345D-03 D exponent (which occupies eight
storage positions and has the value
Coding Your Program — Advanced Programming 43
+0.00012345; the precision is
approximately 16.8 decimal digits)
IBM EXTENSION 1
-1234. 5Q03 Q exponent (which occupies 16
storage positions and has the
value -1,234,500; the precision
is approximately 35 decimal
digits)
END OF IBM EXTENSION
Complex Constant — written as a left parenthesis,
followed by a pair of integer constants or real
constants separated by a comma, followed by a right
parenthesi s.
The first integer or real constant represents the real
part of the complex number; the second integer or real
constant represents the imaginary part of the complex
number. The real and imaginary parts need not be of the
same size; the smaller part is made the same size as the
larger part. For example*
(123.45,-123.45E2) (has the value +123.45, -12345i ;
both the real and imaginary parts
have a length of 4)
IBM EXTENSION 1
(123.45,-123.45D2) (has the value +123.45, -12345i;
the real part has a length of 4,
the imaginary part a length of 8) /r^
(The real part (a real constant) is converted to ^^
a real constant of length 8.)
(12345, -123. 45Q2) (has the value +12345, -12345i ;
the real part has a length of 4,
the imaginary part a length of 16)
(The real part (an integer constant) is converted to
a real constant of length 16.)
END OF IBM EXTENSION
Note: In these examples, the character j. has the
value of the square root of -1.
Logical Constant — written as .TRUE, or .FALSE, in
expressions. (In input/output statements you can use T
or F as abbreviations.)
IBM EXTENSION 1
(In the DATA initialization statement, you can also
use T or F as abbreviations.)
END OF IBM EXTENSION
For a logical item named COMP, you can specify, for
example 1
LOGICAL COMP
C0MP=. FALSE.
This sets the logical item COMP to the value "false."
o
44 VS FORTRAN Application Programming* Guide
Character Constant — written as en apostrophe* followed by a
string of characters* followed by an apostrophe. The
character string can contain any characters in the
computer's character set. For example •
'PARAMETER = '
'THE ANSWER IS:'
"'TWAS BRILLIG AND THE SLITHY TOVES'
Note: If you want to include an apostrophe within the
character constant* you code two adjacent apostrophes* as
shown in the last example* which is displayed as:
'TWAS BRILLIG AND THE SLITHY TOVES
Hollerith Constant — valid only in a FORMAT statement. It is
written as on integer constant followed by the letter H»
followed by a string of characters. The character string
can contain any characters in the computer's character set.
For example:
F0RMAT(I3*11H = THE NORM)
F0RMAK2D8.6* 18H ARE THE 2 ANSWERS)
IBM EXTENSION 1
In old FORTRAN* the literal constant performs functions
similar to the current FORTRAN character constant* and the
current Hollerith constant. (Reference documentation is
given in the IBM Svstem/360 and Svstem/370 FORTRAN IV
Language manual.)
Hexadecimal Constant — written as the character Z, followed
by a hexadecimal number* made up of the digits through 9
and the letters A through F. You write a hexadecimal
constant as 2 hexadecimal digits for each byte.
You can use hexadecimal constants only in a DATA statement
to initialize data items of all types except character.
REAL *« TEMP
DATA TEMP/ZC1C2C3C4/
END OF IBM EXTENSION
Reference documentation for program constants is given in
the VS FORTRAN Application Programming: Language Reference
manual.
Coding Your Program — Advanced Programming 45
Defining constants by Name — PARAMETER statement
If your program uses one constant frequently, you can use the flj Y
PARAMETER statement to name the constant and assign it a value. %jr
You can do this once, before your program first uses the
constant, and then refer to the constant, wherever it's used, by
i ts name.
There are two advantages in handling constants this way*
• The name for the constant can be a meaningful name — which
makes the logic of the program easier to understand when the
time comes for maintenance updates.
• If for some reason the value of the constant must be
changed, you can change it once, in the PARAMETER
statement, and all references throughout the program are
updated.
You use the PARAMETER statement to assign names and values to
constants. For example*
CHARACTER *5 C1,C2
PARAMETER (C1='DATE , ,C2= , TIME f ,RATE=2*1 .414)
The CHARACTER explicit type statement defines items CI and C2 as
character items of length 5. The PARAMETER statement then
defines these items as named program constants*
CI has the value "DATE ". The constant is five characters
long; the blank following the word DATE is part of the
constant.
C2 has the value "TIME ". The constant is five characters
long; the blank following the word TIME is part of the
constant. /f~-\)
RATE is defined implicitly as a REAL *4 item. Therefore, Vj?
it's a real constant, four storage positions long, with a
value of 2 times 1.414 or 2.828.
You'll note that RATE is defined through the expression
2*1.414; when you define a constant using an expression in
this way, the expression you specify must be a constant
expression.
In the PARAMETER statement, the value you assign to the constant
must be consistent with its data type; that is, CI and C2 must
contain character data, and RATE must contain real data. If any
data conversions must be performed, they are made according to
the rules for the assignment statement. (See "Assigning Values
to Data — Assignment Statement.")
The value you assign through a PARAMETER statement to a
character constant must contain no more than 255 characters.
Reference documentation for the PARAMETER statement is given in
the VS FORTRAN Application Programming* Language Reference
manual.
ARRAYS AND SUBSCRIPTS
A VS FORTRAN array is a set of consecutive data items, each of
which is the same data type and length as the other items in the
set .
In FORTRAN, you can give a name to the entire array and then
refer to each of the individual items. The individual items are
called arrays elements, and you can refer to any individual
element by specifying its position within the array through one
or more subscripts, depending upon the number of dimensions in
the array.
\jf
46 VS FORTRAN Application Programming* Guide
You can define an array by using the DIMENSION statement, the
explicit type statement, or the COMMON statement.
One-Dimensional Arrays
To define a one-dimensional array, you specify only one
dimension declarator. For example, you want to define a
one-dimensional array, named ARRAY1, that contains five array
elements. You can do so through the following DIMENSION
declarati on •*
DIMENSION ARRAYK5)
In this case, you've defined ARRAY1 as an array containing five
elements, each implicitly defined as a REAL item of length 4.
SUBSCRIPT REFERENCES: Program references to ARRAY1 take the
form of subscripts 1
• As integer constants*
ARRAYH2)
In this example, the subscript cpecifies a reference to the
second array element.
• As integer variables:
ARRAYKNUM)
where (NUM) represents the integer variable subscript, into
which you can place the values 1 through 5. (For ARRAY1, any
other values produce invalid array references.)
IBM EXTENSION
You can also specify subscript references as real constants,
variables, or expressions; the compiler converts the real
value to an integer value.
END OF IBM EXTENSION
Reference documentation for the DIMENSION statement and for
subscript references is given in the VS FORTRAN Application
Programming: language Reference manual.
flulti dimensional Arrays
In VS FORTRAN, arrays can have up to seven dimensions; that is,
you may need to specify up to seven dimension declarators to
define the &rray, and up to seven subscripts to identify a
specific array element. (The number of subscripts you specify
must always equal the number of dimensions in the array.)
Multidimensional arrays ar& stored in column-major order. That
is, the first subscript always varies most rapidly, and the last
subscript always varies least rapidly.
For example, if you define the 3-dimensi onal array ARR3(2,2,2),
it T s placed in storage in the order shown in Figure 8. In this
example, the lower bounds of the subscripts are 1; therefore, the
first array eletrent is (1,1,1); you'd refer to the second array
element as ARR3(2,1,1), and you'd refer to the seventh array
element as ARR3(1,2,2).
Arrays — Implicit Lower Bounds
In the preceding. examples, the subscripts are shown as having a
range from 1 through the upper bound for each dimension of the
array; that is, in ARRAY3 the implicit lower bound for each
Coding Your Program — Advanced Programming 47
dimension is 1, and the explicit upper bound for each dimension
is 2.
Arrays — Explicit Loner Bounds
In VS FORTRAN, you can also explicitly state both the lower and
upper bounds iFor any array. For example, for ARR3A you could
speci fy ♦
DIMENSION ARR3A(4:5,2:3,l:2)'
The layout in storage — as shown in Figure 8 — is exactly the same
as for ARR3; however, valid array references would range from
ARR3A(4,2,1) through ARR3AC5, 3, 2) .
ARR3 — Implicit Lower Bounds
I 1,1,1 | 2,1,1 | 1,2,1 I 2,2,1 | 1,1,2 | 2,1,2 I 1,2,2 I 2,2,2
ARR3A — Explicit Lower Bounds
_____________________ ___.»____ ______ — _________________ — ___.,,___.
I 4,2,1 | 5,2,1 | 4,3,1 | 5,3,1 I 4,2,2 I 5,2,2 I 4,3,2 I 5,3,2
Figure 8. Three-Dimensi onal Array — Implicit and Explicit Lower Bounds
Arrays — signed Subscripts
I
In VS FORTRAN, your array declaration can specify positive or V-V
negative signed declarators for either the lower or the upper
bounds. This can make a difference i rt the number of array
elements the array contains.
For example, if you define ARR2 and ARR2S as follows 2
DIMENSION ARR2(4,2), ARR2S (-2:2,2)
the two arrays are laid out in storage as shown in Figure 9:
Valid array references for ARR2 range from ARR2(1,1) through
ARR2(4,2), and there ar& eight array elements.
Valid array references for ARR2S range from ARR2S(-2,1)
through ARR2S(2,2) (with ARR2S(0,1) and ARR2S(0,2)
included), and there are ten array elements.
Because a zero subscript is valid for ARR2S, there are two more
array elements in ARR2S than in ARR2.
t
J
48 VS FORTRAN Application Programming- Guide
ARR2(4,2) — is arranged in storage like this*
I 1,1 | 2,1 | 3,1 | 4,1 | 1,2 \ 2,2 | 3,2 I 4,2 |
ARR2S(-2*2,2) — is arranged in storage like this:
I -2,1 | -1,1 | 0,1 | 1,1 | 2,1 | -2,2 | -1,2 | 0,2 I 1,2 I 2,2
Figure 9. Arrays — Effect of Negative Lower Bounds
Arrays — Programmi ng Cons i dera t i ons
Wherever possible, you should specify arrays as one-dimensional
rather than as multidimensional. The fewer the dimensions in an
array, the faster your array references execute.
Always make sure that subscript values refer to elements within
the bounds of the array; if they don't, you can possibly destroy
data or instructions.
SUBSTRINGS OF CHARACTER ITEMS
o
■O
For character arrays and character variables, you can make
substring references (that is, references to only a portion of
the item) using substring notation.
You specify substring references by naming the array element or
variable and then adding the substring reference — a left
parenthesis, the lower bound, a colon, the upper bound, and a
right parenthesis, in that order.
For example*
VAR1(2*4) means that the substring consists of the second
through fourth characters in the character variable VAR1;
ARR1(2)(1*4) specifies that the substring consists of the
first through fourth characters in the second array element
of the character array ARR1.
You can omit the lower bound of the substring reference if it is
equal to 1; that is, ARR(2)( : 4) is exactly equivalent to
ARR(2)(1*4).
You can use character substrings in program references and in
assignment statements. For example, if you define a variable and
an array as follows*
CHARACTERK10 SUVAR,SUARR(3)
SUVAR= f ABCDEFGHIJ'
and you specify the following assignment*
SUARR(2)(*5)=SUVAR(6*10)
then, when the assignment statement is executed, the last five
characters of SUVAR (that is, FGHIJ) are placed in the first five
characters of the second array element of SUARR; the last five
characters of that array element are unchanged.
Reference documentation for character substrings is given in the
VS FORTRAN Application Programming* Language Reference manual.
Coding Your Program — Advanced Programming 49
USING DATA EFFICIENTLY
How efficiently your program uses the system depends, in part, on
how you define and use the data in your program. Th# choices you
make also depend upon the results you want to achieve.
This section discusses how to initialize data and how to reuse
storage for different data items in the same program.
INITIALIZING DATA — DATA STATEMENT
You can use the DATA statement to initialize variables and
arrays. You must place it after any specification statement or
IMPLICIT statement that refers to the items you're initializing.
For example* your program could contain the following
statements*
CHARACTER *<* CARL,CELS*2
DATA DEG,CELS, CARL/10. 2, 'DG' , 'SURD'/, AVCH/ . 1515/
and the data items would be initialized to the following values:
DEG (real constant) initialized to 10.2
CELS (character constant) initialized to DG
CARL (character constant) initialized to SURD
AVCH (real constant) initialized to .1515
You can also use named constants to initialize data items*
PARAMETER (DEGI=10.2)
DATA DEG/DEGI/
which initializes the real variable DEG to the value 10.2.
Reference documentation for the DATA statement is given in the VS
FORTRAN Application Programming* Language Reference manual.
Initializing Arrays — DATA Statement
There are special considerations when you initialise arrays with
the DATA statement* as follows*
INITIALIZING ARRAY ELEMENTS* You can initialize any element of
an array by subscripting the array name. Only one element is
initialized. The following example shows how to initialize
individual array elements*
DIMENSION AUO)
DATA A(1),A(2),A(4),A(5)/1. 0,2. 0,4.0, 5.0/
the array elements are initialized as follows*
A(l) initialized to 1.0
A(2) initialized to 2.0
A(3) is not initialized
A(4) initialized to 4.0
A(5) initialized to 5.0
A(6) through A(10) are not initialized.
INITIALIZING CHARACTER ARRAY ELEMENTS* In a character array, it
isn't necessary to specify the constant as the same length as the
character array element*
If the character constant is shorter than the character
array element, the array element is padded at the right with
blanks.
If the character constant is longer than the character array
element, the constant is truncated at th» right.
**^
50 VS FORTRAN Application Programming* Guide
■C
o
For example* if you specify the following statements*
CHARACTER *4 CARRAY(4)
DATA CARRAY(l),CARRAY(4)/ , ABC , , f EFGHIV
the CARRAY array is initialized as follows :
CARRAY(l) initialized to ABC (fourth character is blank)
CARRAYC2) and CARRAY(3) are not initialized
CARRAYC4) initialized to EFGH (I is truncated)
INITIALIZING ARRAYS— IMPLIED DO LISTS: You can use implied DO
lists to initialize parts or all of an array. You use the implied
DO list to specify the values the subscripts should assume.
Initializing an Entire Array — Implied DO List: You can
initialize an entire array to the value 0.0, as follows:
DIMENSION ARRAYE(10,10)
DATA ((ARRAYE(I,J),I=1,10),J=1,10)/100*0.0/
This DATA statement tells the compiler to:
1. Vary the subscript I from 1 to 10 each time the subscript J
is incremented, and \/ary the subscript J from 1 to 10; the
implied increment for both I and J is 1.
2. Place 100 repetitions of the value 0.0 in the 100 array
elements; the repetition factor is specified by the 100*.
Initializing an Identity Matrix — Implied DO Lists: You're
allowed to nest implied DO lists in a DATA statement. In this way
you can initialize an identity matrix, using one DATA statement:
DIMENSION ARRAYI(10,10)
DATA ((ARRAYI(I,J),I=l,J-l),J=2,10)/45*0.0/,
((ARRAYI(I,J),J=l,I-l),I=2,10)/45*0.0/,
(ARRAYI(I,I),I=1,10)/10*1.0/
This DATA statement tells the compiler to:
1. Vary the subscript,! from 1 to 1 less than the value of J,
each time the subscript J is incremented; subscript J is
incremented from 2 to 10. This fills the upper right 45 array
elements with 0.0.
2. Vary the subscript J from 1 to one less than the value of I
each time the subscript I is incremented; subscript I is
incremented from 2 to 10. This fills the lower left 45 array
elements with 0.0.
3. Use the value of I for both subscripts (1,1), and vary I from
1 to 10. This fills the principal diagonal with the value
1.0.
You can also use the DATA statement to initialize the entire
array to zeros, and then specify a DO statement and an assignment
statement to initialize the principal diagonal. For example:
DIMENSION ARRAYD(10,10)
DATA UARRAYD(I,J),I=1,10),J=1,10) /100X0.0/
DO 30 1=1,10,1
ARRAYD(I,I)=1.0
30 CONTINUE
MANAGING DATA STORAGE — EQUIVALENCE STATEMENT
You can control storage allocation within your program by using
the EQUIVALENCE statement.
When your program's logic permits it, you can use this statement
to specify that one storage area is to be shared by two or more
Coding Your Program — Advanced Programming 51
data items. These items can be variables or arrays, and they can
be of the same or of differing data types. There's one
restriction* CHARACTER items cannot be equivalenced with other
data types.
Note that only the storage itself is equivalent (shared); »
mathematical equivalence i s implied only when the sharing items
are of the same type, when they share exactly the same storage,
and when the value assigned to the shared area is of that type.
The EQUIVALENCE statement is particularly useful when you use it
with the COMMON statement; this kind of usage is described in
"EQUIVALENCE Considerations — COMMON Statement" in Part 3.
When you use the EQUIVALENCE statement with array elements, you
can implicitly specify the storage sharing of other array
elements within the same array; this is because arrays are stored
in a predetermined order. For example, if you write an
EQUIVALENCE statement referring to ARR3 (illustrated in
Figure 8), as follows*
DIMENSION ARR3(2,2,2)
INTEGER *4 ARR3B(4)
EQUIVALENCE ( ARR3C2, 2, 1 ) , ARR3B( 1 ) )
then the array elements of ARR3 and ARR3B share storage as shown
in Figure 10, with the displacement for the array elements shown
in the right-hand column.
ARR3 Storage
ARR3B Storage
Displacement
<*
8
12
16
20
2<f
28
32
Figure 10. Sharing Storage Between Arrays — EQUIVALENCE Statement
ARR3Q,
.1,
.1)
ARR3(2,
.1,
.1)
ARR3U,
.2,
.1)
ARR3(2,
.2,
.1)
ARR3U,
.1,
.2)
ARR3(2,
.1;
,2)
ARR3(1;
.2;
► 2)
ARR3(2,
,z>
,2)
ARR3BU)
ARR3B(2)
ARR3B(3)
ARR3BC4)
T--
^y
Reference documentation for the EQUIVALENCE statement is given
i n the VS FORTRAN Application Programming* Language Reference
manual .
Execution-Time Efficiency Using Equivalence
When you make items equivalent, you can specify them in any order
in your EQUIVALENCE statement. However, unless you ensure that
all the arithmetic items in the group have the proper boundary
alignment, you can lose object-time efficiency.
When all the items in an equivalence group are defined as
beginning at the same storage address, there is no problem.
There can be problems, however, when some items begin at a
displacement from the beginning address. In this case, you can
\j?'
52 VS FORTRAN Application Programming* Guide
f\ ensure proper boundary alignment by defining each equivalent
■ '-) arithmetic item as starting at a displacement from the beginning
^-^ of the group that can be evenly divided by its length* "•*- "*
it's COMPLEX, half its length. The two examples in Fig
or, i f
...... gure 11
illustrate this concept.
DEFINING AND USING EXPRESSIONS
Expressions are combinations of data items and operators that
represent a value. You can use them for arithmetic operations,
character operations, logical operations, or in relational
operations.
The simplest form of an expression is simply the name of a data
item, or the value or named value of a constant. You can specify
more complicated expressions by using operators to combine data
items. The kind of operators you can use depends upon the type of
expression you're specifying*
Arithmetic operators — for arithmetic expressions
Character operators — for character expressions
Relational operators — for relational expressions
Logical operators — for logical expressions
The precedence of one type of operator over another is in the
order given above.
ARITHMETIC EXPRESSIONS
You can use arithmetic expressions to specify mathematical
relationships of various kinds. The valid arithmetic
expressions, and how you can combine them, are shown in
Figure 12.
Specify all desired computations explicitly, and make certain
that no two arithmetic operators appear consecutively.
In addition, be aware that the compiler evaluates arithmetic
expressions as follows*
• Operands are evaluated in their order of precedence from
highest to lowest.
• Within the exponentiation precedence level , operations are
performed right to left. For example, A**B**C is evaluated
as (AKX(BXXC)).
• Within all other precedence levels , operations are performed
left to right. For example, A+B+C is evaluated as ((A+B)+C).
• Parentheses are evaluated as they are in mathematics; they
specify the order in which operations are to be performed.
That is, expressions within parentheses are evaluated before
the result is used. For example, the expression (CA-B)+C)*E
is evaluated as follows*
1. A-B is evaluated, gi ving resultl
2. resultl +C is evaluated, giving result2
3« result2 *E is evaluated, giving the final result
• You can use the + and - operators as signs for an item; when
you use them this way, they're evaluated as if they were
addition or subtraction operators. That is, A=-B+C is
evaluated asthough written A=-(B)+C.
Coding Your Program — Advanced Programming 53
The following EQUIVALENCE statement (where A is REAL*4, I is INTEGER**, and A2 is (f^)
DOUBLE PRECISION): ^^
DIMENSION A(10),I(16),A2(5)
EQUIVALENCE (A(l) , 1(7 ) , A2( 1) )
causes the items to be laid out in storage as follows:
Displacement:
4. 8 12 16 20 24 28 32 36 40 44 48 52 56 60 64
1 I I I I I I I I I I I I I I I I
I array 1(7)
, — | — | — , — | — | — | — | — | | — | | | — | — | | — |
A array |---j 1 — | — | — I | -.— | — | — | — |
A2(l)
A2 array I I | I I I
(Efficiently laid out — A and A2 begin at a displacement of 24 storage positions from
the beginning of the equivalence group)
The following EQUIVALENCE statement (using the same items):
DIMENSION A(10),I(16),A2(5)
EQUIVALENCE ( A( 1 ) , I (6 ) , A2( 1) )
causes the items to be laid out in storage as follows:
Displacement:
4 8 12 16 20 24 28 32 36 40 44 48 52 56 60 64 /r ^
1 I I I I I I I I I I I I I I I I ( V
I array 1(6)
I — ,_.. j. „,— | __-,-_!___ | — , — j — , — , — ,— .i — i — i — i
A(l)
A array | — | — | — | — | | | | — | — | — |
A2(l)
A2 array I | | | | |
(Inefficiently laid out — A2 begins at a displacement of 20 — not divisible by 8 — from
the beginning of the equivalence group)
Figure 11. Storage Efficiency and the EQUIVALENCE Statement
54 VS FORTRAN Application Programming: Guide
^s.
Operation
Arithmetic
Operator
Precedence
Function Evaluation (none)
Exponentiation **
Hi ghest
Second
Hi ghest
Multipl i cat ion
Di vi si on
Third
Hi ghest
Addi tion
Subtract! on
Lowest
Figure 12. Arithmetic Operators and Operations
In arithmetic expressions, you can specify the operands as any
mix of integer, real, or complex items.
However, you should be careful, when you're specifying
arithmetic expressions, that you define the operands so that you
get the precision you want in the result. For example, if you
specify'
DOUBLE PRECISION RESULT
RESULT = AR3*AR1
AR3 and AR1 (both REAL *4 numbers) are multiplied together, the
REAL *4 result is padded with zeros and placed in RESULT. Thus,
while the RESULT is the length of a DOUBLE FRECISION item, it has
only the precision obtainable using REAL*4 operands
(approximately 7.2 decimal digits).
If you're dividing one operand by another, you should define the
operands and the result as REAL items.
If you divide one integer by another, any remainder is ignored,
and you get an integer quotient-
DATA 11/10/, 12/15/
RESULT=I2/I1
In this case, the expression on the right of the equal sign is
evaluated to the integer 1; then the result is converted to a
floating point number and stored in RESULT.
You can also perform more complex mathematical operations by
using the intrinsic functions thai VS FORTRAN provides; see
"Saving Coding Effort with Statement Functions" for details.
Reference documentation for arithmetic expressions is given in
the ¥S FORTRAN Application Programming* Language Reference
manual.
CHARACTER EXPRESSIONS
You specify character expressions by combinations of character
items, the character concatenation operator, and optional
parentheses.
Coding Your Program — Advanced Programming
55
The simplest form of character expression is simply a character
item itself.
You can combine character operands by using the concatenation
operator (//) to join one operand to the next. For example:
CHARACTER *12 CHAR
CHARACTER *6 CHAR1,CHAR2
DATA CHARl/'ABCDEF'/,CHAR2/ f GHIJKLV
CHAR = CHAR1//CHAR2
The concatenation operator (//) specifies that the contents of
CHAR2 are to be joined to those of CHAR1 to form the character
stri ng:
ABCDEFGHIJKL
which is then assigned to the character variable CHAR.
Reference documentation for character expressions is given in
the VS FORTRAN Application Programming: Language Reference
manual.
RELATIONAL EXPRESSIONS
You can form relational expressions by combining two arithmetic
expressions with a relational operator, or by combining two
character expressions with a relational operator.
The relational operators you can use are listed in Figure 13.
Relational
operator
Meaning
.GT.
greater than
.LT.
less than
.GE.
greater than
or equal to
.LE.
less than or
equal to
.EQ.
equal to
.NE.
not equal to
\^-j7
Figure 13. Relational Operators and their Meanings
You can combine expressions as shown in the following examples:
A.GE.B
If A is greater than or equal to B, this relational expression is
evaluated as "true"; otherwise, it is evaluated as "false."
(A+B).LT.(C-B)
If the result of A+B is less than the result of C-B, this
relational expression is evaluated as "true"; otherwise, it is
evaluated as "false."
COMPLEX CMPLX1/CMPLX2
(CMPLXl-2).EQ.(CMPLX2+2)
If the result of CNPLX1-1 is equal to the result of CMPLX2+2,
this relational expression is evaluated as "true"; otherwise, it
is evaluated as "false." (The only relational operators you can
use with complex arithmetic operands are . EQ . and .NE.)
CHARACTER *5 CHAR4, CHAR5, CHAR6*8
(CHAR4//CHAR5).GT.CHAR6
c
.J
56 VS FORTRAN Application Programming: Guide
fs^
\taiZ
In this expression, CHAR6 is extended 2 characters to the right
with blank characters; CHAR6 is then compared with the
concatenation of CHAR4 and CHAR5, according to the EBCDIC
collating sequence. If the concatenation of CHAR4 and CHAR5
evaluates as greater than CHAR6, this relational expression is
evaluated as "true"; otherwise, it is evaluated as "false."
Relational Expressions — Character operands
LOGICAL EXPRESSIONS
When you use a relational expression to compare character
operands, the comparison is made using the EBCDIC collating
sequence.
For example,
(contai ni ng
if character items CI (containing
XYZ') are compared, as follows :
3ABM and C2
L = C1.GT.C2
C1.GT.C2 evaluates as "true."
However, if you use the intrinsic functions (LLT, LGT, LLE, and
LGE) to compare character operands, the comparison is made using
the ASCII collating sequence. See "Comparing Character
Operands — FORTRAN-Suppl i ed Functions" in Part 3 for additional
i nf ormat i on .
Reference documentation for relational expressions and for the
EBCDIC and ASCII collating sequences is given in the VS FORTRAN
Application Programming'- Language Reference manual.
You use logical expressions to combine logical operands — a
logical constant, logical variable or array element, logical
function references, and logical or relational
expressions — optionally enclosed in parentheses.
The logical operators you can use are shown in Figure 14.
Logical operator Meaning
•NOT. Logical negation
AND.
OR.
EQV.
NEQV.
If both operands are "true," the
expression is "true"; otherwise
the expression is "false"
If either operand is "true," the
expression is "true"; otherwise
the expression is "false"
If both operands are "true" or if
both operands are "false," the
expression is "true"; otherwise
the expression is "false"
If both operands arQ "true" or if
both operands are "false," the
expression is "false"; otherwise
the expression is "true"
Precedence
Hi ghest
Lowest
Figure 14. Logical Operators and their Meaning;
^f^TV
Coding Your Program — Advanced Programming
57
The following examples show some of the ways you can use logical *
expressions 2 /|f~v /
1. A.GT.B.OR.A.EQ.C
This logical expression is "true" if one , of the following is
"true":
A is greater than B, or
A i s equal to C
otherwise, it is "false."
2. A.GT.B.AND.A.EQ.C
This logical expression is "true" only if both the following
are "true" 2
A is greater than B, and also
A i s equal to C
otherwise, it is "false."
3. A.GT.B.AND. .NOT.A.EQ.C
This logical expression is "true" only if both the following
are "true" 2
A is greater than B, and also
A i s not equal to C
otherwise, it is "false."
4. A.GT.B.OR.A.EQ.C.AND.B.LT.D
This logical expression is evaluated in the following order 2
a. A.GT.B is evaluated, giving a truth value v.
b. A.EQ.C is evaluated, giving a truth value w.
c. B.LT.D is evaluated, giving a truth value x.
d. w.AND.x is evaluated, giving a truth value i£.
e. v. OR.}/ is evaluated, giving the final truth value z.
The expression is "true" if either v or y evaluates as
"true."
Reference documentation for logical expressions is given in the
VS FORTRAN Application Programming 2 Language Reference manual.
ASSIGNING VALUES TO DATA — ASSIGNMENT STATEMENT
In a VS FORTRAN program, the assignment statement lets you assign
values to data.
The assignment statement closely resembles a conventional
algebraic equation, except that the value to the right of the
equal sign replaces (is assigned to) the value to the left.
You can use the assignment statement to assign one constant*
variable, or array element to another variable or array element.
You can specify arithmetic, character, and logical operands and
expressions to the right of the equal sign.
^j/'
58 VS FORTRAN Appli cation Programming 2 Guide
ARITHMETIC ASSIGNMENTS
4"\
c
You can assign arithmetic operands and expressions to other
arithmetic operands; the item(s) to the right of the equal sign
don't have to be the same type or length as the item to the left
of the equal sign.
For example (assuming default naming conventions)* if you make
the following assignments, you'll get the indicated results:
PI=3. 1*159
assigns the real constant 3.14159 to the REAL variable of
length 4 named PI.
ARRAY3(NUM) = DIFF
assigns the value currently contained in the REAL variable
of length 4 to the REAL array element ARRAY3CNUM) of
length 4
INTR = DIFF
the value of DIFF is converted to an INTEGER value of length
4 (that is, the largest integer in the real item is used,
without rounding) and placed in INTR.
DIFF = INTR
the value of INTR is converted to a REAL value of length 4
and placed in the variable DIFF.
DIFF=INTR+DIFF
the value of INTR is converted to a REAL value of length 4
and added to the current value of DIFF; the result is the
new value of DIFF.
You can use and combine all the arithmetic operators, as shown in
Figure 12.
Reference documentation for arithmetic assignments is given in
the VS FORTRAN Application Programming- Language Reference
manual .
CHARACTER ASSIGNMENTS
You can use character assignments to initialize character items,
For example 1
CHARACTER*10 SUVAR
SUVAR='ABCDEFGHIJ'
which assigns the value ABCDEFGHIJ to the character variable
SUVAR.
When the operands are character items or expressions, you can
specify the item to the left and the item(s) to the right of the
equal sign with differing lengths. When you execute the
assignment, the item to the left is either padded at the right
with blanks or the data is truncated to fit into the item at the
left:
CHARACTER *5 A,B,C,E *13
DATA A/'WHICH'/,B/' DOG »/,C/'BITES'/
E=A//B//C
In the assignment statement, the concatenation symbols (//)
place the contents of A, B, and C one after another into E.
After the assignment statement is executed, the character
variable E contains:
WHICH DOG BIT
(Note that the characters ES are truncated.)
Coding Your Program — Advanced Programming 59
LOGICAL ASSIGNMENTS
You can also define character items on either side of the equal
sign as substrings, in which case only the substring portion of
the item is acted upon:
A(«*5)=C(3*4)
After this assignment statement is executed, A contains the
characters "WHITE".
There's one restriction upon character assignment statements*
the item to the left of the equal sign, and those to the right
must not overlap in any way; that is, they must not refer to the
same character positions, completely or in part. If they do, you
can get unpredictable results, but you won't get an error
message.
Reference documentation for character assignments is given in
the VS FORTRAN Application Programming' Language Reference
manual .
When the operand to the left of the equal sign is a logical item,
the operands or expressions to the right must evaluate to a
logical value of either "true" or "false."
In a logical assignment, the righthand operands and expressions
can be logical items, and logical or relational expressions.
Within the relational expressions, you can use arithmetic or
character operands.
For example, you can use arithmetic operands, as follows:
LOGICAL *4 LOGOP
DOUBLE PRECISION AR1/1 . 1/, AR2/2 .2/, AR3/3.3/ , AR4
LOGOP = (AR4.GT.AR1).0R.(AR2.EQ.AR3)
"true" is placed in LOGOP when AR4 is greater than AR1; otherwise
AR2 and AR3 must be tested. Then if AR2 is equal to AR3, "true"
is placed in LOGOP; otherwise "false" is placed in LOGOP.
For example, you can use character operands, as follows*
LOGICAL *4 LOGOP
CHARACTER *6 CHAR1, CHAR2, CHAR3
DATA CHARl/'ABCDEFV CHAR2/' GHIJKL V
LOGOP = (CHAR2.EQ.CHAR3).AND.(CHAR1.LT.CHAR2)
"true" is placed in LOGOP when CHAR2 and CHAR3 are equal and
CHAR1 is less than CHAR2; otherwise, "false" is placed in LOGOP.
(Unless their values change during execution, CHAR1 always
evaluates as less than CHAR2.)
Reference documentation for logical assignments is given in the
VS FORTRAN Application Programming* Language Reference manual.
rv
SAVING CODING EFFORT WITH STATEMENT FUNCTIONS
If your program makes the same complex calculation a number of
times, you can define a statement function and then, whenever the
program must make the given calculation, refer to that function.
For example,
WORK(A,B,C,D,E) = 3.274*A + 7.477*B - C/D + (X+Y+Z)/E
defines the statement function WORK, where WORK is the function
name and A, B, C, D, and E are the dummy arguments.
o
60 VS FORTRAN Application Programming* Guide
r
The expression to the right of the equal sign defines the
operations to be performed when the function reference appears
in an arithmetic statement.
All statement function definitions must precede the first
executable statement of the program.
The function reference might appear in a statement as follows!
W = U0RK(GAS, OIL, TIRES, BRAKES, PLUGS) - V
This is equivalent to:
W = 3.274*GAS + 7.477X0IL - TIRES/BRAKES + (X+Y+ZVPLUGS - V
Note the correspondence between the dummy arguments A, B, C, D,
and E in the function definition and the actual arguments GAS,
OIL, TIRES, BRAKES, and PLUGS in the function reference.
For reference documentation about statement functions, see the
VS FORTRAN Application Programming: Language Reference manual.
CONTROLLING PROGRAM FLO U
Unless you explicitly change the flow of control, VS FORTRAN
programs execute one statement after another sequentially. In VS
FORTRAN, you can alter the sequence of control, using the ASSIGN,
DO, GO TO, IF, PAUSE, STOP, and END statements.
In VS FORTRAN, the arithmetic and logical IF statements and the
unconditional GO TO statement work in the same way they've done
in older IBM FORTRAN implementations.
However, there &r& new VS FORTRAN programming options
~ available — such as the block IF statement — and changed
, programming rules for the DO statement, assigned and computed GO
y TO statements, and the PAUSE, STOP, and END statements.
Programming considerations for these new language features are
reviewed in the following sections.
USING STRUCTURED PROGRAMMING — 5L0CK IF STATEMENT
The VS FORTRAN structured programming statements — the block IF
statement and its associated ELSE IF, ELSE, and END IF
statements — help you create programs that conform to structured
programming rules:
1. Write all code in control structures.
2. Construct each control structure so that it has only one
entrance and only one exit.
3. Make each control structure nestable.
4. Control program flow along paths that define the structure
itself.
5. Indent the source code to reflect the logic flow between
control structures.
These rules make programs simpler and easier to understand; each
structure is small and self-contained, and the structure of the
program reflects its logic.
The block IF statement — together with its subsidiary ELSE IF,
ELSE, and END IF statements — helps you write VS FORTRAN programs
that conform to these structured programming rules. They let you
nest IF procedures in a simple straightforward way.
Coding Your Program — Advanced Programming 61
Two terms are needed to explain the concepts of the block IF
statement, IF-level and IF-blOCk:
IF-Ievel
iF-block
The number of IF-levels in a program unit is
determined by the number of sets of block-IF
statements (IF THEN and END IF statements).
The IF-level of a particular statement is determined
with the formula 5
nl - n2
where J
nl is the number of block IF statements from
the beginning of the program unit up to and
including this statement.
n2
is the number of END IF statements in the
program unit up to, but not including, this
statement.
Thus, in the following example*
EQ. B) THEN
IF (C+D .EQ. 0) THEN
10
11
IF (A .
20
21
IF (
29
30
END*
39
40
END IF*
IF
The block IF at number 10 is at IF level 1,
and the block IF statement at statement 20
' is at IF level 2.
An IF-block begins with the first statement after the
block IF statement (IF THEN), and ends with the
statement preceding the next ELSE IF, ELSE, or END IF
statement at the same IF-level as the block IF
statement. The IF-block includes all the executable
statements in between.
Thus, in the preceding example, the IF blocks are:
• Statements 11-39 inclusive.
• Statements 21-29 inclusive.
In Figure 15, the IF blocks for each example are:
Example l: The IF block ends with the statement
preceding END IF.
Example Z' The IF block ends with the statement
preceding ELSE.
Example Z' The IF block ends with the statement
preceding ELSE IF.
You can code an empty IF-block; that is, you can code
an IF-block that has no executable statements in it.
You must not transfer control into an IF-block from
outside the IF-block.
x_y
c
V--
62 VS FORTRAN Application Programming: Guide
.#">>
vy
fy^
There are three forms a block IF statement can take, as shown in
Figure 15.
Example 1* IF (expression) THEN
(code executed if expression is "true")
END IF
Example 2* IF (expression) THEN
(code executed if expressi on is "true")
ELSE
(code executed if expressi on is "false")
END IF
Example 3* IF (expressi onl) THEN
(code executed if expressi onl is "true")
ELSE IF (expression2) THEN
(code executed if expression! is
"false" and expression2 is "true")
ELSE
(code executed if both expression 1
and expressi on2 are "false")
END IF
Note: In this third form, you can repeat ELSE IF blocks as your
program's logic requires; for example*
IF (expressionl) THEN
(code executed if expressi onl is "true")
ELSE IF (expression2) THEN
(code executed if expressi on2
is "true")
ELSE IF (expression3) THEN
(code executed if expressi on3
is "true")
ELSE IF (expressions THEN
(code executed if expressi on4
is "true")
ELSE
(code executed if all e xpressi ons
listed above are "false")
END IF
Figure 15. Block IF Statement — Valid Forms
Any one of these forms can be nested to any depth within any of
the others, as the following example shows*
IF (A.EQ.B) THEN
(code sequence executed if A.EQ.B is "true")
ELSE IF (A.GT.B) THEN
(code sequence executed if A.GT.B is "true")
ELSE
(code sequence executed if A.EQ.B and A.GT.B
are both "false")
IF (C.LT.D) THEN
(code sequence executed if C.LT.D is "true")
ELSE
(code sequence executed if C.LT.D is "false")
DO
90 CONTINUE
END IF
END IF
Here's how the statement executes*
Coding Your Program — Advanced Programming 63
1. The first block IF statement has an IF block that includes
the range of statements to the ELSE IF statement.
2. The ELSE IF THEN statement has as its ELSE IF block the range \J""
to the ELSE statement at the same level (the first ELSE
statement).
After your program executes an ELSE IF block, control is
transferred to the END IF statement at the same level.
3. The first ELSE statement is the alternative condition for
the ELSE IF THEN statement.
4. The second IF THEN statement is subordinate to the first ELSE
statement. This IF block continues to the first END IF
statement.
5. The second ELSE statement is the alternative condition for
the second IF THEN statement. Its ELSE block is the range of
code to the first END IF statement.
6. The CONTINUE statement provides a convenient reference point
for the DO-loop code executed in the current nested ELSE
block. (The nested DO loop must be completely contained
within the current block; in this example, the current
nested ELSE block.)
7. The first END IF statement corresponds to the nested block IF
statement.
8. The second END IF statement corresponds to the first block IF
statement (the one that begins the entire code sequence).
Reference documentation for the block IF statement is given in
* ne VS FORTRAN Application Programming* Language Reference
manual.
Using the CONTINUE Statement
In the previous example, there's a CONTINUE statement which
provides a convenient ending point for procedures within the
current ELSE block. You'll find the CONTINUE statement
particularly useful in this way within DO loops.
However, there's one limitation you must observe. When you use
the CONTINUE statement within a block IF statement sequence, you
must use the CONTINUE only for control transfers wi thi n the local
code block (in this example, the local ELSEblock). If you branch
into the block (with GO TO statements, for example), the results
are unpredictable, even though you won't get an error message.
PROGRAMMING LOOPS — DO STATEMENT
In VS FORTRAN, you can use the DO statement to execute a range of
statements a specific number of times. The ways you can do it ar&
much more flexible than in previous FORTRAN implementat i ons^
• You can nest DO statements; if you nest one DO statement
within another, you must include the range of the inner DO
statement entirely within the range of the outer DO
statement.
You can use the same terminal statement for both the inner
and the outer DO statement ranges. (CONTINUE is handy for
this.)
• If you code DO statements within a block IF, ELSE IF, or ELSE
block, make sure that the range of the DO statement is
completely contained within that block.
^_j/
O-
64 VS FORTRAN Application Programming: Guide
• If you code a block IF statement within a DO loop, ensure
that the entire range of the block IF statement* including
END IF, is within the range of the DO loop. (You can't use
the END IF as the terminal statement for the loop.)
• Don't use any of the following as terminal -statements:
— An unconditional or assigned GO TO statement
An arithmetic IF, ELSE IF, ELSE, or END IF statement
— Another DO statement
A RETURN, STOP, or END statement
An INCLUDE statement
• When you execute a DO statement, the DO loop becomes active.
It remains active until one of the following occurs?
— The loop executes completely.
— The program executes a RETURN statement within its
range.
— A transfer is made out of its range.
— Any STOP statement is executed anywhere in the program.
— Execution is terminated for any other reason.
In VS FORTRAN, you can specify the DO variable as an integer or
real variable, and you can specify the initial value, the test
value, and the increment as integer or real expressions,
positive or negative. These rules give your DO loop processing
much more flexibility than before.
For example, if you code the following DO statement*
DO 20 VAR=START,END,INC
20
CONTINUE
how the loop executes depends upon the values you place in START,
END, and INC.
You can specify them all as positive quantities*
START=1.0
END=11.0
INC = 2
The starting value (START) for VAR is 1.0, and the ending value
(END) is 11.0. Each time the loop is executed, VAR is incremented
by 2.0 (INC). (Note that because VAR is a real item, that the
integer value in INC is converted to a real value.) After the
loop has been executed six times, VAR contains the value 13.0,
and DO statement processing is completed.
You can specify a decrementing INC value, with a START value
higher than the END value*
START=11.0
END=1.0
INC=-2
Again the loop is executed six times, after which VAR contains
the value -1.0.
You can specify values that cause the DO loop not to be executed*
Coding Your Program — Advanced Programming
65
START=10.0
END=1.0
INC=2
The START value is higher
than the END value and INC
the increment is positive.
After execution/ VAR
contains the value 10.0.
or
START=1.0 The START value is lower
END=10.0 than the END value and INC
INC=-1 the increment is negative.
After execution^ VAR
contains the value 1.0.
In either case the loop is not executed at all.
Note: Be careful when you're processing DO loops using real
values for the starting or ending values, or for the increment;
because real numbers ar& an approximation of integer values,
there can be times when the loop is not executed exactly as you
expect. In general/ numbers that cannot be represented exactly
in the computer may give unexpected results.
Reference documentation for the DO statement is given in the VS
FORTRAN Application Programming: Language Reference manual.
USING PROGRAM SWITCHES—ASSIGNED GO TO STATEMENT
You can make one GO TO statement transfer control to different
statements/ depending upon a control variable (which contains
statement number to be used). You set the control variable by
means of an ASSIGN statement*
ASSIGN 20 TO LVAR
GO TO LVAR
30 (next executable statement)
When this GO TO statement is executed/ control is transferred to
statement number 20.
You can optionally include a list of statement numbers in the
assigned GO TO statement*
ASSIGN 20 TO LVAR
GO TO LVARdO, 20/ 50, 100)
30 (next executable statement)
When this GO TO statement is executed, control is transferred to
statement number 20.
When your program executes either of these assigned GO TO
statements/ LVAR must be assigned a valid number for an
executable statement.
Reference documentation for the assigned GO TO statement is
gi ven i n the VS FORTRAN Application Programming* Language
Reference manual.
Hi «L# / '
\ I
USING CONDITIONAL TRANSFERS — COMPUTED GO TO STATEMENT
You can transfer control conditionally to one of a number of
statements, depending on the value contained in a control item*
INT1=2
GO TO (10,20,30,50,100) INT1
When this statement is executed, the value in INT1 (2) specifies
that the second statement number i s to be used for the transfer,
and control is transferred to statement number 20.
You can use an integer expression as the control item*
o
66 VS FORTRAN Application Programming* Guide
INT1=20
INT2=18
GO TO (10,20,30,50,100) INT1-INT2
When this statement is executed, the expression INT1-INT2 is
evaluated, and the resulting value (2) specifies that the second
statement number in the list is to be used for the transfer.
Control is transferred to statement number 20.
You can also transfer control to the next executable statement,
by ensuring that the value in the control item is either less
than one or greater than the number of labels listed. That is, in
the previ ous examples, if the value in INT1 or of INT1-INT2 is
less than one or greater than five, control is transferred to the
next executable statement.
Reference documentation for the computed GO TO statement is
given in the VS FORTRAN Application Programming' Language
Reference manual.
SUSPENDING PROGRAM EXECUTION — PAUSE AND STOP STATEMENTS
You can use the PAUSE and STOP statements to suspend program
execution* the PAUSE statement temporarily, the STOP statement
permanently.
Suspending Execution Temporarily — PAUSE Statement
C
You can use the PAUSE statement to halt program execution,
pending operator response:
PAUSE 20200
or
PAUSE 'MOUNT TEMPORARY TAPE. TO RESUME ENTER 9'
When the program executes either of these PAUSE statements, the
message is displayed at the operator console:
01 IFY001A PAUSE 20200
or
01 IFY001A PAUSE MOUNT TEMPORARY TAPE. TO RESUME ENTER 9
The format of the operator's response to the message depends upon
the operating system being used.
Stopping Programs Permanently — stop statement
When you end execution of your program, you can communicate a
message to the system operator through the STOP statement.
The message can be a numeric string of 5 digits or less :
STOP 21212
where 21212 can have any meaning you want to assign it.
The message can also be a character constant*
STOP 'PROGRAM BACGAM EXECUTION COMPLETED'
The character constant you specify must contain no more than 72
characters.
When the program executes either of these STOP statements, the
message is displayed at the operator console.
Coding Your Program— 'Advanced Programming 67
You can also use the STOP statement to stop the program
permanently wi thout sending a message to the operator J _^ j
STOP \J
Reference documentation for the PAUSE and STOP statements is
given in the VS FORTRAN Application Programming* Language
Reference manual.
ENDING YOUR PROGRAM— END STATEMENT
In VS FORTRAN* the last statement in your program must be an END
statement, and (unless your program executes a RETURN or STOP
statement first) it must be the last statement executed.
For this reason, you can label the END statement. This lets you
ensure that it is executed (if that T s what you want), no matter
which branch of the program is executed last:
110 END
(For the END statement in subprograms, see "Coding Calling and
Called Programs.")
Reference documentation for the END statement is given in the VS
FORTRAN Application Programming* Language Reference manual.
USE PRE-MRITTEN SOURCE CODE
If your program uses frequently-used code sequences — sequences
such as blocks of common data items, or often-used error routines
or input/output routines — you can write the code sequences once,
place them in a system catalog, and then retrieve them for your
program with the INCLUDE statement. _,.
For example, to retrieve an error routine you cataloged under the ^w ;
name ERRTN, you can specify*
INCLUDE (ERRTN)
in your source program. During compilation, the ERRTN source
statements are inserted at this point in the program.
For information on cataloging the source code, see "Cataloging
Your Source Program."
AVOIDING CODING ERRORS
Many coding errors can cause problems in your compilation.
While you're coding your program, be careful not to make these
common programming errors 5
1. Misspelling FORTRAN words.
2. Omitting required punctuation, or inserting unneeded
punctuation.
3. Not observing FORTRAN formatting rules.
4. Forgetting to assign values to variables and arrays before
you use them.
5. Moving data into an item that's too small for it. (This
causes truncation.)
In particular, don't initialize more array elements than the
array contains; you can inadvertently destroy subsequent
data and instructions.
o
68 VS FORTRAN Application Programming* Guide
f*^
^^y
6. Specifying subscript values that are not within the bounds
of an array,
7. Inadvertently changing types defined in an IMPLICIT
statement by explicit type statements.
8. Making invalid data references to equivalenced items of
differing types (for example* integer and real).
9. Transferring control from outside a DO loop into an
intermediate point in a DO loop.
10. Using arithmetic items for intermediate calculations that
are too small to give the precision you need in the result.
For example^ If your final result is in the order of seven
decimal digits, you may need to perform the intermediate
calculations in DOUBLE PRECISION.
11. Failing to inspect code movements in programs compiled with
the 0PTIMIZEC3) option. For example 1 if an IF statement
controls execution of a computation within a loop, the
computation may be moved outside the loop and give you
results you don*t expect. See "Using the Optimization
Feature."
12. Attempting to process input records after a file has been
used for output. See "Programming Input and Output."
13. Writing main programs or subprograms that directly or
indirectly invoke themselves (see "Coding Calling and Called
Programs").
14. Writing a series of subprograms without a required main
program.
15. Defining dummy arguments and actual arguments that do not
agree in type and/or length. For example** arrays that do not
have the same dimensions, integer actual arguments with real
dummy arguments or vice versa.
16. In a subprogram, assigning new values to arguments
associated with variables in common.
17. Failing to initialize V5C0M when your main program is not a
FORTRAN program. (See "Appendix B. Assembler Language
Con si derati ons.")
18. Referring to a statement function with other than the
defined number of arguments.
19. When using carriage control characters, not overriding all
applicable default values for FORTRAN units.
20. If you recompile programs originally written for the OS
FORTRAN Gl, H Extended, or DOS FORTRAN F compilers, you may
experience VS FORTRAN internal table overflows. If this
happens, you must restructure the source code to reduce the
number of unique parameter lists and/or the number of
branches specified in computed GO TO statements and
alternate returns.
21. The VS FORTRAN compiler uses the OS FORTRAN H extended
architecture for rounding infinite binary expansions. The OS
FORTRAN Gl compiler also rounds, but the DOS FORTRAN F
compiler truncates. If you recompile programs originally
written for the DOS FORTRAN F compiler, you may experience a
difference in expected execution output.
22. If your VS FORTRAN Internal tables overflow, you must
restructure the source code to reduce the number of unique
parameter lists and/or the number of branches specified in
computed GO TO statements and alternate returns.
Coding Your Program — Advanced Programming
69
Additional parameter lists are created when you recompile OS
FORTRAN H Extended programs that have many arrays with ^r~^
adjustable dimensions. (These parameter lists are created (J ,'
because a library routine (IFYDSPAN) is used to perform the x^
calculations for adjustable dimensions.) Also* in
LANGLVLC77) parameter lists* character parameters generate
two entries each.
X:^
o
70 VS FORTRAN Application Programming* Guide
COMPILING YOUR PROGRAM — ADVANCED PROGRAMMING
Xj)
Once your source program is written, you must have it translated
into machine language — that is, compile it. What you get as
output from the translation depends upon the job control options
and compiler options you specify.
AUTOMATIC CROSS COMPILATION
Cross compilation of VS FORTRAN programs is automatic. That is,
you can compile your source program under any system; you can
then link-edit the resulting object module to execute under any
of the supported systems.
OVERALL JOB CONTROL CONSIDERATIONS
c
The job control statements you use, when processing VS FORTRAN
programs, are dependent upon the system you 1 re running under.
Your VS FORTRAN jobs can be any of the following:
Compi le-only
Compile, link-edit
Compile, link-edit, execute
Link-edit only
Link-edit, execute
Execute only
No matter which of these you're doing, there are certain job
control statements you use for any job. These are explained in
the following sections.
Syntax for Job control statements
In the following sections, the job control statements are shown
using a formal syntax notation. The following paragraphs define
how to interpret this syntax.
• UPPERCASE LETTERS* WORDS, AND NUMBERS: must be coded in the
statement exactly as shown.
For example, the word JOB in a format i s to be coded as JOB.
• LOWERCASE LETTERS AND WORDS: represent variables, for which
programmei — supplied information is substituted.
For example, the word "option" in a format can be coded as
NODECK.
• SYMBOLS in the following list must be coded exactly as shown:
apostrophe
»
asteri sk
K
comma
,
equal sign
3
parentheses
(
)
peri od
.
slash
/
Compiling Your Program— —Advanced Programming 71
HYPHENS (-): join lowercase letters and words and symbols to
form a single variable name.
For example, the word "program-name" in a format could be
coded as MYPR0G1.
SQUARE BRACKETS ([ 3): group optional related items (such as
alternative choices from which one choice can be made). For
example* the sequence "option [, opt ion]" in a format could
be coded as NODECK or as NODECK, XREF as needed.
ELLIPSES ( ... ): specify that the preceding syntactical
unit can, optionally, be repeated. (A syntactical unit is a
single syntactical item, or a group of syntactical items
enclosed in braces or brackets.) For example, the sequence
"option C, option] ... " in a format could be coded as NODECK
or as NODECK, XREF or as NODECK, XREF, MAP, DUMP as needed.
can be coded.
♦ BLANKS^ are used to improve the readability of the control
statement definitions. They must not appear in an operand
field, unless a definition explicitly states otherwise.
See "Using VM/370-CMS with VS FORTRAN" for information on
compiling, link-editing, and executing programs under
VM/370-CMS.
USING THE COMPILE-TIME OPTIONS
The VS FORTRAN compile-time options let you specify details
about the input source program and request specific forms of
compilation output.
Each option has a default value for your organization, and was
set when the compiler was installed. Ask your system
administrator for the default options in force.
How you specify the compiler options depends upon the system
you' re usi ng:
• In VM/370-CMS, specify them as options of the FORTVS command
(see "Using VM/370-CMS with VS FORTRAN").
• In OS/VS, specify them as options in the PARM subparameter of
the EXEC job control statement (see "Requesting
Execution — OS/VS EXEC Statement").
• In DOS/VSE, specify them as options in the PARM parameter of
the EXEC job control statement (see "Requesting
Execution— DOS/VSE EXEC Statement").
For abbreviations of compiler options, see VS FORTRAN
Application Programming' System Services Reference Supplement .
In the following paragraphs, each of the compile-time options is
briefly explained:
DECK | NODECK
Specifies whether or not the object module in card image
format is to be produced. r
FIPS (S|F) I NOFIPS
Specifies whether or not standard language flagging is to
be performed, and, if it is, the standard language flagging
level: subset or full.
Items not defined in the current American National Standard
are flagged.
'% z j/'
72 VS FORTRAN Application Programming: Guide
{%
^^y
<o
If you specify LANGLVLC66) and FIPS flagging at either
level, the FIPS option is ignored.
FLAG (I|I4|E|S)
Specifies the level of diagnostic messages to be written* I
(information) or higher, W (warning) or higher, E (error)
or higher, or S (severe) or higher.
FREE I FIXED
Indicates whether the input source program is in free
format or in fixed format.
GOSTMTlNOGOSTMT
Specifies whether or not internal sequence numbers (for
traceback purposes) are to be generated for a calling
sequence to a subprogram.
LANGLVL (66177)
Specifies the language level in which the input source
program is written: the old FORTRAN language level, or the
current FORTRAN language level.
LINECOUNT (number)
Specifies the maximum number of lines on each page of the
printed source listing. The number may be in the range 5 to
32765.
LISTlNOLIST
Specifies whether or not the object module listing i s to be
wri tten.
MAPlNOMAP
Specifies whether or not a table of source program names and
statement labels is to be written.
NAME (name)
For old FORTRAN programs only, specifies the name to be
given to a main program.
When NAME is omitted, the main program is named MAINft.
OBJECT INOOBJECT
Specifies whether or not the object module i s to be
produced.
OPTIMIZE €0|1I2|31 I NOOPTIMIZE
Specifies the optimizing level to be used during
compilation*
OPTIMIZE (0) OR NOOPTIMIZE specifies no optimization.
OPTIMIZE (1) specifies register and branch
optimization.
OPTIMIZE (2) specifies partial code-movement
optimization. 0PTIffIZE(2) will not relocate any code
when it has been determined that relocating the code
under consideration would cause unplanned or unexpected
interrupts.
OPTIMIZE (3) specifies full code-movement optimization.
SC(namel>na?re2> . . . )
Specifies the names of subroutines for which only the
locations of character arguments are to be passed. (An
entry for the length of the character string is not made in
the parameter list.) This option can be repeated; the lists
will be combined. On an 3»PR0CESS statement, multiple names
can be supplied as parameters to the SC option. However,
only one parameter for each SC option can be supplied on
invocation of the compiler (EXECUTE options).
Compiling Your Program — Advanced Programming
73
SOURCE | NOSOURCE
Speci fi es whether or not the source listing is to be / #~ik
produced. \^J
TERMINAL I NOTERMINAL
Specifies whether or not error messages and compiler
diagnostics are to be written on the output data set and
whether or not a summary of error messages is to be printed.
XREFINOXREF
Specifies whether or not a cross-reference listing i s to be
produced.
MODIFYING BATCH COMPILATION OPTIONS — ©PROCESS STATEMENT
In a batch compilation for either OS/VS or DOS/VS, the options
specified when the compiler is invoked remain in force for all
the 3PR0CESS statement.
To change the compiler options* place the ^PROCESS statement
just before the first statement in the source program. The
following rules apply :
• ^PROCESS must appear in columns 1 through 8 of the statement.
• The 3JPR0CESS statement can be followed by compiler options
in columns 9 through 72 of the statement. The options must be
separated by commas or blanks,
• The 3JPR0CESS statement cannot be continued to multiple
lines. However, multiple process statements can be supplied
for a program unit. Columns 9 through 72 of a following
PROCESS statement ar& appended to the previous ^PROCESS
statement. /^~^ I
All compiler options except OBJECT and DECK are permissible. H " J * /
• All options npjk to be given default values must be specified,
including the overriding options in the EXEC statement.
(3PR0CESS overrides all options specified in the EXEC
statement . )
JOS CONTROL CONSIDERATIONS— OS/VS
The simplest way to execute your program under OS/VS is to use
one of the cataloged procedures described in "Using and
Modifying Cataloged Procedures — OS/VS."
However, the cataloged procedures may not give you the
programming flexibility you need for your more complex data
processing jobs, and you may need to specify your own job control
statements.
The job control statements you can use for any OS/VS job are
outlined below. Reference documentation for them is given in the
VS FORTRAN Application Programming' System Services Reference
Supplement .
IDENTIFYING A JOB— OS/VS JOB STATEMENT
The JOB statement begins each OS/VS job you enter into the
system J
//jobname JOB [parameters}
The jobname identifies this job to the system. The jobname must
conform to the standards defined in 0S/VS2 MVS JCL .
The parameters let you request the following:
74 VS FORTRAN Appl i cat i on Programmi ng* Guide '
Accounting information for this job
Your name
The type of system messages to be written
Conditions for terminating job execution
Assignment of input and output classes
Job pr i ori ty
Main storage requirements
Time limit for the job
REQUESTING EXECUTION— OS/VS EXEC STATEMENT
! -c
You use the EXEC job control statement to request that execution
of a program or procedure is to begin.
//[stepname] EXEC CPROC=]procname
[PARM=opti on[ ,opti on] ...
Cothei — parameters]
The stepname identi f i es thi s job step.
The procname is the name of a cataloged procedure you want
executed.
To request a FORTRAN compilation, you specify PR0C=F0RTVS.
The PARM parameter lets you specify any options that differ from
the defaults.
(See "Using the Compile-Time Options" and "Link-Editing Your
Program — -Advanced Programmi ng. ")
The other parameters let you request other information*
A job step name (when its necessary for a later job step to
refer to information from this job step)
Conditions for bypassing execution of this job step
Accounting information for this job step
Time limit for this step
Main storage requirements
DEFINING FILES— OS/VS DD STATEMENT
To define files you may need, you specify the DD statement '
//[ddname Iprocstep. ddname] DD C data- set-name] [other-parameters]
The ddname identifies the data sets defined by this DD statement
to the compiler, linkage editor, loader, or to your program. The
ddnames you can use for VS FORTRAN are shown in Figure 16.
The procstep identifies the procedure step.
The data-set-name is the qualified name you've given the data set
that contains your data ,f i les; for example, the name of the
library containing the files you use in your INCLUDE statements.
The other parameters let you request additional information J
• The location of this data set in the system configuration
Compiling Your Program — Advanced Programming
75
The status of this data set at the beginning and end of the
job step
Label information for this data set f s volume
Optimization of input/output channel usage
Device type
Space allocation (for data sets on direct access devices)
Characteristics of the data set records
Reference documentation on these job control statements is given
i n the VS FORTRAN Application Programming* System Services
Reference Supplement .
REQUESTING COMPILATION — OS/VS
In one job step under OS/VS, you can request compilation for a
single source program or for a series of source programs.
COMPILING A SINGLE SOURCE PROGRAM— OS/VS
For compiling a single source program under OS/VS, the sequence
of job control statements is*
//JOB Statement
//EXEC Statement (to execute the VS FORTRAN compiler)
//DD Statements for Compilation (as required)
(Source program to be compiled)
/*Data Delimiter Statement (only if source program is on cards)
//End-of-Job Statement
These job control statements are deer i bed in the VS FORTRAN (^^
Application Programming* System Services Reference Supplement . *%^j?
BATCH COMPILATION OF MORE THAN ONE SOURCE PROGRAM — OS/VS
In OS/VS , you can compile more than one source program during the
execution of one job. The sequence of job control statements you
use is*
//JOB Statement
//EXEC Statement (to execute the VS FORTRAN compiler)
//DD Statements (as required)
aPROCESS Statement (if needed to modify compiler options)
(First source program to be compiled)
3PR0CESS Statement (if needed to modify compiler options)
(Second source program to be compiled)
2PR0CESS Statement (if needed to modify compi ler options)
(Third source program to be compiled)
/*Data Delimiter Statement (only if source program is on cards)
//End-of-Job Statement
These job control statements are deer i bed in the VS FORTRAN
Application Programming* System Services Reference Supplement .
The 3PR0CESS statement is described in "Modifying Batch
Compilation Options — aPROCESS Statement" on page 74.
COMPILATION DATA SETS — OS/VS
For compilation under OS/VS, there are two required data sets and
several optional ones.
e>
76 VS FORTRAN Application Programming: Guide
REQUIRED OS/VS COMPILE-TIME DATA SETS
You must ensure that the following ddnames are available during
compilation. They may be available through the cataloged
procedure you're using for compilation (check with your system
administrator). If they aren't, you must specify them through a
DD statement*
SYSIN — to define the source input data set
SYSPRINT — to define the printed output data set
OPTIONAL OS/VS COMPILE-TIME DATA SETS
You specify the following data sets, through a DD statement, only
if you're requesting specific compilation features*
SYSLIN — if you're requesting that an object module be
produced (through the OBJECT compiler option); it defines
the object module data set.
SYSPUNCH — if you're requesting an object module punched on
cards (through the DECK compiler option); it defines the
card image data set on which the object module is punched.
SYSTERM — when the TERMINAL compi le-time option is in effect,
you specify SYSTERM as the data set that will contain printed
compiler output (that is, error messages, source statements
in error, and compiler statistics).
SYSLIB — if your source program uses the INCLUDE statement,
this ddname defines the library input data set. For INCLUDE
statements, the data set records must be unblocked, fixed
length, 80-character records with DS0RG=PO.
USING AND MODIFYING CATALOGED PROCEDURES — OS/VS
When you're operating under OS/VS, there are a number of
cataloged procedures you can use to compile, link-edit (or
load), and execute your VS FORTRAN programs'*
1. Compile only — FORTVC, shown in Figure 16
2: Compile and Link-edit — FORTVCL, shown in Figure 17
3. Compile, Link-edit, and Execute — FORTVCLG, shown in
Figure 18
4. Link-edit and Execute — FORTVLG, shown in Figure 19
5. Execute only — FORTVG, shown in Figure 20
6. Compile and Load — FORTVCG, shown in Figure 21
7. Load only — FORTVL, shown in Figure 22
As the figures show, many of the JCL parameters in these
procedures are coded as symbolic parameters (the parameter name
is preceded by an ampersand). The IBM-supplied default value for
each symbolic parameter is defined in the PROC statement that
begins each procedure.
This means that you can execute the procedures without making any
changes to them, or you can modify them for any particular run.
(The use of symbolic parameters is explained in the job control
language publications for the system you're operating under.)
Jt>
Compiling Your Program — Advanced Programming 77
//FORTVC
//
//
//*
//*
//*
//x
//x
//x
//x
//x
//x
//x
//x
//FORT
//
//cycpoTMT
//systerm'
//syspunch
//SYSLIN
//
PROC FVPGM=FORTVS,FVREGN=80 0K,FVPDECK=NODECK,
FVPOLST=NOLIST,FVPOPT=0,FVTERM= , SYSOUT=A , ,
FVLNSPC='3200,(25,6) f
PARAMETER DEFAULT-VALUE
EXEC
USAGE
COMPILER NAME
FORT-STEP REGION
COMPILER DECK OPTION
COMPILER LIST OPTION
COMPILER OPTIMIZATION
FORT. SYSTERM OPERAND
FORT. SYSLIN SPACE
PGM=*FVPGM,REGI0N=&FVREGN,C0ND=(4,LT),
PARM=» * FVPDECK, &FVPOLST, OPT (&FVPOPT)'
nn cvcmiT = A nrnirni vct7c=taoq
DD &FVTERM
DD SYSOUT=B,DCB=BLKSIZE=3440
DD DSN = mOADSET,DISP = CMOD,PASS),UNIT=SYSDA,
SPACE=($FVLNSPC),DCB=BLKSIZE=320
FVPGM
FORTVS
FVREGN
256K
FVPDECK
NODECK
FVPOLST
NOLIST
FVPOPT
FVTERM
SYSOUT=A
FVLNSPC
3200,(25,6)
Figure 16. Cataloged Procedure FORTVC, OS/VS
PARAMETER DEFAULT-VALUE
FVPGM
FVREGN
FVPDECK
FVPOLST
FVPNAME
FVPOPT
FVTERM
PGMLIB
FORTVS
256K
NODECK
NOLIST
MAIN
SYSOUT=A
UGOSET
USAGE
COMPI
FORT-
COMPI
COMPI
COMPI
COMPI
FORT.
LKED.
//FORTVCL PROC FVPGM=FORTVS, FVREGN=800K, FVPDECK=NODECK,
// FVPOLST=NOLIST,FVPOPT=0,FVTERM='SYSOUT=A»,
// FVPNAME=MAIN,PGMLIB='aaGOSET*
//x
//x
//x
//x
//x
//x
//x
//x
//x
//x
//x
//x
//FORT EXEC
//
//SYSPRINT
//SYSTERM
//SYSPUNCH
//SYSLIN
//
//LKED EXEC
//
//SYSPRINT
//SYSLIB
//SYSUT1
//SYSLMOD
//
//SYSLIN
//
LER NAME
STEP REGION
LER DECK OPTION
LER LIST OPTION
LER NAME OPTION
LER OPTIMIZATION
SYSTERM OPERAND
SYSLMOD DSNAME
H^y
PGM=*FVPGM,REGI0N=SFVREGN,C0ND=(4,LT),
PARM=»&FVPDECK,8iFVPOLST,OPT(«FVPOPT),NAME(8iFVPNAME)*
DD SYSOUT=A,DCB=BLKSIZE=3429
DD &FVTERM
DD SYSOUT=B,DCB=BLKSIZE=3440
DD DSN = mOADSET,DISP = (MOD,PASS),UNIT = SYSDA,
SPACE=(320 0,(25,6)),DCB=BLKSIZE=320
PGM=IEWL,REGION=20 0K,COND=(4,LT),
PARM=»LET, LIST, MAP, XREF'
DD SYSOUT=A
DD DSN=SYS1.VF0RTLIB,DISP=SHR
DD UNIT=SYSDA,SPACE=( 1024, (200,20))
DD DSN = &PGMLIB.UFVPNAME),DISP = (,PASS),UNIT = SYSDA,
SPACE=(TRK,(10,10,1),RLSE)
DD DSN = &UOADSET,DISP = (OLD, DELETE)
DD DDNAME=SYSIN
Figure 17. Cataloged Procedure FORTVCL, OS/VS
\J'
78 ,? S FORTRAN Application Programming: Guide
g™\
//FORTVCLG PROC
//
//
//
//x
//x
//x
//x
//x
//x
//x
//x
//x
//x
//x
//x
//x
//x
//FORT EXEC
//
//SYSFRINT
//SYSTERM
//SYSPUNCH
//SYSLIN
//
//LKED EXEC
//
//SYSPRINT
//SYSLIB
//SYSUT1
//SYSLMOD
//
//SYSLIN
//
//GO EXEC
//FT05F001
//FT06F001
//FT07F001
FVPGM=FORTVS,FVREGN=80 0K,FVPDECK=NODECK,
FVPOLST=NOLIST,FVPOPT=0,FVTERM='SYSOUT=A',GOREGN=10 0K,
GOF5DD= , DDNANE=SYSIN' ,GOF6DD='SYSOUT=A» ,
GOF7DD= f SYSOUT=B f
PARAMETER DEFAULT-VALUE
FVPGM
FVREGN
FVPDECK
FVPOLST
FVPOPT
FVTERM
GOREGN
G0F5DD
G0F6DD
GOF7DD
FORTVS
800K
NODECK
NOLIST
SYSOUT=A
100K
DDNAME=SYSIN
SYSOUT=A
SYSOUT=B
USAGE
COMPI
FORT-
COMPI
COMPI
COMPI
FORT.
GO-ST
GO. FT
GO. FT
GO. FT
LER NAME
STEP REGION
LER DECK OPTION
LER LIST OPTION
LER OPTIMIZATION
SYSTERM OPERAND
EP REGION
05F001 OPERAND
06F001 OPERAND
07F001 OPERAND
PGM=&FVPGM, REGIONS FVREGN, COND = ( 4, LT),
PARM^iFVPDEdCfcFVPOLSTfOPTUFVPOPT)'
DD SYS0UT=A,DCB=BLKSIZE=3429
DD JFVTERM
DD SYSOUT=B,DCB=BLKSIZE=3440
DD DSN = &UOADSET,DISP = (MOD,PASS),UNIT = SYSDA,
SPACE=(320 0,(25,6)),DCB=BLKSIZE=3200
PGM=IEWL,REGION=20 0K,COND=(4,LT),
PARM='LET,LIST,MAP,XREF f
DD SYSOUT=A
DD DSN=SYSl.VFORTLIB,DISP=SHR
DD UNIT=SYSDA,SPACE=( 1024, (200,20))
DD DSN = UGOSET (MAIN ),DISP=(, PASS), UNIT = SYSDA,
SPACE=(TRK,(10,10,1),RLSE)
DD DSN=*&LOADSET,DISP=( OLD, DELETE)
DD DDNAME=SYSIN
PGM=x.LKED.SYSLM0D,REGI0N=*G0REGN,C0ND=(4,LT)
DD &GQF5DD
DD 4GOF6DD
DD &GOF7DD
Figure 18. Cataloged Procedure FORTVCLG, OS/VS
Compiling Your Program — Advanced Programming
79
//FORTVLG PROC
//
//
//
//*
//x
//X
//x
//x
//x
//x
//x
//x
//x
//x
//x
//LKED EXEC
//
//SYSPRINT
//SYSLIB
//SYSUT1
//SYSLMOD
//
//SYSLIN
//GO EXEC
//
//FT05F001
//FT06F001
//FT07F001
LKLNDD= , DDNAME=SYSIN , ,GOPGM=MAIN,GOREGN=100K,
G0F5DD=»DDNAME=SYSIN f ,
GOF6DD='SYSOUT=A»,
GOF7DD= f SYSOUT=B f
PARAMETER DEFAULT-VALUE
LKLNDD
GOPGM
GOREGN
G0F5DD
G0F6DD
GOF7DD
DDNAME=SYSIN
MAIN
10OK
DDNAME=SYSIN
SYSOUT=A
SYSOUT=B
USAGE
LKED. SYSLIN OPERAND
OBJECT PROGRAM NAME
GO-STEP REGION
GO.FT05F001 OPERAND
GO.FT06F001 OPERAND
GO.FT07F001 OPERAND
PGM=IEWL -, REGIGN=20GK,
PARM^LET^LIsfVMAP^XREF'
DD SYSOUT=A
DD DSN=SYSl.VFORTLIB,DISP=SHR
DD UNIT=SYSDA,SPACE=(CYL,(1,1))
DD DSN = 4&G0SETUG0PGM),DISP = (,PASS),UNIT = SYSDA,
SPACE=(TRK,(10,10,1),RLSE)
DD &LKLNDD
PGM=*. LKED. SYSLMOD, REGION=*GOREGN,
C0ND=C4,LT,LKED)
DD SG0F5DD
DD &GOF6DD
DD &GOF7DD
Figure 19. Cataloged Procedure FORTVLG, OS/VS
//FORTVG
PROC
GOPGM=MAIN,GOREGN=10 0K,
//
G0F5DD= , DDNAME=SYSIN' ,
//
G0F6DD= f SYS0UT=A',
//
G0F7DD= f SYS0UT=B'
//x
//x
//x
PARAMETER DEFAULT-VALUE
//x
//x
GOPGM MAIN
//x
GOREGN 100K
//x
G0F5DD DDNAME=SYSIN
//x
GOF6DD SYSOUT=A
//x
GOF7DD SYSOUT=B
//x
//x
//GO
EXEC
PGM=*G0PGM,REGI0N=4G0REGN
//FT05F001
DD &G0F5DD
//FT06F001
DD &G0F6DD
//FT07F001
DD XGOF7DD
USAGE
PROGRAM NAME
GO-STEP REGION
GO.FT05F001 DD OPERAND
GO.FT06F001 DD OPERAND
GO.FT07F001 DD OPERAND
Figure 20. Cataloged Procedure FORTVG, OS/VS
80 VS FORTRAN Appli cati on Programming* Guide
//FORTVCG PROC FVPGM=FORTVS, FVREGN=800K,FVPDECK=NODECK,
// FVFOLST=NOLIST,FVPOPT=0,FVTERM= f SYSOUT=A' ,
FVLNSPC='3200,(25,6)»,
G0F5DD= f DDNAME=SYSIN f ,
G0F6DD='SYS0UT=A f ,
G0F7DD= f SYS0UT=B' ,GOREGN=100K
//
//
//
//
//x
//x
//X
//*
//X
//*
//*
//X
//X
//X
//*
//X
//X
//*
//*
//FORT EXEC
//
//SYSPRINT
//SYSTERM
//SYSFUNCH
//SYSLIN
//
//GO EXEC
//
//SYSLIN
//SYSLOUT
//SYSLIB
//FT05F001
//FT06F001
//FT07F001
PARAMETER DEFAULT-VALUE
FVPGM
FVREGN
FVPDECK
FVPOLST
FVPOPT
FVTERM
FVLNSPC
G0F5DD
GOF6DD
GOF7DD
GOREGN
FORTVS
256K
NODECK
NOLIST
SYSOUT=A
3200,(25,6)
DDNAME=SYSIN
SYSOUT=A
SYSOUT=B
100K
USAGE
COMPI
FORT-
COMPI
COMPI
COMPI
FORT.
FORT.
GO. FT
GO. FT
GO. FT
GO-ST
LER NAME
STEP REGION
LER DECK OPTION
LER LIST OPTION
LER OPTIMIZATION
SYSTERM OPERAND
SYSLIN SPACE
05F001 OPERAND
06F001 OPERAND
07F001 OPERAND
EP REGION
PGM=&FVPGM,REGION=&FVREGN,COND=(4,LT),
PARM= , &FVPDECK,«FVPOLST,OPT(&FVP0PT)'
DD SYS0UT=A,DCB=BLKSIZE=3429
DD &FVTERM
DD SYSOUT=B,DCB=BLKSIZE=3440
DD DSN=S&LOADSET,DISP= (MOD, PASS ) , UNIT=SYSDA,
SPACE=(&FVLNSPC),DCB=BLKSIZE=320
PGM=LOADER,REGION=&GOREGN,
PARM='LET,NORES,EP=MAIN f
DD DSN = mOADSET,DISP = ( OLD, DELETE)
DD SYSOUT=A
DD DSN=SYS1.VF0RTLIB,DISP=SHR
DD 8G0F5DD
DD SG0F6DD
DD &GOF7DD
Figure 21. Cataloged Procedure FORTVCG, OS/VS
//FORTVL PROC
//
//
//*
//x
//x
//x
//x
//x
//x
//x
//x
//x
//GO EXEC
//
//SYSLOUT
//SYSLIB
//FT05F001
//FT06F001
//FT07F001
GOF5DD= f DDNAME=SYSIN f ,
G0F6DD='SYS0UT=A',
G0F7DD= f SYS0UT=B f ,GOREGN=10 0K
PARAMETER DEFAULT-VALUE
G0F5DD
GOF6DD
GOF7DD
GOREGN
DDNAME=SYSIN
SYSOUT=A
SYSOUT=B
100K
USAGE
GO.FT05F001 OPERAND
GO.FT06F001 OPERAND
GO.FT07F001 OPERAND
GO-STEP REGION
PGM=LOADER , REGI0N=4G0REGN ,
PARM= ? LET,NORES,EP=MAIN'
DD SYSOUT=A
DD DSN=SYS1.VF0RTLIB,DISP=SHR
DD &GOF5DD
DD &GOF6DD
DD &GOF7DD
Figure 22. Cataloged Procedure FORTVL, OS/VS
The following sections describe how you can temporarily modify
the OS/VS cataloged procedures.
Compiling Your Program — Advanced Programming
81
Modifying PROC statements— OS/VS
You can modify PROC statement parameters by specifying changes
in the EXEC statement that calls the procedure. When you change a
PROC statement parameter, you're assigning a temporary value to
a symbolic parameter; when the cataloged procedure is executed,
this value is transferred to the appropriate parameter in the
EXEC or DD statement.
For example, to change the region size of the compiler from 256K
to 200K bytes and the card punch output in the load module from
output class B to output class C, you can use the following
statement '
// EXEC FORTVCLG,FVREGN=200K,
// G0F7DD='SYS0UT=C
Note that you don't code the ampersand preceding a symbolic
parameter; and that you us© apostrophes to enclose a value
containing a special character, as in SYS0UT=C.
Before you execute the call, the appropriate statements in
FORTVCLG appear as follows:
//FORT EXEC PGM=&FVPGM,REGION=&FVREGN,
//FT07F001 DD 4G0F7DD
When the cataloged procedure is called, the statements appear as
though they were coded :
//FORT EXEC PGM=FORTVS,REGION=200K, . . .
//FT07F001 DD SYS0UT = C VV
Note that a symbolic parameter not changed (PGM=4FVPGM) retains
its default value.
Another method you can use to change a parameter value i s to
assign the new value directly to the parameter itself, not the
symbolic parameter associated with it. For example, you can
change the region size by specifying REGION=200K in place of
FVREGN=200K, (In this example, you'd be changing the region size
for all job steps; to change the region size for the compile job
step only, you must code the appropriate job step name, FORT, in
the parameter; for example, REGION. FORT = 200K. )
Modifying EXEC Statements — OS/VS
To modify EXEC statement parameters, you must change the EXEC
statement that calls the procedure.
The following rules apply to EXEC statement modi f i cat i ons J
• Parameters are overridden in their entirety. If you want to
retain some options while changing others, you must specify
those options to be retained. (However, if you don't
override them, default options remain in effect.)
• To specify parameters for individual job steps, use the
form:
keyword. stepname=value
where*
\J"
82 VS FORTRAN Application Programming* Guide
c
keyword
indicates the parameter name
stepname
indicates the procedure name, for example,
REGION. FORT=value
Parameters not specifying stepname are assumed to apply to all
steps in the procedure; for example, REGION=value applies to the
entire cataloged procedure.
• To make changes to more than one step, you must specify all
changes for an earlier step before those for later steps.
• You can combine changes to symbolic parameters and EXEC
statement parameters on the same card.
You're allowed to make the following modi f icati ons:
1. Override existing parameters * For example, to modify the
LKED step by raising the condition code from 4 to 8, use the
statement *
//SOMENAME EXEC FORTVCLG,
// C0ND.LKED=(8,LT)
2. Add new parameters ' For example, to modify FORT by
specifying the TIME parameter, use the statement 5
//ANYNAME EXEC FORTVCLG, TIME. F0RT=5
3. Change more than one paramet er* For example, to modify FORT
by changing the region from 256K to 200K bytes and the PARM
option NOLIST to LIST, use the statement*
//SOME EXEC FORTVCLG,
// REGION. FORT=200K,
// PARM.FORT=LIST
4. Change more than one step * For example, to modify FORT by
specifying TIME and to modify LKED by raising the condition
code from 4 to 8, use the statement'
//ANY EXEC FORTVCLG, TIME. F0RT=5,
// C0ND.LKED=(8,LT)
Note that you can add a parameter while revising an existing
one.
5. Combine changes to symbolic parameters and EXEC statement
parameters ' For example, to modify the symbolic parameter
FVREGN, and to add the TIME parameter to the FORT EXEC
statement, use the statement*
//ANY EXEC FORTVCLG, FXREGN=200K,
// TIME.F0RT=5
Modifying DD Statements — OS/VS
You modify the DD statement by submitting new DD statements after
the EXEC statement that calls the procedure. As with
modifications to EXEC statements, you can override or add
parameters to DD statements in one or many steps. In addition,
you can add entirely new DD statements to any step (whenever you
supply a SYSIN DD statement, you're adding a new DD statement.)
The following rules apply to DD statement modifications'
• Parameters are overridden in their entirety except for the
DCB parameter, in which individual subparameters can be
overri dden.
Compiling Your Program — Advanced Programming 83
• Parameters are nullified by specifying a comma after the
equal sign in the parameter; for example, UNIT=, . -~ !
• Parameters are overridden when mutually exclusive parameters ^U#
are specified in their place; for example, SPLIT overrides
SPACE.
• DD statements must indicate the related procedure step,
using the form //procstep. ddname ; for example, //FORT . SYSIN.
• To make changes in more than one step, you must specify all
changes for an earlier step before those for later steps.
• To modify more than one DD statement in a job step, you must
specify the applicable DD statements in the same sequence as
they appear in the cataloged procedure.
You can make the following modifications 1
1» O verride existing param e ters . For example, to modify
SYSLMOD so that the load module is stored in a private
library rather than in the system library, you can specify
the statement *
//LKED. SYSLMOD DD DSNAME=PRIVCPROG) ,
// DISP=(MOD,PASS)
In this example, the library PRIV is assumed to be an old
library and is cataloged (that is, VOLUME and UNIT
parameters need not be specified). Note that in subsequent
uses of the library you must submit a JOBLIB DD statement
defining the private library, to make the library available
to the system.
2. Add new parameters . For example, to store the load module in
a new, uncataloged library, you must specify the VOLUME, ^-^ ]
UNIT, and SPACE parameters. For example* (
//LKED. SYSLMOD DD DSNAME=MYLIB(FIRST) ,
// DISP=(NEW,PASS),
// V0LUME=SER=11234,
// UNIT=SYSDA,
// SPACE=(TRK, (50,10,2))
3. Add new DD statements . For example, to add new data sets
having data set reference numbers 10 and 15 for processing in
the GO step, you can specify the statements*
//GO.FT10F001 DD DSNAME=DSET1 ,
// DISP=(NEW, DELETE),
// V0LUME=SER=T1132,
// UNIT=TAPE
//GO.FT15F001 DD DSNAME=DSET2,
// DISP=(, DELETE),
// V0LUME=SER=DA45,
// UNIT=3350,
// SPACE=(TRK, (10,10))
Note that you can explicitly define a data set as new (DISP
parameter for FT10F001), or, alternatively, permit the
system to assume a new data set by default (DISP in
FT15F001).
JOB CONTROL CONSIDERATIONS— DOS/VSE
Under DOS/VSE, the simplest way to execute your program is to use
one of the procedures outlined in "Requesting Compilation
Only— DOS/VSE."
However, these procedures may not give you the programming
flexibility you need for your more complex data processing jobs,
o
84 VS FORTRAN Application Programming* Guide
and you may need to specify your own job control statements> or
write your own cataloged procedures.
USING DOS/VSE JOB CONTROL STATEMENTS
The job control statements you can use for any DOS/VSE job are
outlined below. Reference documentation for them is given in the
VS FORTRAN Application Programming' System Services Reference
Supplement .
c
IDENTIFYING A JOB — DOS/VSE JOB STATEMENT
The JOB statement begins each DOS/VSE job you enter into the
system*
// JOB jobname
The jobname is the name you're giving to this job.
You can also code comments in the JOB statement, including job
accounting information.
SPECIFYING LINKAGE-EDITOR OPTIONS — DOS/VSE OPTION STATEMENT
Under DOS/VSE, you use the OPTION statement to request the
linkage editor, and linkage-editor options.
// OPTION optionC, option] ...
In the compilation step, you can use the OPTION statement to
specify that the object module is to be link-edited*
• Specify OPTION LINK for link-editing only.
• Specify OPTION CATAL for link-editing and cataloging in the
core image library.
DEFINING FILES— DOS/VSE ASSGN STATEMENT
You use the ASSGN statement to assign a logical input/output unit
to a physical device. (You need do this only if the logical unit
is different from that defined during system generation.)
// ASSGN SYSxxxE ,devi ce-addressj symboli c-unitH , other-entries]
SYSxxx is a valid system logical unit or programmer logical unit.
The units valid for VS FORTRAN are shown in Figure 23.
(See the VS FORTRAN Application Programming' System Services
Reference Supplement . )
The device-address specifies the channel and unit number for the
speci f i c devi ce.
The symbolic-unit specifies a valid system or programmer logical
uni t .
You can also optionally specify other entries*
• That the logical unit is to remain unassigned, and that any
program references to it are to cause immediate job
cancellation
• That the logical unit is to remain unassigned and that all
program references to it are to be ignored, without
canceling the job
• That this assigned unit is to be used as an alternate unit
when the capacity of the original device is reached
Compiling Your Program — Advanced Programming 85
• Tape mode specifications
(See the VS FORTRAN Application Programming- System Services
Reference Supplement . )
DEFINING FILES ON DIRECT ACCESS DEVICES— DOS/VSE
For files on direct access devices, you must specify a DLBL
statement and an EXTENT statement, in addition to the ASSGN
statement .
DLBL Statement — DOS/VSE
You use the DLBL statement to supply label information for both
file creation and file retrieval.
// DLBL filename Cdata-set-i dl [, date] [, code]
The filename is the filename that corresponds to the logical
unit. See Figure 23 for a list of valid system filenames.
The data-set-id specifies the name associated with this data set
on the volume. If you omit this field, the filename is used.
The date specifies the retention period or expiration date of the
data set.
The code specifies the type of data set label to be used:
sequential, direct or VSAM.
Other fields can also be specified.
For reference documentation about the DLBL statement, see the VS
FORTRAN Application Programming' System Services Reference
Supplement .
EXTENT Statement — DOS/VSE
You use the EXTENT statement to assign a data area on a direct
access device to a file in your program.
// EXTENT SYSxxx, , , , Crelat i ve-track] , tno-of-tracks]
SYSxxx is a valid system logical unit or programmer logical unit.
See Figure 23 for units valid for VS FORTRAN.
For reference documentation, see the VS FORTRAN Application
Programming^ System Services Reference Supplement .
The relative-track specifies the position of the track (relative
to zero) where the extent begins.
The no-of-tracks specifies the number of the tracks to be
allocated to the extent.
You can also specify other optional entries*
• Whether the extent is split cylinder or no split cylinder
• The number of split cylinder tracks (if this is a split
cylinder extent)
REQUESTING EXECUTION— DOS/VSE EXEC STATEMENT
ff~>\;
\
You use the EXEC job control statement to request that execution
i s to begi n . *~'\'\
86 VS FORTRAN Appli cati on Programmi ng* Guide
// EXEC [[PGM = ] program-name ],SIZE = AUTO I number, -
CP ARM= f opt i on' C, 1 option']. . .3
// EXECCPROC=program-name][,SIZE=AUTO|number]
The program-name identifies either J
• When you specify PGM=, a phase in the core' image library.
For example, the VS FORTRAN compiler* the linkage editor, or
a phase (problem program object module).
To request a FORTRAN compilation, you specify PGM=VFORTRAN.
You can omit the program-name if the phase to be executed has
just been processed by the linkage editor.
When you're requesting a VS FORTRAN compilation, you should
specify the SIZE parameter as 800K.
Use the PARM parameter to request compiler options that
differ from those set for your organization. The options can
be any of those described in "Using the Compile-Time
Opti ons."
• When you specify PR0C=, a procedure in the procedure
li brary .
For reference documentation about these job control statements,
see the VS FORTRAN Application Programming- System Services
Reference Supplement .
REQUESTING COMPILATION — DOS/VSE
Under DOS/VSE, in one job you can request compilation for a
single source program or for a series of source programs.
COMPILING A SINGLE SOURCE PROGRAM — DOS/VSE
For a single source program, the sequence of job control
statements you use is :
// JOB Statement
// OPTION Statement (as required)
// ASSGN Statements for Compilation (as required)
// DLBL Statements for Compilation (as required)
// EXTENT Statements for Compilation (as required)
// EXEC Statement (to execute the VS FORTRAN compiler)
(Source program to be compiled)
/* Data Delimiter Statement (only if source program is on cards)
/& End-Of-Job Statement
BATCH COMPILATION OF MORE THAN ONE SOURCE PROGRAM — DOS/VSE
For a series of programs, the sequence of job control statements
you use i 5:
// JOB Statement
// OPTION Statement (as required)
// ASSGN Statements for Compilation (as required)
// DLBL Statements for Compilation (as required)
// EXTENT Statements for Compilation (as required)
// EXEC Statement (to execute the VS FORTRAN compiler)
(First source program to be compiled)
aPROCESS Statement (if needed to modify compiler options)
(Second source program to be compiled)
3PR0CESS Statement (if needed to modify compiler options)
(Third source program to be compiled)
/* Data Delimiter Statement (only if source program is on cards)
/% End-Of-Job Statement
Compiling Your Program — Advanced Programming 87
These job control statements are described in the VS FORTRAN
Application Programming* System Services Reference Supplement .
■• ' )
The ^PROCESS statement is described in "Modifying Batch *^>
Compilation Options — ^PROCESS Statement" on page 74. 4_/
COMPILE-TIME FILES— D03/VSE
When you're compiling under DOS/VSE, most of the the system files
the compiler uses— SYSIPT, SYSLST, SYSPCH, SYSLNK, and
5YSL0G- — are predefined and always available; therefore* you
never have to specify them.
However, if your source program uses the INCLUDE statement, you
must specify SYSSLB (for the system or a private source statement
library) in an ASSGN statement. The file records representing
the source statements to be included must be unblocked,
fixed-length, 80-character records. The file to be included must
be cataloged in the G sublibrary.
WRITING AND MODIFYING CATALOGED PROCEDURES — DOS/VSE
To catalog a procedure in the procedure library, you submit a
CATALP statement specifying the procedure name: Rules for naming
the procedures are given in DOS/VSE System Control Statements .
The control statements to be cataloged follow the CATALP
statement; they can be job control or linkage editor control
statements or both. The end of the control statements to be
cataloged must be indicated by an end-of-procedure delimiter,
usually a / + delimiter.
Each control statement cataloged in the procedure library should
have a unique identity. This identity is required if you want to
be able to modify the job stream at execution time. Therefore, ^
when cataloging, identify each control statement in columns 73 y
through 79 (blanks may be embedded). v^'
RETRIEVING CATALOGED PROCEDURES — DOS/VSE
To retrieve a cataloged procedure from the procedure library,
you use the PROC parameter in the EXEC job control statement,
specifying the name of the cataloged procedure.
When the job control program starts reading the job control
statements in the input stream on SYSRDR and finds the EXEC
statement, it knows by the operand PROC that a cataloged
procedure i s to be inserted. It takes the name of the procedure
to be used and retrieves the procedure with that name from the
procedure library. At this point, SYSRDR is temporarily assigned
to the procedure library. Job control reads and processes the job
control statements as usual. The statement,
//EXEC MYPROGM
causes the program MYPROGM to be loaded and given control. When
execution of MYPROGM is complete, the job control program reads
the next statement or statements from the procedure library and
then finds the end-of-procedure indicator (/+). The
end-of-procedure indicator returns the SYSRDR assignment to its
permanent device, where the job control program finds the /&
statement and performs end-of-job processing as usual.
TEMPORARILY MODIFYING CATALOGED PROCEDURES — DOS/VSE
You can request temporary modification of statements in a
cataloged procedure by supplying the corresponding modifier \
statements in the input stream. {f~\ J
.88 VS FORTRAN Application Programming* Guide
c
COMPILER OUTPUT
Normally not all statements need to be modified; therefore, you
must establish an exact correspondence between the statement to
be modified and the modifier statement by giving them the same
symbolic name. This symbolic name may have from one to seven
characters, and must be specified in columns 73 through 79 of
both statements.
A single character in column 80 of the modifier statement
specifies which function is to be performed.
A indicates that the statement i s to be inserted after
the statement in the cataloged procedure that has the
same name.
B indicates that the statement i s to be inserted before
the statement in the cataloged procedure that has the
same name.
D indicates that the statement in the cataloged
procedure that has the same name is to be deleted .
Any other character or a blank in column 80 of the modifier
statement indicates that the statement is to replace (override)
the statement in the cataloged procedure that has the same name.
In addition to naming the statements and indicating the function
to be performed, you must inform the job control program that it
has to carry out a procedure modification. This is done as
follows*
1. By specifying an additional parameter (OV for overriding) in
the EXEC statement that calls the procedure, and
2. By using the statement // OVEND to indicate the end of the
modifier statements.
Placement of the // OVEND statement is as follows 1
• Directly behind the last modifier statement or,
• If the last modifier statement overwrites a // EXEC
statement and is followed by data input, between the /* and
/& delimiters.
The output the compiler gives you depends upon whether you've
accepted the default compiler options in force for your
organization, or whether you've modified the defaults using
explicit compiler options.
COMPILER OUTPUT WITH DEFAULT OPTIONS
If you accept the compiler default options, you'll usually get
the following output, printed in the following order (depending
on the default options in force for your organization) 1
• The date of the compilation — plus information about the
compiler and this compilation
• A listing of your source program
• Diagnostic messages telling you of errors in the source
program
• Informative messages telling you the status of the
compi lati on
(You'll also get a machine language object module.)
Note that these defaults may be modified for your organization.
Compiling Your Program — Advanced Programming 89
OUTPUT WITH EXPLICIT COMPILER OPTIONS
In addition to the output listed above, you can request each
compilation to produce the following additional output:
• A listing of the object module (LIST option), in
pseudo-assembler language (that is, the assembler
instructions that would have been generated for the object
module, if the compiler translated into assembler before
producing the machine code)
• A copy of the object module (DECK option), in card image
format
• A table of names and statement labels (MAP option) defined in
the source program
• A cross-reference listing (XREF option) of variables and
labels used in the source program
• Messages flagging statements that do not conform to the
language standard level you've chosen
Depending on the options you've chosen, the output you'll get is
shown in Figure 23 (Options that produce printed output are
shown in the order in which they are printed in the output
listing.)
For information on how to use the SOURCE, FLAG, MAP, XREF, and
FIPS options, see "Fixing Compile-Time Errors — Advanced
Progratnmi ng."
For information on how to use the DECK and OBJECT options, see
"Link-Editing Your Program — Advanced Programming."
For information on how to use the LIST option, see "Fixing
Execution-Time Errors — Advanced Programming."
CATALOGING YOUR SOURCE PROGRAM
If you wish, you can catalog your source program so that it's
available for future updating or correction.
How you do it depends upon the system you're using.
For VM/370-CMS considerations, see "Using VM/370-CMS with VS
FORTRAN."
For 0S/VS2-TSO considerations, see "Using 0S/VS2-TS0 with VS
FORTRAN."
CATALOGING YOUR SOURCE — OS/VS
You can create partitioned data sets for use in your SYSLIB data
set.
You can then catalog your source program, and source statement
sequences you'll use in INCLUDE statements, as members in that
library.
The library in which you catalog the source programs or statement
sequences is SYSLIB.
Then when you compile a program using the INCLUDE statement, you
must specify SYSLIB in a DD statement.
(See the VS FORTRAN Application Programming' System Services
Reference Supplement for additional detail.)
i J
o
90 VS FORTRAN Application Programming .« Guide
Compiler option Produces the Following output
SOURCE
XREF
LIST
MAP
FLAG
o
OBJECT
TERMINAL
DECK
Compilation Headings: Compiler Name and Release Level, Source
Program Name, Compilation Date, Listing Page Number
A listing of the source program
Cross reference information, showing each name and its type and
usage; as well as where each name and statement is defined and used
in the program
A listing of the object module — containing the relative location of
each generated constant or statement, the name of the source item
used in the instruction, plus sect i on headi ngs for: constants and
data addresses, common areas, equivalenced variables* address
constants, external references, parameter lists, the save area, and
generated instructions
A map of the source program, showing: the program name and size, name
usage and type, COMMON block information, and statement label usage
and location
A listing of error messages at the FLAG level you've chosen:
I requests a listing of all messages produced
W requests a listing of warning, error, severe error, and abnormal
termination messages (return code 4 or higher)
E requests a listing of error, severe error, and abnormal
termination messages (return code 8 or higher)
S requests a listing of severe error and abnormal termination
messages (return code 12 or higher)
For an explanation of these message codes, see "Diagnostic Message
Listing — FLAG Option"
The object module in machine language form, produced for linkage
editor input
Statistics and messages directed to the SYSTERM data set; also
produces an indexed summary of statistics and messages for each
compilation at the end of all compilations
The object module in machine language form to be produced as an
output data set for punching or for cataloging
Compilation statistics 5 source program name, number of statements
compiled, generated object module size (in bytes), the number and
severity of error messages produced
Figure 23. Compiler Output Using Explicit Options
CATALOGING YOUR SOURCE — DOS/VSE
You can catalog source programs and source statement sequences
you'll use in INCLUDE statements as books in the source statement
library, using the CATALS function.
Then, when you compile a program using the INCLUDE statement, you
must specify SYSSLB in an ASSGN statement.
(See the VS FORTRAN Application Programming: System Services
Reference Supplement for additional detail.)
Compiling Your Program — Advanced Programming
91
CA TALOGING YOUR OBJECT MODULE — DOS/VSE
You request an object module data set by specifying the DECK
compi ler opt i on.
You can use the object data set as input to the linkage editor or
loader in a later job step, or you can catalog it for later
reference.
The data set is a copy of the object module, in card image
format, which consists of dictionaries, text, and an
end-of-module indicator. (See "Object Module as Link-Edit Data
Set— -DECK Option" for additional detail.)
Once you've created the object module data set, you can catalog
it in a system or private library for future reference.
How you do it depends upon the system you're using.
For vfi/37G-Cn3 considerations, see "Using VM/37G-CMS with VS
FORTRAN."
For 05/VS2-TS0 considerations, see "Using 0S/VS2-TS0 with VS
FORTRAN."
CATALOGING YOUR OBJECT MODULE— OS/VS
You can create partitioned data sets for use in your SYSLIB data
set. You can then catalog your object module as a member in that
library.
The library in which you catalog your object module is SYSLIB. .
Then, when you link-edit and execute, you must specify SYSLIB in
a DD statement.
(See the VS FORTRAN Application Programming' System Services ( }•
Reference Supplement for additional detail.) '^^
CATALOGING YOUR OBJECT MODULE — DOS/VSE
You can catalog your object module in the relocatable library,
using the CATALR function.
Then, when you link-edit and execute, you must specify SYSRLB in
an ASSGN statement. (See the VS FORTRAN Application Programming-
System Services Reference Supplement for additional detail.)
92 VS FORTRAN Application Programming* Guide
USING VH/370-CMS KITH VS FORTRAN
You can use the facilities of VM/370-CMS, taking advantage of
quick terminal turnaround time, to develop VS FORTRAN programs,
You can compile your programs under VM/370-CMS and link-edit
them to run under MVS, 0S/VS1, or DOS/VSE; or you can compile*
link-edit, and execute them under VM/370-CMS. However, the
DOS/VSE version of the VS FORTRAN compiler and library is not
supported under CMS/DOS.
THE CP AND CMS COMMANDS
There are CMS and CP commands that help you create and edit your
source programs, link-edit your object modules, and execute your
load modules. The VM/370-CMS commands you'll use most frequently
are shown in Figure 25. Reference documentation for these
commands is given in the VS FORTRAN Application Programming*
System Services Reference Supplement .
US ING YOUR TERMINAL HITH CMS
You must log on your terminal, using the procedures your
organization has set up.
You can then use all the CP and CMS commands to develop, test,
and run your VS FORTRAN programs.
When you finish a terminal session, you log off in the usual way.
See the IBM Virtual Machine Faci 1 i tv/370 ' Terminal User's Guide
for documentation on terminal usage.
CREATING YOUR SOURCE PROGRAM—- CMS EDIT COMMAND
To create a source program file, you use the EDIT command. (Use
the EDIT command whenever you want to create a new file and also
whenever you want to edit an existing one.)
The EDIT subcommands (such as FILE, INPUT, GETFILE, etc.) help
you enter and edit the lines of source code.
To create a source program file, you specify the file type of
your source program file as FORTRAN.
For example, to create a source program file named MYPROG, you
speci fyJ
edit myprog fortran
This creates an empty file for you, with the filename MYPROG, and
the filetype FORTRAN. (If MYPROG already exists, the EDIT
command retrieves it for you and makes it available for editing.)
You can now enter your source program into the file, line by
line, according to the rules for fixed or free form source
programs.
Fixed format FORTRAN files contain 80-character records; you use
the first 72 characters for FORTRAN statements and continuation
lines.
Using VM/370-CMS with VS FORTRAN 93
CMS Command usage
ACCESS
EDIT
Activates a virtual disk for your use.
Puts you in EDIT mode to create and edit source
program and data files, and lets you use the
following EDIT subcommands*
FILE Places a file on your disk; takes you out
of EDIT mode.
FMODE Changes a file's filemode.
FNAME Changes a file's filename.
GETFILE Includes an existing file in the file you're
o
J?
INPUT Enters INPUT mode and accepts lines as part
of the file you're creating or editing.
QUIT Lets you stop editor processing without making
any permanent changes to the file.
EXEC Executes a file that consists of one or more
CMS commands.
FILEDEF Defines a file and its input/output devices.
FORTVS Invokes the VS FORTRAN compiler.
GLOBAL Specifies text libraries to be searched to
resolve external references in a program
being loaded.
INCLUDE Specifies additional TEXT files for use
during program execution.
LISTFILE Displays a list of your files.
LOAD Places a TEXT file in storage and
establishes the linkages for execution.
PRINT Prints a file on the off-line printer.
PUNCH Punches a card file on the off-line card punch.
RENAME Changes the filetype, filename, and/or filemode
of a file.
RUN Causes compilation, link-editing, and execution
of a source program file.
START Begins execution of a previously loaded and
li nk-edi ted f i le.
TYPE Types all or part\of a file.
Figure 24. VM/370-CMS Commands Often Used with VS FORTRAN
-%^r
~\ \
9A VS FORTRAN Application Programming: Guide
IBM EXTENSION
T
If you're using free form input, you can enter your source
program into the file, line by line, according to the rules for
free form source programs.
The maximum line length you can enter is 81 characters;
however, your source statements (excluding statement numbers
and statement break characters) can be up to 1320 characters
long.
You must ensure that sequence numbers do not appear in your
free form source (columns 73-80). The use of the filetype
FORTRAN (which is necessary for both fixed and free form
source) may automatically generate sequence numbers.
END OF IBM EXTENSION
(Reference documentation for creating source programs is given
i n the VS FORTRAN Application Programming* Language Reference
manual . )
USING THE FORTRAN INCLUDE STATEMENT — CHS
\7
If your source programs use the INCLUDE statement, you must
specify a FILEDEF command for SYSLIB, to make the library
containing the INCLUDE source code available. For INCLUDE
statements, the data set records must be unblocked,
fixed-length/ 80-character records.
1. Create one or more members with a filetype of COPY.
edit memberl copy a
INPUT
common/coml/al ,a2 ,a3,a4
common/com2/bl ,b2, b3,b4
file
2. Create a FORTRAN source program.
edit myprog fortran a
input
include (memberl)
z = al * bl
end
file
3. Create a CMS macro library
mac gen testOl memberl
COMPILING YOUR PRO€4y*M — US IN© CfIS
If you have used an INCLUDE statement in your source program, you
need to define SYSLIB for use by the compiler*'
filedef syslib disk testOl maclib a(perm
If you want to compile MYPROG with the defaults your organization
uses, you specify*
fortvs myprog
If, however, you want to compile MYPROG using nondefault
compiler opti ons>, speci fy , for example'
Using VM/370-CMS with VS FORTRAN
95
fortva myprog (free flag(e) deck map)
which tells the compiler that your source program is in free 1 f~>
form, and which gives you a compilation with only E leyel U J
messages or higher flagged (FLAG(E)), a copy of the object deck
(DECK), and a map of names and labels (MAP); all the options you
don't specify are the default options.
Reference documentation for the FORTVS command is given in the VS
FORTRAN Application Programming* System Services Reference
Supplement .
COMPILER OUTPUT— CMS
Depending on your organization's compile-time defaults and/or
the options you select in your FORTVS command, you may get a
LISTING file and/or a TEXT file as output, placed in your disk
storage for easy reference.
Tht LISTING File— CMS
The TEXT File— CMS
The LISTING file contains the compiler output listing; see
"Fixing Compi le-T ime Errors — Advanced Programming" in Part 2 for
an explanation of what the compiler output listing contains and
how to use it. It has the filename of your source program, and
the filetype LISTING. For example, the file for MYPROG is MYPROG
LISTING.
You can display the LISTING file, using the TYPE command'*
type myprog listing
and the listing is displayed at your terminal.
You can get a printed copy of the LISTING file, using the PRINT
command*
print myprog listing
and the listing is printed on the system printer.
The TEXT file contains the object code the compiler created from
your source program. The TEXT file contents are explained in
"Link-Editing Your Program — Advanced Programming" in Part 2.
It is placed in your storage with the filename of your source
program and a filetype of TEXT. For example, the file for MYPROG
is MYPROG TEXT.
This file remains in your disk storage until you erase it.
You can link-edit the TEXT file under any of the systems that VS
FORTRAN supports to get a load module (or phase).
MAKING LIBRARIES AVAILABLE— CMS GLOBAL COMMAND
Before you link-edit and execute your VS FORTRAN programs, you
must make the VS FORTRAN libraries accessible to your disk
storage. (Ask your system administrator for the name(s) of the
library files you can use.)
For example, if the names of the libraries available ar& FORTLIB
and CMSLIB, you specify*
global txtlib fortlib cmslib
\J-
96 VS FORTRAN Application Programming* Guide
g%
TXTLIB tells CMS that both FORTLIB and CMSLIB are text libraries
available to your programs.
It's a good idea to include a GLOBAL command in your profile
EXEC, so that the VS FORTRAN execution-time library modules are
always automatically available to you.
LOADING AND EXECUTING YOUR PROGRAM UNDER CHS
To load and execute your program under CMS, use the LOAD and
INCLUDE commands to create a load module from one or more object
modules (plus any needed VS FORTRAN library modules).
The input object modules must be TEXT files.
USING THE LOAD AND INCLUDE COMMANDS — CMS
o
You use the LOAD command to create and execute a load module.
Input you use consists of your object module, VS FORTRAN library
routines, and any other secondary input (such as TEXT files of
called subprograms).
For example, if you want to load and execute the TEXT files for
MYPROG, and its subprogram SUBPROG, you specify-*
load myprog (start)
Because you've made the TXTLIB available (through the GLOBAL
command), CMS link-edits the TEXT files for MYPROG and SUBPROG
into a load module and then execution begins (because you
specified START in the load command).
If you don't specify the START option in the LOAD command,
execution doesn't begin until you issue a START command*
start myprog
If you don't make the TEXT library available, you must define
secondary input, using the INCLUDE command-
load myprog
include subprog
start myprog
The INCLUDE command tells CMS that SUBPROG is needed as secondary
input during execution of MYPROG.
Creating a Nonreloca table Load Module — GENMOD Command
You can also create a nonrelocatable load module and save it for
future reference, using the LOAD, INCLUDE, and GENMOD commands*
load myprog
include subprog
genmod myproga
This creates a a nonrelocatable load module named MYPROGA on your
CMS disk.
You can now invoke MYPROGA, by entering*
myproga
at the terminal, and your program is executed.
Using VM/370-CMS with VS FORTRAN 97
DEFINING SEQUENTIAL AND DIRECT DATA FILES — CMS
When you execute your program, you must make any files it uses /1| r~v
available for processing, through a FILEDEF command. The FILEDEF J J
command uses a file identifier for each file. ^J"
Before you can process a direct file, you must preformat it.
"05/VS Considerations — Direct Files" tells how to do this.
Specifying a File Identifier — CMS
You must identify every file you use in the following form*
filename filetype [fi lemode]
where the f i lename is the name that identifies the file to the
system; the f i letvpe defines the kind of file this is. The
filetypes you'll most often use are:
DATA for your data files
FORTRAN for all your FORTRAN source programs
The f i lemode is optional, and can be any valid CMS fi lemode; you
need to specify it only when you want to store the file on disk
storage other than your own.
USING THE FILEDEF COMMAND — CMS
The form of the FILEDEF command you use varies, depending on the
type of file you're processing: sequential or direct disk, tape,
or uni t record.
Defining Sequential and Direct Disk Files — CMS /— ^
( >
To define sequential and direct disk files, you specify the ^-^
FILEDEF command as follows:
filedef FTxxFyyy DISK filename filetype Cfi lemode] [options]
You specify the FTxxFyyy field to agree with the FORTRAN
reference numbers in the source program.
For the xx field, see Figure 29 in Part 2 for reference
numbers you should specify.
For the yvy field, specify 001 if you're not using multiple
files, if you're using multiple files, you can specify 001
through 999.
The options are any FILEDEF options valid for disk files.
See the VS FORTRAN Appl i cat i on Programming: System Services
Reference Supplement for additional information.
Defining Tape Files — CMS
To define tape files, you specify the FILEDEF command as follows:
filedef FTxxFyyy TAPn [options]
You specify the FTxxFyyy field to agree with the FORTRAN
reference numbers in the source program:
For the xx field, see Figure 29 in Part 2 for reference
numbers you should specify.
o
98 VS FORTRAN Application Programming: Guide
For the yvv field, specify 001 if you're not using multiple
files, if you're using multiple files, you can specify 001
through 999.
For the n field, you specify any valid tape unit (1 through 4).
The options are any FILEDEF options valid for tape files.
See the VS FORTRAN Application Programming- System Services
Reference Supplement for additional information.
Defining Terminal Files — CMS
To define terminal files, you specify the FILEDEF command as
f ol lows:
filedef FTxxFOOl TERMINAL [options]
You specify the FTxxFOOl field to agree with the FORTRAN
reference numbers in the source program.
For the xx field, see Figure 29 in Part 2 for reference
numbers you should specify.
You always specify 001 for the vvv field.
The options are any FILEDEF options valid for terminal files.
For input terminal files, your program should always notify you
when to enter data; if it doesn't, you may inadvertently cause
long system waits.
See the VS FORTRAN Application Programming! System Services
Reference Supplement for additional information.
c
Defining Unit Record Files — CMS
To define unit record files, you specify the FILEDEF command as
follows*
For Card Reader Files:
filedef FTxxFOOl READER [options]
For Card Punch Files:
filedef FTxxFOOl PUNCH [options]
For Printer Files:
filedef FTxxFOOl PRINTER [options]
You specify the FTxxFOOl field to agree with the FORTRAN
reference numbers in the source program:
For the xx field, see Figure 29 in Part 2 for reference
numbers you should specify.
You always specify 001 for the vvv field.
The options are any FILEDEF options valid for the type of unit
record file you're processing.
See the VS FORTRAN Application Programming: System Services
Reference Supplement for additional information.
DEFINING VSAM SEQUENTIAL AND DIRECT FILES— CMS
VS FORTRAN allows you to process VSAM sequential files (using
ESDS data sets) and VSAM direct files (using RRDS data sets).
Using VM/370-CMS with VS FORTRAN 99
To define and use such VSAM files under CMS, you must first
define the file to CMS, then you define a catalog entry for the
file. When you want to access the file (to write or read it), you
must use job control commands.
Defining a VSAM File to ens
To define a VSAM file to CMS, you must specify the following
commands in the following order:
The DLBL command to define the VSAM cluster.
The EDIT command, to create a file containing the DEFINE
CLUSTER command you'll use to create the catalog entry for
your file.
The AMSERV command, to execute the DEFINE CLUSTER command,
in the file you've created; this creates the VSAM catalog
entry.
Using the DLBL Command — CMS
You must execute the DLBL command to name the VSAM cluster and to
define the VSAM files you'll use for program input/output. For
example, to identify the FILE name used in your DEFINE CLUSTER
command, you specify:
dlbl myfile data DSN mastcat (vsam
which identifies MYFILE to the system as a VSAM file named MYFILE
contained in the catalog MASTCAT.
Creating a VSAM DEFINE Command — CMS EDIT Command
To create a catalog entry, you must issue the EDIT command, ■( J
giving the name of the entry; the filetype is AMSERV: ^-^
edit catfile amserv
This puts you in edit mode, and you can then enter the Access
Method Services DEFINE CLUSTER command as data into the file; for
example:
DEFINE CLUSTER (NAME(MASTCAT)
FILE(MYFILE)
V0LUMEU23456)
NONINDEXED
RECORDS(20)
which defines a catalog entry in MASTCAT, for a VSAM sequential
file (NONINDEXED) named MYFILE, on volume 123456, with 20 tracks
of space allocated.
Making the Catalog Entry — AMSERV command
Once you've entered the DEFINE CLUSTER command in an AMSERV file,
you can request Access Method Services to process the command for
you, using the AMSERV command:
amserv catfile
This command sends the DEFINE CLUSTER command to Access Method
Services for processing, and entry into MASTCAT.
See the VS FORTRAN Application Programming: System Services
Reference Supplement for additional information.
o
100 VS FORTRAN Application Programming: Guide
Creating and Processing VSAM Files — CMS
When you execute a FORTRAN program to create or process a VSAM
file, you define the file in a DLBL command* For example, to
process MYFILE in a FORTRAN program called MYPROG, you specify:
dlbl myfile data DSN mastcat (vsam
start myprog text
When MYPROG is executed, the DLBL statement makes MYFILE
available to the program.
Using VM/370-CMS with VS FORTRAN 101
USING 0S/VS2-TS0 WITH VS FORTRAN
O 7 "
You can use the facilities of 0S/VS2-TS0, taking advantage of
quick terminal turnaround time, to develop VS FORTRAN programs.
You can compile your programs under 0S/VS2-TS0 and link-edit
them to run under MVS, or you can compile, link-edit, and execute
them under 05/VS2-TSO.
USING THE TSO COMMANDS
The TSO commands help you create and edit your source programs,
link-edit your object modules, and execute your load modules.
The TSO commands you'll use most frequently are shown in
Figure 25. Reference documentation for these commands is given
i n the VS FORTRAN Application Programming* System Services
Reference Supplement .
USING YOUR TERMINAL UITH TSO
You must log on your terminal, using the procedures your
organization has set up.
You can then use all of the TSO commands to develop, test, and
run your VS FORTRAN programs.
When you finish a terminal session, you log off in the usual way.
See the 0S/VS2 TSO Terminal User's Guide for documentation on
terminal usage.
CREATING YOUR SOURCE PROGRAM — TSO EDIT COMMAND
n^-^"
To create a source program file, you use the EDIT command. Use
the EDIT command whenever you want to create a new file and also
whenever you want to edit an existing one.
(You can also use the Structured Programming Facility (SPF)
editor to create source program files. You can use SPF to
allocate sequential files or partitioned data sets, although
this isn't necessary, since the ALLOCATE and ATTRIB commands are
also avai lable. )
The EDIT subcommands (such as COPY, INPUT, INSERT, etc.) help you
enter and edit the lines of source code.
To create a source program file, you can specify the descriptive
qualifier of your source program file as FORT. Alternatively,
you can specify the descriptive qualifier as DATA.
For example, to create a source program file named MYPROG, you
speci fy*
edit myprog.fort
or
edit myprog.data
This creates an empty data set for you, with the name MYPROG, and
the descriptive qualifier FORTRAN or DATA. (If MYPROG.FORT
already exi sts, the EDIT command retrieves it for you and makes
it available for editing.)
c
J?
102 VS FORTRAN Application Programming: Guide
■o
TSO Command
ALLOCATE
ATTRIB
CALL
DELETE '
EDIT
FREE
HELP
LINK
LOADGO
STATUS
SUBMIT
TEST
Figure 25
Usage
Allocates data sets needed for compilation,
link-editing, or execution.
Builds a list of data sets you intend
to allocate dynamically.
Invokes compiler, linkage-editor, or load
module for execution.
Deletes one or more data set entries or one
or more members of a partitioned data set.
Puts you in EDIT mode to create and edit
source program and data files, and lets you
use the following EDIT subcommands*
COPY Copies records within the data set you
are editing.
END Ends edit mode with or without saving
the data set.
HELP Gives information about EDIT subcommands
INPUT Enters INPUT mode and accepts lines as
part of the data set you're creating
or editing.
INSERT Inserts one or more lines of data into
the data set that you're creating or
editing.
LIST Displays one or more lines of your data
set at the terminal.
HOVE Move one or more records in your data
set to another position in the same
data set.
SAVE Ends EDIT mode and places the current
data set on disk storage.
Deallocates files allocated for a job.
Gives information about commands other
than EDIT subcommands.
Converts one or more object modules into
a load module.
Loads one or more object modules into
storage and executes them.
Checks execution status of a submitted
batch job.
Submits a JCL file to MVS to run as a
batch (background) job (requires SUBMIT
logon capabilities).
Tests an object program for proper
execution and locates programming errors.
0S/VS2-TSO Commands Often Used with VS FORTRAN
^r%
"^y
Using 0S/VS2-TS0 with VS FORTRAN
103
You can now enter your source program into the file* line by
line* according to the rules for fixed or free form source
programs.
Fixed format FORTRAN files contain 80-character records; you use
the first 72 characters for FORTRAN statements and continuation
lines.
r
IBM EXTENSION
T
If you 1 re using free form input* you can enter your source
program into the file, line by line, according to the rules for
free format source programs.
The maximum line length you can enter is 80 characters;
however, your source statements (excluding statement numbers
and statement break characters) can be up to 1320 characters
long.
This is particularly handy when you're using a terminal — you
don't have to pay attention to card image restrictions.
END OF IBM EXTENSION
(Reference documentation for fixed-form and free-form source
program input is given in the VS FORTRAN Application
Programming' Language Reference manual.)
COMPILING YOUR PROGRAM — TSO ALLOCATE AND CALL COMMANDS
To compile your program, use the ALLOCATE and CALL commands.
Allocating Compilation Data Sets — TSO ALLOCATE Command
First, you allocate the data sets you'll need for compilation as
shown in Figure 26.
~%^/'
allocate dataset(myprog.f ort) file(sysin) old
READY
allocate dataset(myprog. li st) f i le(syspri nt) new block(120) space(60,10)
READY
allocate dataset(myprog.obj ) file(syslin) new block(80) spacedOO, 10)
READY
allocate dataset(*) f i le(systerm) •
READY
Figure 26. Allocating TSO Compilation Data Sets
For any compilation, you must allocate the SYSIN AND SYSPRINT
data sets.
Allocate the SYSLIN data set only if you wish to produce an
object module (you've specified the OBJECT compiler option).
Allocate the SYSTERM data set only i f you wish to receive
diagnostics at the terminal (you've specified the TERMINAL
option).
You can enter these ALLOCATE commands in any order. However, you
must enter all of them before you invoke the FORTRAN compiler.
Requesting Compilation — CALL Command
Once you've allocated the data sets you'll need, you can issue a
CALL command, requesting compilation.
O'
104 VS FORTRAN Application Programming: Guide
You can request compilation* using the default compiler options:
call 'sysl . linkli b(vsf ort) *
or you can request one or more compiler options explicitly:
call ' sysl . linklib(vsfort) * 'f ree, term,source»map* li st >object f
which tells the compiler that:
FREE — your source program is in free form.
TERM — diagnostic messages arQ to be directed to your
termi nal .
SOURCE — the source program i s to be printed in the output
li sting.
MAP — a storage map is to be printed in the output listing.
LIST — the object program i s to be printed in the output
li sting.
OBJECT — an object module is to be produced.
eference documentation for the CALL command is given in the VS
ORTRAN Application Programming: System Services Reference
Supplement .
COMPILER OUTPUT — TSO
o
Depending on your organization's compi le-time defaults and/or
the options you select in your CALL command* you may get a LIST
file and/or an OBJ file as output* placed in your disk storage
for easy reference* under the name(s) you specified in the
ALLOCATE command.
The list File — TSO
The obj File — TSO
The LIST file contains the compiler output listing; see "Fixing
Compi le-Time Errors — Advanced Programming" in Part 2 for an
explanation of what the compiler output listing contains and how
to use it.
It has the name of your source program* and the qualifier LIST.
For example* the qualified name for MYPROG is MYPROG.LIST.
The OBJ file contains the object code the compiler created from
your source program. The OBJ file contents are explained in
"Link-Editing Your Program — Advanced Programming" in Part 2.
It is placed in your storage with the name of your source program
and the qualifier OBJ. For example* the qualified name for MYPROG
is MYPROG. OBJ.
This file remains in your disk storage until you erase it* using
the DELETE command.
You can link-edit the OBJ file under any of the systems that VS
FORTRAN supports to get a load module.
LINK-EDITING AND EXECUTING YOUR PROGRAM UNDER TSO
To link-edit and execute your program under TSO, use the LINK
command to create a load module from one or more object modules
(plus any needed VS FORTRAN library modules)* and then use the
CALL command to execute the load module.
Using 0S/VS2-TS0 with VS FORTRAN
105
The input object module must be OBJ files, for example:
user id. name. OB J
LINK-EDITING YOUR PROGRAM— TSO LINK COMMAND
You use the LINK command to create and execute a load module.
Input you use consists of your object module, VS FORTRAN library
routines, and any other secondary input (such as OBJ files of
called subprograms).
For example, if you want to load and execute the OBJ files for
MYPROG, and its subprogram SUBPROG, you specify:
link (myprog, subprog) load(myprog) lib( f vfortlib* )
When the commands are executed, the OBJ files for MYPROG and
wuui Kwu are i*nK ecs'tecs together :ntc a less mccuie, and then
execution begins.
You must request the linkage editor to search the library to
resolve external references. In the last example, you are
therefore requesting a search of SYS1 . FORTLIB .
A
Linkage Editor Listings — TSO LINK command
You can also use the LINK command to specify linkage editor
options. In the last example, you can request the listings to be
printed, either on the system printer or at your terminal:
On the System Printer:
link (myprog, subprog) lib( ' vfortli b T ) load(myprog) print
The qualified name of the file to be sent to the system printer
is MYPROG. LINKLIST. To print the file, you must use a PRINT
command, or the SPF HARDCOPY command.
At Your Terminal:
link (myprog, subprog) 1 ib( f vfortl i b' ) load(myprog) print(*)
When you specify PRINK*), the linkage editor listings are
displayed at your terminal.
EXECUTING YOUR PROGRAM — TSO
To execute your program, use the CALL command.
USING THE CALL COMMAND— TSO LOAD MODULE EXECUTION
For example, to execute MYPROG. LOAD, you specify the ALLOCATE
commands needed to allocate the input and output data sets it
uses, as well as any work data sets.
Then you issue the CALL command, as follows:
file(F05FT001)
(as needed)
allocate dataset(myprog. indata)
READY
allocate dataset(myprog.outdata) f i le(F06FT001) (as needed)
READY
allocate dataset(myprog.workf i 1) f i le(FlOFTOOl) (as needed)
READY
call myprog
and program TEMPNAME from file MYPROG. LOAD is executed.
Once program execution is complete, and if you no longer need
them, you should issue the DELETE command to free the disk space
^W
106 VS FORTRAN Appli cation Programming: Guide
C" \
used by the data sets you've named in the ALLOCATE commands and
in the CALL command*
delete (myprog. indata myprog. outdata myprog. workf i 1)
READY
If you do need them, don't issue the DELETE command; you can then
reuse the data sets as necessary.
Using the Loader* — TSO LOADGO Command
f\.
Using the LOADGO command, you can invoke the loader program to
link-edit and execute your program all in one step. This is
efficient when you have several object modules you want combined
into one load module for a quick test. When you use the LOADGO
command, the load module created is automatically deleted when
program execution ends.
First, you must allocate any needed data sets, as outlined under
"Allocating Compilation Data Sets — TSO ALLOCATE Command."
Then you issue the LOADGO command. In this example, you're
linking and executing the MYPROG object module?
loadgo (myprog) lib( ' vf ortli b' )
The VFORTLIB operand makes the SYS1.F0RTLIB data set available
to the loader program. The loader program can then resolve any
external references in MYPROG, and load the needed object
modules.
You can also use the LOADGO command to execute a link-edited load
module, for example, one named MYPROG**
loadgo myprog tempname
You can also use the LOADGO command to specify loader options. In
the last example, you can request a load module map and the
listings to be printed, either on the system printer or at your
termi nal '
On the Printer File:
loadgo (myprog) map print
The qualified name of the file sent to the system printer is
MYPROG. LOADLIST.
At Your Terminal:
loadgo (myprog) map print(K)
When you specify PRINT(*), the loader listings are displayed at
your termi nal .
FIXING EXECUTION ERRORS UNDER TSO
When you're developing programs using TSO, you can make use of
all the FORTRAN debugging aids described in "Fixing
Execution-Time Errors — Advanced Programming."
You can't use the TEST command to debug your source programs.
However, you can use the TSO TEST command, together with its
associated subcommands, to debug your object program.
The easiest way to use TEST i s to establish the point in your
program where an abnormal termination occurred.
For best results, you should be familiar with the basic assembler
language and addressing conventions.
Using 0S/VS2-TS0 with VS FORTRAN 107
Reference documentation on using the TEST command is given in the
VS FORTRAN Application Programming' System Services Reference „ I
Supplement . q \ r
REQUESTING COMMAND PROCEDURE PROCESSING UNDER TSO
You can create a command procedure (CLIST) for a number of
different processing options under TSO. This is useful, because
you can preallocate all the options you need once, when you
create the command procedure. Then, every time you execute the
command procedure, there's no need to respecify the options.
You can create command procedures to process your jobs either in
the foreground or in the background.
COMMAND PROCEDURES FOR FOREGROUND PROCESSING
To create a command procedure to link-edit and run a FORTRAN
program in the foreground, do the following*
1. Edit a file named LINK. MYPROG. CLIST, which contains*
LINK MYPROG LIB( » VFORTLIB 1 ) LOAD(MYPROG(MYNAME) TEST
LIST LET XREF PRINT(MYPROG)
These options will allow you to use the TEST command (TEST),
list the link-edit control statements (LIST), allow the
procedure to complete execution even if there are errors
(LET), produce a cross-reference table (XREF), and produce a
linkage-editor listing on the MYPROG. LIST data set (PRINT).
2. Use the SAVE subcommand to save the command procedure.
3. To execute the link and run command procedure, enter* .-.^
ex link.myprog V.> y
and press ENTER.
This tells TSO to create a load module, MYNAME, in file
userid. MYPROG. LOAD
To run a prevously link-edited program, do the following*
1. Edit a file name RUN. MYPROG. CLIST which contains*
s
ALLOC FILE(FTxxFyyy) (work and data files
as needed)
CALL MYPROG(MYNAME)
2. Use the SAVE subcommand to save the command procedure.
3. Use the END subcommand to exit from the EDIT command.
4. To execute the run command procedure, enter*
ex run.myprog
and press ENTER.
This tells TSO to execute MYNAME in file userid. MYPROG. LOAD
in the foreground.
COMMAND PROCEDURES FOR BACKGROUND EXECUTION
If your source programs are small, foreground execution can be
quite convenient. However, if your programs will take some time
to compile and/or to execute, you may prefer to batch process
6
108 VS FORTRAN Application Programming* Guide
c
them in the background. This frees your terminal for other work
while the batch job is running.
To create a command procedure for background compilation, do the
followi ng:
1. Edit a file named COMPILE. MYPROG. CNTL, placing in it the
following job control statements*
//userid JOB (acct. informati on) , f yourname* , other information
//COMPILE EXEC VSFORTC
//VSFORT.SYSIN DD DSN=useri d.MYPROG. FORT, DISP=SHR
2. Use the SAVE subcommand to save the command procedure.
3. To execute the run command procedure, enter J
submit compi le.myprog
and press ENTER.
This tells TSO to compile MYPROG in file useri d .MYPROG. FORT
in the background.
To create a command procedure for background compilation,
link-editing, and execution, do the following'
1. Edit a file named RUN. MYPROG. CNTL , placing in it the
following job control statements*
//userid JOB (acct. informati on) , 'yourname' , other information
//RUN EXEC FORTCLG
//GO.FTnnFxxx DD DSN=useri d.MYPROG. FORT,
DISP=SHR
/x
//GO.FTxxFyyy DD DSN=useri d.MYPROG. DATA,
DISP=SHR (other files as needed)
2. Use the SAVE subcommand to save the command procedure.
3. Use the END subcommand to exit from the EDIT command.
4. To execute the compi le-1 ink-execute command procedure,
enter*
submit run.myprog
and press ENTER.
This tells TSO to compile, link-edit, and execute MYPROG in
file useri d .MYPROG. FORT in the background.
TSO FILE NAMING CONVENTIONS
When you're creating or processing files under TSO, you must use
the TSO naming conventions, as follows*
[ i denti fi cat ion. Iname.qualif i er
[identification.!
is the identification you supply in your LOGON command, or
that you assign with the PROFILE command.
If you omit the identification, your LOGON identification
i s assumed.
name.
is the name you give the file.
qualifier
identifies the contents of the file. Qualifiers useful for
FORTRAN are:
Using 0S/VS2-TS0 with VS FORTRAN 109
Qualifier Has File Contents
CLIST TSO commands and subcommands
DATA Data files you're creating or processing
FORT FORTRAN source programs — in either fixed or free
form
LIST FORTRAN compiler output listings
LOAD FORTRAN load modules
LOADLIST Loader output listings
OBJ FORTRAN object modules
If the file you're referring to is a sequential or direct file*
you can use the name and the qualifier alone to identify the data
set. For example*-
myfi lei. data
If the file you're referring to i s a member of a partitioned data
set* you can add the membei — name in parentheses after the
qualifier. For example, to refer to member-name C0MM0N1 in data
set INCLIB1, you specify*
incl i bl .data (common 1)
FILE IDENTIFICATION — TSO ALLOCATE COMMAND
Before compiling* link-editing, or executing your program, you
must allocate the data sets you'll need, using the ALLOCATE
command. For example, you could allocate the following files ^A
when processing a source program named MYPROG* uy.
For the Source Program as compiler Input:
allocate datasetCmyprog.f ort) file(sysin) old
This ALLOCATE command tells TSO that the file named MYPROG. FORT
is an existing file (OLD), available on the SY5IN data set.
For Compiler Output Listings:
allocate dataset(myprog. li st) f i le(sy«pri nt) new
block(120) space(60,10)
This ALLOCATE command tells TSO that the file named MYPROG. LIST
is a new file (NEW), to be produced on the SYSPRINT data set. The
line length is 120 characters; the primary space allocation is 60
lines.
To print the listing, use the PRINT command.
For an Object Deck:
allocate dataset(myprog.obj ) f i le(syspunch) new
block(80) space (120,20)
This ALLOCATE command tells TSO that the file named MYPROG. OBJ is
a new file (NEW), to be produced on the SYSPUNCH data set. The
record length is 80 characters.
For the Object Module:
allocate dataset(myprog.obj ) file(syslin) -
new block(80) spacedOQ, 10)
This ALLOCATE command tells TSO that the file named MYPROG. OBJ is
a new file (NEW), to be produced on the SYSLIN data set. The
110 VS FORTRAN Application Programming* Guide
record size (and block size) must be 80 characters. The space you
can specify as any size you need.
For Terminal Input/Output:
allocate dataset(*) f i le(systerm)
This ALLOCATE command tells TSO that the file identified by the
asterisk (*) is available on the SYSTERM data set. You can then
use the terminal to receive error mesage output.
(The listing output is on the SYSPRINT data set.)
For Program Data Sets:
allocate dataset( i dent i fi er .name. data) f i le( FnnFTxxx)
This ALLOCATE command tells TSO that the file identified by the
qualified name is available on the FnnFTxxx data set. Valid
values for nn and xxx &re documented in Figure 29.
Reference documentation for the ALLOCATE command is given in the
VS FORTRAN Application Programming? System Services Reference
Supplement . For valid values for FnnFTxxx* see "Defining
Files — OS/VS DD Statement" in Part 2.
Before you can load a direct file, you must preformat it. "OS/VS
Considerations — Direct Files" tells how to do this.
DEFINING VSAM SEQUENTIAL AND DIRECT FILES — TSO
c
VS FORTRAN allows you to process VSAM sequential files (ESD5 data
sets) and VSAM direct files (RRDS data sets).
To define and use VSAM files under TSO, you can enter and execute
the Access Method Services commands (such as DEFINE CLUSTER)
directly from your terminal. See your system administrator for
further information about catalogs and volumes.
When you want to access the file (to write or read it), you must
use the ALLOCATE command, if you're referencing the VSAM file
using FnnFTyyy. If you aren't, you don't need an ALLOCATE
command, because you are accessing the file directly.
SYSTEM CONSIDERATIONS UNDER OS/VS2-TSO
When you're developing programs using the TSO facilities, your
FORTRAN programs must not require system actions for which you
are not authorized (for example, protected data set access or
volume mounting).
In addition, if your FORTRAN programs make use of assembler
subroutines, there are a few system considerations you must take
into account, when coding the assemler routines, as follows 1
1. Your assembler subprograms must execute as nonauthori zed
problem programs.
2. Your assembler subprograms must use standard MVS system
service interfaces.
3. Your assembler subprogram must not use TSO-specific storage
subpools.
4. The address spaces your assembler subprograms use must not
be sensitive to MVS control block structures.
5. Your assembler subprogram must use only the data set
characteristics available through the ALLOCATE command.
Using 0S/VS2-TS0 with VS FORTRAN 111
FIXING COMPILE-TIME ERRORS—ADVANCED PROGRAMMING
)
VS FORTRAN gives you a good deal of assistance in finding and
correcting errors it detects during compilation. The compiler
output listing gives you much useful information to aid you in
debuggi ng.
In addition, if you're creating programs that must conform to
1978 Standard FORTRAN rules, you can use the Standard Language
Flagger to tell you when you've used program elements that don't
conform.
USING THE COMPILER OUTPUT LISTING
The compiler output listing is designed to help you pinpoint any
errors you've made in your source program. The listing is
described in the following sections, together with hints on how
to use it.
COMPILATION IDENTIFICATION
This portion of the listing helps you identify each run you make,
even separate runs on the same day.
The heading on each page of the output listing gives the name of
the compiler and its release level, the name of the source
program, and the date and time of the run in the format 5
DATE' month day, year TIME* hour .mi nute. second
That is, for example 2
DATE: MAY 1, 1981 TIME: 14.31.01
The TIME given is the time the job was completed. The TIME is
shown on a 24-hour clock; that is, 14.31.01 is the equivalent of
2.31.01 PM.
The first page of the listing also shows the compiler options
(default and explicit) in effect for this compilation.
Note: Your organization may show the date as:
year month day
instead of the format shown above.
SOURCE PROGRAM LISTING— SOURCE OPTION
Use the source listing for desk checking to make sure that your
source statements conform to VS FORTRAN syntax. The internal
sequence numbers (which the compiler provides for you) help you
identify the statements causing diagnostic messages.
The statements printed in the source program listing are
identical to the FORTRAN statements you submitted in the source
program, except for the addition of internal sequence numbers
(ISN) as a prefix. Figure 27 shows an example of the source
program 1 i sti ng.
Note: When this program is executed, the diagnostic messages
shown in Figure 28 are produced.
112 VS FORTRAN Application Programming: Guide
c
REQUESTED OPTIONS (EXECUTE): MAP
REQUESTED OPTIONS (PROCESS): LIST XREF MAP
OPTIONS IN EFFECT: LIST MAP XREF NOGOSTMT NODECK SOURCE TERM OBJECT FIXED TRACE
OPTIMIZE(O) LANGLVL(77) NOFIPS FLAG(I) NAME(MAIN ) LINECOUHT(60)
X *...l 2 3 4 5 6 7.x 8
C SAMPLE PROGRAM TO DEMONSTRATE THE NEW VS FORTRAN
ISN 1 REAL*8 PI
ISN 2 PARAMETER (PI = . 314159265D1)
ISN 3 C0MPLEXX8 C8V, C8A, C8B
ISN 4 COMPLEXK32 C32
ISN 5 LOGICAL*l LI
ISN 6 REAL*8 R8A, R8V, R8VNU
ISN 7 CHARACTERX14 CHAR14
ISN 8 EQUIVALENCE (R4A(4), R8A(2), C32(l,l))
ISN 9 EQUIVALENCE (12(3), LI)
ISN 10 DIMENSION R8A(7), C32(4,5), R4AU1), 12(3)
ISN 11 COMMON /COM1/ R4A, C8A
ISN 12 COMMON /C0M2/ LI, C8B
ISN 13 111 FORMATCIOUTPUT FOR ', A14, 14F10.7, E15.7, 2(F20.16))
ISN 14 DATA A2/3. 14159/
ISN 15 DATA CHAR14/'SHARE PROGRAM '/
ISN 16 ASSIGN 111 TO J
ISN 17 Al = (A2 + R8A(2))*3
ISN 18 IF (Al .EQ. 0) GOTO 200
ISN 19 IF (A2 .EQ. 0) GOTO 200
ISN 20 DO 100 I = 1,7
ISN 21 IF (LI)
1 R8V = R8V + R8A(I) + (.0007, .0021) + FLOAT(I)
ISN 23 100 CONTINUE
ISN 24 CALL CXSUB(*300 > R8V , Al ,PI )
ISN 25 R8A = 1.0002 + R8A(1)
ISN 26 200 WRITE(6,J) CHAR14, R8A, Al, C32
ISN 27 DATA C8V/(2. 540005, 2.781828)/
ISN 28 300 PAUSE 'THE END'
ISN 29 END
Figure 27. Source Program Listing Example — SOURCE Option
DIAGNOSTIC MESSAGE LISTING— FLAG OPTION
If the level of the message is greater than or equal to that
you've specified in the FLAG option and there are syntax errors
in your VS FORTRAN source program, the compiler detects them and
gives you a message. The messages are self explanatory, making it
easy to correct your syntax errors before recompiling your
program.
Examples of VS FORTRAN messages are shown in Figure 28.
Fixing Compile-Time Errors- — Advanced Programming 113
*x* VS FORTRAN ERROR MESSAGES ***
IFX1027I RPLC 12(S)
IFX2323I
IFX2323I
IFX2332I
IFX2323I
COMN
COMN
COMN
COMN
4(W)
<KW)
12(S)
4(W)
27 NON-SUBSCRIPTED ARRAY NAME APPEARS AS LEFT-OR-EQUAL
SIGN VARIABLE. SPECIFY A SUBSCRIPTED ARRAY NAME
OR A VARIABLE NAME.
VARIABLE "R8A" IN COMMON "COM1" IS INEFFICIENTLY
ALIGNED. VARIABLES SHOULD BE ALIGNED ON
APPROPRIATE BYTE BOUNDARIES.
VARIABLE "C32" IN COMMON "COM1" IS INEFFICIENTLY
ALIGNED. VARIABLES SHOULD BE ALIGNED ON
APPROPRIATE BYTE BOUNDARIES.
THE VARIABLE "LI" WILL CAUSE COMMON "COM2" TO EXTEND
TO THE LEFT BECAUSE OF ITS POSITION IN EQUIVALENCE
STATEMENT AT ISN "9". CHECK VARIABLE PLACEMENT.
VARIABLE "C8B" IN COMMON "COM2" IS INEFFICIENTLY
ALIGNED. VARIABLES SHOULD BE ALIGNED ON
APPROPRIATE BYTE BOUNDARIES.
Figure 28. Examples of Compile-Time Messages — FLAG Option
Messages you'll get are all in the following format*
IFXnnnnI mmmm level Cisn] 'message text'
where each one of the areas has the following meanings
IFX The message prefix identifying all VS FORTRAN compiler
messages
nnnnl The unique number identifying this message
mrturm The identifier for the compiler module issuing the
message
level The severity level of the error diagnosed. Compiler
diagnostic messages are assigned severity levels as
follows 1
0(1) Indicates an informational message; messages at
the I level merely give you information about the
source program and how it was compiled.
The severity code is (zero).
4(W) Is a warning message; it usually tells you that a
minor error, which does not violate the VS FORTRAN
syntax* was detected.
The severity code is 4.
If no messages produced exceed this level, you can
link-edit and execute the compiled object module.
8(E) Is an error message; usually, a VS FORTRAN syntax
error was detected. The compiler makes a
corrective assumption, and completes the
compi lat i on.
The severity code is 8.
It's possible that the program will execute
correctly.
V^y 1
114 VS FORTRAN Application Programming: Guide
, 12(S) Is a serious error message; an error uas detected
* which violates VS FORTRAN syntax, and for which
* r the compiler could make no corrective assumption.
The severity code is 12.
You shouldn't attempt execution, except possibly
for debugging purposes.
16(U) Is an abnormal termination message; an error was
detected which stopped the compilation before it
could be completed.
The severity code is 16.
Cisnl gives the internal sequence number of the statement in
which the error occurred, if the internal sequence
number can be determined.
'message-text* explains the source program error that was
detected.
OS/VS Cataloged Procedures and Compiler Message Codes
Unless you increase the permissible condition code in the COND
parameter of the compilation EXEC statement, severity levels
higher than level 4 prevent link-edit processing.
DOS/VSE Message code Considerations
j^%
Severity levels higher than level 4 prevent link-edit
processing.
USING THE MAP AND XREF OPTIONS
The MAP and XREF compiler options, described in the following
sections, are a big aid in debugging your programs — both for
fixing compile-time errors and also for fixing execution-time
errors. You can use them to cross check for the fallowing common
source program problems'
• Are all variables defined as you expected?
• Are variables misspelled?
If you've declared all variables, then the following are
suspect*
1. Unreferenced variables
2. Variables referenced in only one place
• Are all referenced variables set before they're used?
(Except for variables in COMMON, parameters, initialized
variables, etc . )
• Are one or more variables unexpectedly equivalenced with
some other variable?
• Are there unreferenced labels? (If there are, you may at some
point have mi skeyed a label.)
-• Have you accidentally redefined one of the standard library
functions? (For example, through a statement function
def i ni ti on . )
• Are the types and lengths of arguments correct across
subroutine calls? (You'll need both listings for this.)
Fixing Compile-Time Errors — Advanced Programming 115
• For a variable passed to the main entry of a subroutine* have
you inadvertently altered it at a subordinate entry point?
These questions and more about your source program syntax and
logic can be answered through the information supplied you by the
Source Program Map and the Cross Reference Dictionary.
SOURCE PROGRAM MAP — MAP OPTION
If you've specified the MAP option* the storage map shows you how
you've used each item you've defined in your program; this can
help you figure out obscure syntax or logic errors that aren't
immediately apparent from the source listing.
A storage map shows the use made of each variable* statement
function* subprogram* or intrinsic function within a program. An
example of a storaqe map is aiven in Figure 29,
STORAGE MAP
TAG: SET(S), REF'D(F), USED AS ARG (A) , COMN(C), EQUV(E), STMT. FUNCT. (T) , SUBPROG(X), NAMED CONSTANT (K) , INITIAL VALUE (I)
PROGRAM NAME: MAIN . SIZE OF PROGRAM: 350 HEX BYTES.
NAME MODE
NAME MODE
TAG
A1
R*4
SFA
000140
A2
R*4
FI
000144
CHART*
CHAR
FI
000148
CXSUB
FX
000000
C32
C*32
FCE
OOOOOC
C8A
C*8
C
UNREFD
C8B
C*8
C
UNREFD
C8V
C*8
I
UNREFD
FLOAT
R*4
X
UNREFD
I
1*4
FA
000138
12
1*4
CE
UNREFD
J
1*4
F
00013C
L1
L*1
FCE
000000
PI
R*8
FK
000054
R4A
R*4
CE
UNREFD
R8A
R*8
FCE
000004
R8V
R*8
SFA
000130
R8VNU
R+8
UNREFD
VSCOM#
FX
000000
VSERH#
FX
000000
COMMON INFORMATION
NAME: COM1. SIZE: 28C HEX BYTES.
-NAME- MODE DISPL^ _NAME_
R8A(E) R*8 000004 C32 (E)
NAME: COM2. SIZE: 9 HEX BYTES.
-NAME- ■ "2°.?. 21§?t:. -NAME-
12(E) 1*4 FFFFF8 L1 (E)
(E) - EQUIVALENCED
MODE
DISPL;_
NAME
MODE
DISPL._
C*32
OOOOOC
R4A(E)
R*4
000000
(E) -
EQUIVALENCED
MODE
DISPL^
NAME
MODE
DISPL^
L*1
000000
C8B
C*8
000001
_NAME_ MODE DISPL^
C8A C*8 00002C
MODE DISPL.
w
LABEL INFORMATION.
LABEL DEFINED
100
01 000 00001
01 000 00025
(NN NNN NNNNN IS A GENERATED LABEL)
ADDR. LABEL DEFINED ADDR.
23 000292
1 0001CC
25 0002C4
1 11
01 000 00019
26 001 00020
13 000030
19 0001FE
20 000214
200
01 000 00020
02 002 00020
26 0002CE
20 00020C
23 0002A8
300
01 000 00022
28 000312
22 000228
Figure 29. Example of a Storage Map — MAP Option
The following paragraphs describe each area of a storage map*
such as that shown in Figure 29.
The first line of a storage map gives the name and size of the
source program* the size is given in hexadecimal format.
name column
MODE column
The first column is headed NAME. It shows the name of each
variable* statement function, subprogram* or implicit function
in the program.
The second column is headed MODE — it gives the type and (except
for character items) length of each name* in the format '
€
116 VS FORTRAN Application Programming: Guide
type*length
where the type can be?
C for complex
CHAR for character (length not displayed)
I for integer
L for logical
R for real or double precision
TAG column
c
The third column is headed TAG. It displays use codes for each
name and variable. The use codes are:
A for a variable used as an actual argument in a parameter
list
C for a variable in a COMMON block
E for a variable in an equivalenced block
F for a variable whose value was referred to during some
operation
I for a variable specified with an initial value
K for a constant
S for a variable whose value was set during some operation
T for a statement function
X for an external function
Address Column
The fourth column is headed ADDR — it gives the relative address
assigned to a name. (External functions* statement functions,
and COMMON block references have a relative address of 00000.)
For unreferenced variables* this column contains the letters
UNREFD instead of a relative address.
COMMON Block Maps— MAP Option
If your source program contains COMMON statements, you'll also
get a storage map for each COMMON block.
The map for a COMMON block contains much the same kind of
information as for the main program. The DISPL column shows the
displacement from the beginning of the COMMON block.
Any equivalenced COMMON variable is listed with its name
followed by (E); its displacement (offset) from the beginning of
the block is also given.
Fixing Compi le-Time Errors — Advanced Programming
117
Statement Label Map — MAP Option
The MAP option also gives you a statement label map* a table of
statement numbers used in the program. The label map shows the
following forms of statement numbers:
• Source statement labels — as entered
• Compiler-generated statement labels, in the form'
aa bbb ccccc
where
aa
is the identification code that indicates which
compiler module caused the label to be generated. The
codes are shown in Figure 30.
bbb
is the sequence number within internal sequence number
(ISN) ccccc, starting with 000.
CCCCC
is the ISN of the statement at which the label is
generated.
• FORMAT statement labels — as entered
It also gives you the internal sequence number (ISN) for the
statement in which the label is defined and the address assigned
to the label.
Code
Module
01
IFX1CNTL
02
IFX1D0D0 IFX1END0
03
IFX1L0GL
04
IFX1IFTH
05
IFX1ELSF
06
IFX1ELSE
07
IFX1PRNS
08
IFX1IMPD
0B
IFX1RELS
OC
IFX1IOST
0D
IFX1I0MN
21
IFX1F0RM
vy
Figure 30. Module Identification Codes
SOURCE PROGRAM CROSS-REFERENCE DICTIONARY — XREF OPTION
If you've specified the XREF option, the cross-reference
dictionary shows you where in your program you used each item you
defined. This gives you a record of what interactions between
items you can expect; it also shows up conflicting usages of
items.
o
118 VS FORTRAN Application Programming* Guide
c
During the later debugging stages, when you're debugging
execution errors, it can also be of great assistance in detecting
logic errors.
Figure 31 shows an example of a cross reference listing.
A cross-reference dictionary shows the names and statement
labels in the source program, together with the internal
statement numbers in which they appear.
Data Item Dictionary — XREF Option
C
The first line of the data item cross-reference dictionary
defines the codes used in the TAG column.
From left to right, the subsequent columns give you the following
i nf ormati on :
NAME COLUMN^ Names are listed in alphabetic order.
MODE COLUMN** Each name is followed in the second column, the
column headed MODE, by its type, in the same format as for the
MAP option.
TAG COLUMN: The type for each name is followed in the third
column, the column headed TAG, by its status, which can be*
A an array
C an item in COMMON
D a dummy argument
E an equivalenced item
F a statement function
I an intrinsic function
K a named constant
T an item defined in an explicit type statement
X an external function
DECLARED COLUMN'- The DECLARED column gives the internal sequence
number where the data item is defined.
REFERENCES COLUMN: The REFERENCES column gives the internal
sequence number of each statement in the source program where the
data item is referred to.
If there are no references within the program, this column
contains UNREFERENCED.
Statement Label Dictionary — XREF Option
O
In the statement label dictionary, the following columns are
defined:
LABEL COLUMN: Statement labels, including compiler-generated
labels, are listed in ascending order.
TAG COLUMN: The LABEL column is followed in the second column,
the column headed TAG, by its status, which can be:
A used as an argument
B an object of a branch
F label for a FORMAT statement
Fixing' Compi le-Time Errors — Advanced Programming 119
CROSS REFERENCE DICTIONARY
TAG: ARRAY(A). COMMON(C), EQUIV(E). DUMMY ARG(O), NAMED CONSTANTS), STMT.FUNCT(F), EXT. FUNCT(X) , INTR. FUNCT(I), EXPL.TYPE(T)
HAME BflPJE TAQ PSCIAR6P references
Al R*4 17 18 2* 26
A2 R*4 1* 17 19
CHAR14 CHAR T 7 15 26
CXSUB X 24
C32 C»32 AET 4 8 10 26
C8A C*8 CT 3 11
C8B C*8 CT 3 12
CSV C*8 T 3 27
FLOAT R*4 I 22
I 1*4 20 22 22
12 I** AE 9 10
J 1*4 16 26
LI L*l CET 5 9 12 21
PI R*8 KT 1 2 2*
R4A R*4 ACE 8 10 11
R84 R*8 AET 6 8 10 17 22 25 26
R8V R*8 T 6 22 22 24
R8VNU R*8 T 6 UNREFERENCED
uscnnt y i
VSERHt X 1
TAG: FORMAT(F), NON-EXECUTABLE(N) . USED AS ARGUMENT(A), OBJECT OF BRANCH(B), USED IN ASSIGN STATEMENT(S)
LASJi IM PEFINEP references
100 23 20
111 NFS 13 16
200 B 26 18 19
300 B 28 24
01 000 00001 1 UNREFERENCED
01 000 00019 19 UNREFERENCED
01 000 00020 20 UNREFERENCED
01 000 00022 22 UNREFERENCED
01 000 00025 25 UNREFERENCED
02 001 00020 B 20 20
02 002 00020 B 23 20
Figure 31. Example of a Cross-Ref erence Dictionary — XREF Option
N label for a nonexecutable statement ^\.
S label used in an ASSIGN statement
If a label is used in more than one way, all tags that apply are
pri nted.
DEFINED COLUMN^ This column displays the internal sequence
number (ISN) of the statement in which the label is defined.
REFERENCES COLUMN 5 This column displays the internal sequence
number (ISN) of all statements in which there are references to
the label.
If there are no program references to the label, the word
UNREFERENCED is printed.
END OF COMPILATION MESSAGE
The last entry of the compiler output listing is the informative
message:
*kkk***kk*xkkk*xxk**END OF COMPILATION n xkkxxk*xxxk*x*xk*xxkxkx*
Where n is the number identifying this program's position in a
batch compilation.
US ING THE STANDARD LANGUAGE FLAGGER — FIPS OPTION
Through the FIPS option, you can help ensure that your program
conforms to the current FORTRAN standard — American National
Standard Programming Language FORTRAN, ANSI X3. 9-1978.
You can specify standard language flagging either at the full
language level or at the subset language level:
o
120 VS FORTRAN Application Programming: Guide
Jf%
FIPS=F requests the compiler to issue a message for any
language element not included in full American
National Standard FORTRAN.
FIPS~S requests the compiler to issue a message for any
language element not included in subset American
National Standard FORTRAN.
NOFIPS requests no flagging for nonstandard language
elements.
The messages tell you which language items are not included in
the current American National Standard. They're all in the same
format as the other diagnostic messages, and they're all at the
0(1) (information) level.
For the formats of diagnostic messages, see "Diagnostic Message
Listing — FLAG Option."
Fixing Compile-Time Errors — Advanced Programming 121
LINK-EDITING YOUR PROGRAM — ADVANCED PROGRAMMING
You must link-edit any object module before you can execute your
program, combining this object module with others to construct
an executable load module.
For VM/370-CMS considerations on loading and executing your
programs, see "Using VM/370-CMS with VS FORTRAN."
For TSO considerations on loading and executing your program*
see "Using 0S/VS2-TS0 with VS FORTRAN."
AUTOMATIC CROSS-SYSTEM SUPPORT
source program under any
supported operating system. You can then link-edit the resulting
object module under the same system, or under any other supported
system.
For example, you could request compilation under VM/370-CMS and
then link-edit the resulting object module for execution under
DOS/VSE.
You don f t have to request anything special during compilation to
do this; VS FORTRAN uses the execution-time library for all
system interfaces, so the operating system under which you
link-edit determines the system under which you execute.
LI NKAGE EDITOR INPUT
Your input to the linkage editor can be the object module in ^'\
machine-language format (which you request through the OBJECT \^'
compile-time option), or as a machine-language input data set
(which you request through the DECK compile-time option).
You request the DECK option when you want to catalog the object
module and save it for future link-edit runs.
Request the OBJECT option when you want to combine the link-edit
task with the compilation task. You can then catalog and/or
execute the load module produced.
OBJECT MODULE AS LINK-EDIT DATA SET — DECK OPTION
You use the DECK compile-time option to request an object module
punched into a card deck. The deck produced is in 80-character
f i xed format.
The deck is a copy of the object module — which consists of
dictionaries, text, and an end-of-module indicator. (Object
modules are described in greater detail in the appropriate
linkage editor and loader publications, as listed in the
Preface.)
The object deck consists of four types of records, identified by
the characters ESD, RLD, TXT, or END in columns 2 through 4.
Column 1 of each card contains a 12-2-9 punch. Columns 73 through
80 contain the first four characters of the program name followed
by a foui — digit sequence number. The remainder of the card
contains program information.
122 VS FORTRAN Application Programming? Guide
ESO Record
ESD records describe the entries of the External Symbol
Pi ctionary , which contains one entry for each external symbol
defined or referred to within a module. For example> if program
MAIN calls subprogram SUBA, the symbol SUBA will appear as an
entry in the External Symbol Dictionaries of both the program
MAIN and the subprogram SUBA.
The linkage editor matches the entries in the dictionaries of
other included subprograms and, when necessary, to the automatic
call library.
ESD records sre divided into four types, identified by the digits
0, 1, 2, or 5 in column 25 of the first entry, and column 57 of a
third entry (there can be 1, 2, or 3 external-symbol entries in a
record) .
The contents of each type of ESD record are:
ESD Type Contents
Name of the program or subprogram and indicates the
beginning of the module.
1 Entry point name appearing in an ENTRY statement of a
subprogram.
2 Name of a subprogram referred to by the source module
through CALL statements, EXTERNAL statements, and
explicit and implicit function references. (Some VS
FORTRAN intrinsic functions are so complex that a
function subprogram is called in place of in-line
coding. Such calls are defined as implicit function
references ) .
5 Information about a COMMON block.
TXT Record
RLD Record
TXT records contain the constants and variables your source
program uses, any constants and variables generated by the
compiler, coded information for FORMAT statements, and the
machine instructions generated by the compiler from the source
module.
RLD records describe entries in the Relocation Dictionary , which
contains one entry for each address that the linkage editor or
loader must resolve before the module can be executed.
The Relocation Dictionary contains information that enables
absolute storage addresses to be established when the module is
loaded into main storage for execution. These addresses cannot
be determi ned earlier because the absolute starting address of a
module cannot be known until the module is loaded.
The linkage editor or loader consolidates RLD entries in the
input modules into a single relocation dictionary when it
creates a load module.
RLD records contain the storage addresses of subprograms called
through ESD type 2 records.
Link-Editing Your Program — Advanced Programming
123
END Record
The END record indicates: /1f ~^
• The end of the object module to the linkage editor ^^
• The relative location of the main entry point
• The length (in bytes) of the object module.
The structural order of a typical VS FORTRAN object module is
shown in Figure 32.
Record Type Usage
ESD (Type 0) Names object module
statements)
TXT For FORMAT statements
TXT For compiler-generated constants
ESD (Type 5) For COMMON areas
ESD (Type 2) For external references in CALL
and EXTERNAL statements* and
statements using subprograms
RLD For external references in CALL
and EXTERNAL statements, and
statements using subprograms
TXT For source program constants
ESD (Type 2) For compilei — generated external Vj^
references
RLD For compilei — generated external
references
TXT For object module instructions
TXT For the branch list
RLD For the branch list
END End of object module
Figure 32. Object Module Structure
PRODUCING A LOAD MODULE— OBJECT OPTION
Specify the OBJECT option when you want either to link-edit and
execute your program immediately, or to link-edit the program
and catalog the load module for execution at some later time.
»
LINK-EDITING FOR IMMEDIATE EXECUTION
The simplest way to link-edit for immediate execution is to use a
li nk-edi t-execute cataloged procedure. See "Executing Your
Program — Advanced Programming" for details.
You can also execute the program immediately after link-editing /| \
by including the execution step immediately after the link-edit \j^
124 VS FORTRAN Application Programming: Guide
step. See "Executing Your Program — Advanced Programming" for
details on the execution step.
LINK-EDITING YOUR PROGRAM— OS/VS
The following sections show how to catalog your object module or
load module under OS/VS* and how to use the OS/VS linkage editor
or loader.
CATALOGING YOUR LOAD MODULE — OS/VS
You can catalog the data set containing the load module by
defining it in a SYSLMOD DD statement during link-edit
processi ng.
See the VS FORTRAN Application Development* System Services
Reference Supplement for details.
EXECUTING A LINK-EDIT — OS/VS
c
Under OS/VS, there are two different programs you can use to
perform the link-edit* the linkage editor or the loader. Which
one you use depends upon the output you want produced.
THE LINKAGE EDITOR: Use the linkage editor when you want to
reduce storage requirements through overlays, or to use
additional libraries as input, or to define the structural
segments of the program.
THE LOADER : Use the loader when your input is a small object
module that doesn't require overlay, that doesn't require
additional linkage editor control statements, and that you'll be
executing immediately.
VS FORTRAN supplies you with cataloged procedures that let you
link-edit or load your programs easily. See "Using and Modifying
Cataloged Procedures — OS/VS" for details.
Using the Linkage Editor — OS/VS
When you use the linkage editor, rather than the loader, you have
many processing options and optional data sets you can use,
depending on the 1 ink-edi t processi ng you want done.
LINKAGE EDITOR PROCESSING OPTIONS — OS/VS: Through the PARM
option of the EXEC statement, you can request additional
optional output and processing capabilities:
MAP — specifies that a map of the load module i s to be
produced on SYSPRINT, giving the length and location of the
main program and all subprograms.
XREF — specifies that a cross reference listing of the load
module i s to be produced on SYSPRINT, for the main program
and all subprograms.
LET — specifies that the linkage editor is to allow load
module execution, even when abnormal conditions have been
detected that could cause execution to fail.
NCAL — specifies that the linkage editor is not to attempt to
resolve external references.
If your program attempts to call external routines, you'll
get an abnormal termination.
LIST — specifies that the linkage editor control statements
are to be listed in the SYSPRINT data set.
Link-Editing Your Program — Advanced Programming 125
For reference information on these linkage editor data sets, see
the VS FORTRAN Application Programming- System Services
Reference Supplement .
USIHG LINKAGE EDITOR CONTROL STATEMENTS — OS/VS : Under OS/VS, you
can use the INCLUDE and LIBRARY linkage editor control
statements.
INCLUDE Statement: Use the INCLUDE statement to specify
additional object modules you want included in the output load
module.
LIBRARY Statement: Use the LIBRARY statement to specify
additional libraries to be searched for object modules to be
included in the load module.
For reference informaton on these statements* see the VS FORTRAN
Application Programming: System Services Reference Supplement .
Using the Loadei — OS/VS
You choose the loader when you want to combine link-editing into
one job step with load module execution. The loader combines your
object module with other modules into one load module* and then
places the load module into main storage and executes it.
The loader options you can use, and the loader data sets are
described in the following paragraphs.
LOADER OPTIONS — OS/VS : When you execute the loader, you can
specify the following options through the PARM parameter of the *
EXEC statement:
MAP|NOHAP — specifies whether a map of the load module is to
be produced on SYSPRINT, giving the length and location of
the main program and all subprograms.
^_>
OVLY — specifies that the load module i s to be in overlay
format. That is, that segments of the program will share the ^r-v )
same storage at different times during processing. (For more
details, see "Coding Calling and Called Programs.")
SIZE — specifies the amount of virtual storage to be used for
this link-edit job.
REQUIRED LINKAGE EDITOR DATA SETS — OS/VS: For any link-edit job,
you must make certain that at least the following data sets are
available:
SYSLIN — used for compiler output and linkage editor input.
SYSLMOD — used for linkage editor output.
SYSPRINT — makes the system print data set available, used
for writing listings and messages. This data set can be a
direct access, ma'^nstic ta^s, or rt r!ntsr data set.
SYSUT1 — direct access work data set needed by the link-edit
process.
OPTIONAL LINKAGE EDITOR DATA SETS — OS/VS: l n addition, depending
on what you want the linkage editor to do for you, you can
optionally specify the following data sets:
SYSLIB — direct access data set that makes the automatic call
library CSYS1 . FORTLIB) available. (Required for execution.)
SYSTERM — used for writing error messages and the compiler
statistics listing. This data set can be on a direct access,
magnetic tape, or printer device.
Vy
126 VS FORTRAN Application Programming: Guide
LET|NOLET — specifies whether the linkage editor is to allow
load module execution, even when abnormal conditions that
could cause execution to fail have been detected.
CALL|NCAL — specifies whether or not the loader is to call
attempt to resolve external references. If- you specify NCAL
and your program attempts to call external routines, you'll
get an abnormal termination.
SIZE — lets you specify the amount of storage to be allocated
for loader processing.
EP — lets you specify the name of the entry point of the
program being loaded.
PRINT INOPRINT — specifies whether or not loader messages are
to be listed in the data set defined by the SYSLOUT DD
statement.
RESlNORES — specifies whether or not the link pack area is to
be searched to resolve external references.
SIZE — specifies the amount of storage to be allocated for
loader processing; this size includes the size of your load
module.
LOADER DATA SETS — OS/VS: For any loader job, you must make
certain that at least the SYSLIN data set (used for compiler
output) and the SYSPRINT data set (used for printed output) are
avai lable .
In addition, depending on what you want the loader to do for you,
you can optionally specify the following data sets :
SYSLIB — direct access data set that makes the automatic call
library (SYS1 . FORTLIB) available. This is the library used
for FORTRAN library subroutines.
SYSLOUT — makes the system output data set available, used
for writing listings. This data set can be a direct access,
magnetic tape, or printer data set.
FTnnFnnn — data sets for user-defined files — can be unit
record, magnetic tape, or direct access data sets.
LINK-EDITING YOUR PROGRAM — DOS/VSE
The following sections show how to catalog your object module or
load module under DOS/VSE, and how to use the DOS/VSE linkage
edi tor.
CATALOGING YOUR LOAD MODULE — DOS/VSE
You can catalog the load module (phase) in th© core image
library; this can be either the system core image library or your
own private core image library.
When you catalog the load module in the core image library, your
link-edit step must include the following statement J
// OPTION CATAL
which invokes the linkage editor and places the phase output into
a core image library.
Place the statement before the first link-edit control card, and
before the PHASE statement for the program you want cataloged.
See the VS FORTRAN Application Development* System Services
Reference Supplement for details.
Link-Editing Your Program — Advanced Programming 127
EXECUTING A LINK-EDIT— DOS/VSE
Under DOS/VSE* the only control statement you need to link-edit /f~V
your program is the EXEC LINKEDT statement. DOS/VSE has the ^y
autolink feature which* unless you suppress it* always resolves
all object module references to external-names* after all the
input modules have been read from SYSLNK* SYSIPT, and/or the
relocatable library. Ordinarily* you shouldn't suppress it.
However* if you use service routines or extended error handling
routines* you will need INCLUDE statements* as shown in
Figure 37 on page 143.
In addition to the EXEC LINKEDT statement and the autolink
feature* there ore other linkage editor statements you can use to
control linkage editor functions*
ACTION specifies linkage editor options* as follows 2
CANCEL requests immediate cancellation if errors
occur.
CLEAR initializes the temporary portion of the core
image library to binary zeros.
BG/F1-F6 specifies how input i s to be processed:
8G background execution
F1-F6 Execution in one of the foreground
partitions* Fl through F6
HAP specifies that a storage map and messages are
to be pri nted.
NOHAP suppresses the MAP option; messages are to be
printed.
NOAUTO suppresses the autolink feature for this run. \^y
INCLUDE specifies that a module from the relocatable library or
from SYSIPT (if the compile-time DECK option was
specified) is to be included* a number of modules may be
specified.
PHASE specifies a name for the phase (load module) to be
produced; the starting address and a relocation factor
can also be specified.
You can also specify control statements to control overlay
requirements* for details, see "Coding Calling and Called
Programs. "
Logical Units Used for Link-Editing — DOS/VSE
The following logical units are used during li nk-edi ti ng:
SYSLNK used for linkage editor input
SYSRES used for input in form of relocatable object modules
SYSRLB used for linkage editor input from the system
relocatable library; this is the library used for
FORTRAN library subroutines.
SYSLST used for input from relocatable object modules in a
private library
SYSCLB used for output placed in a private core image library
SYS001 used as a linkage-editor work file
Q
128 V5 FORTRAN Application Programming* Guide
LINKAGE EDITOR OUTPUT
Output from the linkage editor is in the form of load modules (or
phases) in executable form. The exact form of the output depends
upon the options in effect when you requested the link-edit, as
described in the previous sections.
\J
Link-Editing Your Program — Advanced Programming 129
EXECUTING YOUR PROGRAM — ADVANCED PROGRAMMING
When you execute the load module (or phase) » you can either
execute it directly as output from the link-edit (or loader)
step, or specify that it be called from a library of load
modules.
When you execute a load module, you may need many different
files, as outlined in the following sections.
For VM/370-CM5 considerations on program execution, see "Using
VM/370-CMS with VS FORTRAN."
EXECUTING YOUR PROGRAM — OS/VS
The following sections describe the data sets you may need, and
outline the job control language you must use to execute your
programs under OS/VS.
USING LOAD MODULE DATA SETS — OS/VS
If you're using cataloged procedures, or if you're using the
device assignments as shipped by IBM, you must use the DD names
shown in Figure 33.
FORTRAN
Ref.
Number
ddname
Function
Device Type
Usage
SYSIN Input data set
to load module
FT05F001 Input data set
to load module
6
FT06F001
Printed output
data
7
FT07F001
Punched output
data
0-4
FTnnFnnn
Sequential
8-99
Data Set
0-4
FTnnFnnn
Direct Access
8-99
Data Set
0-4
FTnnFnnn
Parti tioned
8-99
Data Set Member
Using Sequential
Access
Card Reader,
Magnetic Tape,
Direct Access
Card Reader,
Magnetic Tape,
Direct Access
Pri nter,
Magnetic Tape,
Direct Access
Card Punch,
Magnetic Tape,
Direct Access
Unit Record,
Magnetic Tape,
Direct Access
Direct Access
Direct Access
Load Module
Input Data
Load Module
Input Data
Load Module
Output Data
Load Module
Output Data
Program
Data
Program
Data
Load Module
Input Data
yy
Figure 33. Load Module Data Sets — OS/VS
c
130 VS FORTRAN Application Programming! Guide
Using Cataloged Load Modules — OS/VS
You can execute cataloged load modules using either a STEPLIB DD
or a JOBLIB DD statement.
USING JOBLIB DD : If you specify a JOBLIB DD statement for the
load module* the JOBLIB library is available through all job
steps of the job.
To ensure that the library remains available* you must specify
the JOBLIB DD statement immediately after the JOB statement.
USING STEPLIB DD :If you specify a STEPLIB DD statement for the
load module* the STEPLIB library is available for only this one
step of the job.
You can place the STEPLIB DD statement anywhere among the DD
statements for this job step.
c
EXECUTING THE LOAD MODULE — OS/VS
How you execute the load module depends on the kind of job you're
runnings execute only* link-edit and execute* or compile
link-edit and execute.
VS FORTRAN supplies you with cataloged procedures that let you
compile* link-edit or load* and/or execute easily. See "Using
and Modifying Cataloged Procedures — OS/VS" for details.
Execute Only — OS/VS
The job control statements you use are!
//JOB Statement
//EXEC Statement (load module)
//DD Statements (as required for execution)
(Input Data to be processed)
/HEnd-of-Data Statement (if input data is on cards)
//End-of-Job Statement
Link-Edit and Execute — OS/VS
The job control statements you use are'>
//JOB Statement
//EXEC Statement (linkage editor)
//DD Statements (as required for linkage editing)
(Link-edit is performed)
//EXEC Statement (load module)
//DD Statements (as required for execution)
(Input data to be processed)
/^Statement (if input data is on cards)
//End-of-Job Statement
Compile, Link-Edit, and Execute— OS/VS
The job control statements you use are!
//JOB Statement
//EXEC Statement (VS FORTRAN Compiler)
//DD Statements (as required for compilation)
(Source program to be compiled)
/HEnd-of-Data Statement (if source program is on cards)
//EXEC Statement (linkage editor)
//DD Statements (as required for link-editing)
(Link-edit is performed)
//EXEC Statement (load module)
//DD Statements - (as required for load module execution)
(Input data to be processed)
Executing Your Program — Advanced Programming 131
/*End-of-Data Statement (if input data is on cards)
//End-of-Job Statement
Reference documentation for these job control statements is
given in the VS FORTRAN Application Programming? System Servi ces
Reference Supplement .
EXECUTING YOUR PROGRAM — DOB/VSE
The following sections describe the logical units you may need,
and outline the job control statements you must use to execute
your programs under DOS/VSE.
LOAD MODULE LOGICAL UNITS— DOS/VSE
If you're using cataloged procedures, or if you're using the
logical units as shipped by IBM, you must specify them as shown
in F i ni i r o ^6
FORTRAN Logical Unit
Ref.
Number
SYS000
SYS001
8
thru
99
SYS002
3
SYS003
4
SYS004
5
SYSIPT
or
SYSIN
SYSLST
SYSPCH
SY5005
thru
SYS096
DOS File Name
IJSYSOO
IJSYS01
IJSYS02
IJSYS03
IJSYS04
IJSYSIP
IJYSYLS
IJSYSPC
IJSYS05
thru
IJSYS96
Function
Device
(Primary)
Type
Program
Unit record
data set
Magnetic tape
Direct access
Program
Unit record
data set
Magnetic tape
Direct access
Program
Unit record
data set
Magnetic tape
Direct access
Program
Unit record
data set
Magnetic tape
Di rect access
Program
Magnetic tape
data set
Direct access
Input data set
to load module
Punched output
data
Printed output
data
Program
data set
Note: Units 9 through 99 may be added by reassembling the unit
(IFYUATBL). See "Using the VSFORTL Macro" in VS FORTRAN Instal
Customi zati on .
Figure 34. Load Module Logical Units — DOS/VSE
Unit record
Magnetic tape
Direct access
Unit record
Magnetic tape
Direct access
Printer
Magnetic tape
Di rect access
Unit record
Magnetic tape
Direct access
assignment table moduli
lation and
w
132 VS FORTRAN Application Programming* Guide
c
EXECUTING THE LOAD MODULE — DOS/VSE
Hon you execute the load module (or phase) depends on the kind of
job you're runnings execute only, link-edit and execute, or
compile link-edit and execute.
Execute Only — DOS/VSE
The job control statements you use are:
// JOB Statement
// ASSGN Statements (as required for execution)
// EXTENT Statements (as required for execution)
// DLBL/TLBL Statements (as required for execution)
// EXEC Statement (load module (or phase))
(Input data to be processed)
/x End-of-Data Statement (if input data is on cards)
/& End-of-Job Statement
Link-Edit and Execute — DOS/VSE
The job control statements you use are:
// JOB Statement
// OPTION LINK (sets link option)
or
// OPTION CATAL (sets link option and catalogs phase)
INCLUDE Statements (as required for linkage editing)
// ASSGN Statements (as required for linkage editing)
// DLBL/TLBL Statements (as required for linkage editing)
// EXEC Statement (linkage editor)
(Linkage editor execution)
// ASSGN Statements (as required for execution)
// DLBL/TLBL Statements (as required for execution)
// EXTENT Statements (as required for execution)
// EXEC Statement (load module)
(Input data to be processed)
/* End-of-Data Statement (if input data is on cards)
/& End-of-Job Statement
Note! Unless you specify OPTION CATAL, the phase is deleted from
the core image library after execution is completed.
Compile, Link-Edit, and Execute — DOS/VSE
The job control statements you use are:
// JOB Statement
// OPTION LINK (sets link option)
or
// OPTION CATAL (sets link option and catalogs phase)
// EXEC Statement (VS FORTRAN Compiler)
(VS FORTRAN source program)
/* Statement (if source program i s on cards)
// ASSGN Statements (as required for linkage editing)
// DLBL/TLBL Statements (as required for linkage editing)
// EXEC Statement (linkage editor)
(Linkage Editor execution)
// ASSGN Statements (as required for execution)
// DLBL/TLBL Statements (as required for execution)
// EXTENT Statements (as required for execution)
// EXEC Statement (load module)
(Input Data to be processed)
/* End-of-Data Statement (if input data is on cards)
/I End-of-Job Statement
Note: Unless you specify OPTION CATAL, the phase is deleted from
the core image library after execution is completed.
Executing Your Program — Advanced Programming 133
Reference documentation for these job control statements is
given in the VS FORTRAN Application Programming? System Services
Reference Supplement .
LOAD MODULE EXECUTION-TIME OUTPUT
The output that execution of your load module gives you depends
upon whether or not there are errors in your program.
EXECUTION WITHOUT ERROR
If your program executes without error* and gives the results you
expect, your task of program development is completed.
EXECUTION WITH ERRORS
"when your program has errors in it, your execution-time output
may be incorrect, or nonexistent.
You may or may not get error messages as well. Any VS FORTRAN
execution-time error messages you get come from the VS FORTRAN
Library. These messages are in a format similar to the compiler
message format (see "Library Diagnostic Messages").
If you get output from the program itself, it may be exactly what
you expected, or (if there are logic errors in the program) it
may be output you didn't expect at all.
When this happens, you must proceed to the next step in program
development, described in "Fixing Execution-Time
Errors — Advanced Programming."
w
\y
134 VS FORTRAN Application Programming? Guide
FIXING EXECUTION-TIME ERRORS — ADVANCED PROGRAMMING
You can begin to fix execution-time errors by scanning the source
program for the kinds of errors described in "Fixing
Execution-Time Errors — Simplified Programming" in Part 1.
However, some execution-time errors are difficult to find and a
simple scan of the source program isn't always very helpful. VS
FORTRAN has a number of features to help you find errors. The
major ones are described in the following sections.
EXECUTION-TIME MESSAGES
Execution-time messages are issued by the execution-time
library. There are three types of messages issued *•
Library Diagnostic Messages — which give information about
errors occurring when the library subroutines are
executed — for example, input/output or mathematical
subroutine errors
Program Interrupt Messages — which give information about
errors that occur when system rules are violated
Operator Messages — which communicate with the operator when
program execution makes it necessary (for example, when a
PAUSE statement is executed)
LIBRARY DIAGNOSTIC MESSAGES
The library diagnostic messages have a format similar to that of
the compiler messages. The library messages give you information
on execution of input/output routines, mathematical subroutines,
and the utility routines.
The messages all have the prefix IFY; they are in the following
format *
IFYnnnnI origin 'message text'
where each of the areas has the following meaning:
IFY is the message prefix identifying all VS FORTRAN
library messages
nnnnl is the unique number identifying this message
origin is the abbreviated name for the library module
that originated the message.
'message-text ' explains the execution-time error that was
detected.
The action the program takes after a message is issued depends
upon your extended error handling routines. For further
information, see "Using Extended Error Handling."
The execution-time messages are documented in the VS FORTRAN
Application Programming' library Reference manual.
Using the Optional Traceback Map
Whenever you get a library diagnostic message, you can also,
optionally, get a traceback map.
Fixing Execution-Time Errors — Advanced Programming 135
Your organization may have set this as the default you get ^
whenever a library message, i 5 generated. jr-^ J
If this is not the default for your organization, you can request
a traceback map, using the CALL ERRTRA routine. See "Using the
Optional Traceback Map" for a further discussion.
The traceback map gives you guidance in determining where the
error occurred.
The traceback map lists the names of called routines, internal
sequence numbers within routines, and contents of registers as
follows*
ROUTINE
lists the names of all routines entered in the current
calling sequence.
Nsmes are shown with the latest routine called at the top
and the earliest routine called at the bottom of the listing
except when the earliest name shown is VSCOM.
CALLED FROM ISN
lists the FORTRAN program's internal sequence number (ISN)
that called the routine, except when calls were made to
VSCOM.
Internal statement numbers are available to the traceback
routine only if you specified the GOSTMT compiler option.
REG. 14
lists the absolute storage location of the instruction that
calls ROUTINE.
REG. 15
lists the absolute location of the entry point to ROUTINE.
REG.
lists the results of function subprogram operations, when
appli cable.
REG. 1
lists the address of any argument list passed to ROUTINE.
ENTRY POINT=address
shows the entry point of the earliest routine entered.
The control program executes its own routine to recover from the
error, and displays the following message*
STANDARD FIXUP TAKEN, EXECUTION CONTINUING
If your organization uses its own error recovery routine, the
word USER replaces STANDARD in this message.
After the error recovery, execution continues.
The summary of errors printed at the end of the listing can help
you determine how many times an error was encountered. If your
source program contains many input/output statements* locating
an error can become a formidable task. By pinpointing the exact
FORTRAN statement involved, the traceback map makes it much
easier for you to locate execution errors.
If you specify the GOSTMT compiler option, the traceback map
lists the internal sequence number (ISN) calling each routine.
Using the ISN, you can locate the source statement and module
called.
W
136 VS FORTRAN Application Programming: Guide
LIST Compiler Option and Traceback naps
If you specify the LIST compiler option* you can use the
traceback map to locate the last assembler language instruction
executed. See Figure 33 for an example of the object program
listing. The steps to take are:
1. For the topmost routine listed under the heading REG. 14,
subtract the 6 low-order hexadecimal digits in the number
shown under ENTRY POINT. This produces the relative location
of the instruction in the listing.
2. Find this location in the object code listing.
3. Using this location as a beginning point, scan upward in the
column that identifies statement numbers to locate the
nearest number occurring before the instruction; this is the
statement number of the FORTRAN statement involved in the
error.
4. Investigate the FORTRAN statement in the source module
li sti ng.
5. If the source statement is correctly specified, investigate
the corresponding job control statement for accuracy.
PROGRAM INTERRUPT MESSAGES
During program execution, you* 11 get messages whenever the
program is interrupted because of the following exceptions*
operation, fixed-point division, decimal division,
floating-point division, exponent overflow, or exponent
underflow.
Program interrupt messages are written in the output data set.
Such an interrupt message gives you guidance in determining the
cause of the error; it indicates what system rule was violated.
Exception codes themselves appear in the eighth digit of the PSW
and indicate the reason for the interruption. Their meanings are
as follows:
Code Meaning
1 i s an operation exception , that is, the operation is not
one that is defined to the operating system.
$ is a protection exception , that is, an illegal reference
is made to an area of storage protected by a key.
5 is an addressing exception , that is, a reference is made to
a storage location outside the range of storage available
to the job.
6 is a specification exception , for example, a unit of
information does not begin on its proper boundary.
7 is a d ata exception , that is, the arithmetic sign or the
digits in a number arG incorrect for the operation being
performed.
9 is a f ixed-poi nt-di vi de exception that is, an attempt is
made to divide by zero.
C is an exponent-overflow exception , that is, a
floating-point arithmetic operation produces a positive
number mathematically too large to be contained in a
register (the mathematically largest number that can be
contained is 16 63 or approximately 7.2 x 10 75 ).
Exponent-overflow generates the additional message:
Fixing Execution-Time Errors — Advanced Programming 137
OPERATOR MESSAGES
REGISTER CONTAINED number _
where number is the floating-point number in hexadecimal \J*
format. (When extended-precision is in use, the message
prints out the contents of two registers.) A standard
corrective action is taken and execution continues.
D indicates an exponent-underflow exception , that is, a
floating-point ari thmeti c operati on generates a number
with a negative exponent mathematically too small to be
contained in a register (mathematically smaller than 16-* 5
or approximately 5.4 x 10- 79 ). Exponent-underflow also
generates the message*
REGISTER CONTAINED number
where number is the number generated.
(When extended-precision is in use, the message prints out
the contents of two registers.) A standard corrective
action is taken and execution continues.
F is a f loating-point-di vi de exception , that is, an attempt
is being made to divide by zero in a floating-point
operation. Floating-point divide also generates the
message*
REGISTER CONTAINED number
(When extended-precision is \n use, the message prints out
the contents of two registers.) A standard corrective
action is taken and execution continues.
The standard corrective action for each type of interrupt is
described in the "Program Interrupt Messages" section of the VS / -- s '
FORTRAN Application Programming* Library Reference manual.
Notes:
1. Operation, protection, addressing, and data exceptions
(codes 1, 4, 5, and 7) ordinarily cause abnormal termination
without any corresponding message.
2. Protection and addressing exceptions (codes 4 and 5)
generate a message only if a specification exception (code
6) or an operation exception (code 1) has also been detected.
3. A data exception (code 7) generates a message only if a
specification exception has also been detected. When a
message is generated for codes 4, 5, or 7, the job will
terminate.
The completion code in the dump indicates that job
termination is due to a specification or operation
exception; however, the error message indicates the true
exception that caused the termination.
Operator messages ere generated when your program executes a
PAUSE or STOP n statement. Operator messages are written on the
system device specified for operator communication, usually the
console. The message can guide you in determining how far your
FORTRAN program has executed.
Figure 35 shows the form that the operator message may take.
(>
138 VS FORTRAN Application Programming* Guide
yy n I 'message*
Figure 35. Operator Message Format
f\
The meaning of the lowercase characters in the figure is as
follows*
Character Meaning
yy message identification number assigned by the system.
n string of 1 through 5 decimal digits you specified in
the PAUSE or STOP statement. For the STOP statement,
this number is placed in register 15.
'message* character constant you specified in the PAUSE or STOP
statement.
printed when a PAUSE statement containing no
characters is executed. (Nothing is printed for a
similar STOP statement.)
A PAUSE message causes program execution to halt, pending
operator response. To resume program execution, the operator
issues the command*
REPLY yy, f z f
where yy i s the message identification number and z is any letter
or number .
A STOP message causes program termination.
I IBM EXTENSION 1
USING DEBUG PACKETS
A debug packet helps you locate obscure sources of error in
your source program. It consists of the DEBUG statement, a set
of FORTRAN statements, and an END DEBUG statement. The DEBUG
statement and debug packets, when used, must be the first
statements in your program.
In debugging packets you can use the following statements'
DEBUG
specifies the debugging options you want performed, which
can be*
• Check the validity of array subscripts.
• Trace the order of execution of all or part of the
program.
• Display array or variable values each time they
change during program execution.
AT
O
specifies the statement number before which the debugging
packet is to be executed.
The AT statement begins each new debugging packet in the
program and ends the previous one.
Fixing Execution-Time Errors — Advanced Programming 139
TRACE ON | TRACE OFF ' ' *~>w
begin or end program execution tracing. i 7
DISPLAY
writes a list of variable or array values that you
specify.
END DEBUG
ends the last debugging packet specified.
In addition to these specific debugging statements (valid only
in a debugging packet) you can also use most FORTRAN procedural
statements to gather information about what's happening during
execution.
When you specify a debugging packet, you'll get information
about program execution in a form that's easy to understand and
easy to use. Figure 36 shows how you can use VS FORTRAN
debugging statements.
If you use a debugging packet in your source program and
compile it using OPTIMIZE(l), OPTIMIZED), or OPTIMIZED), the
compiler changes the optimization parameter to NOOPTIMIZE.
END OF IBM EXTENSION
USING EXTENDED ERROR HANDLING
Extended error handling can be either by default or you can
control it, using predefined CALL statements.
EXTENDED ERROR HANDLING BY DEFAULT
Your organization has a default value for the following ^;
execution-time conditions 1 ^t_V
• The number of times an error can occur before the program is
terminated.
• The maximum number of times an execution-time message is
printed.
• Whether or not a traceback map i s to be printed with the
message.
• Whether or not your organiation' s error-exit routine is to
be called.
These are the extended error handling facilities that may be
available to you.
When extended error handling by default is in effect for your
organization, the following actions take place when an error
occurs.
The FORTRAN error monitor (ERRMON) receives control.
The error monitor prints the necessary diagnostic and
informative messages:
• A short message, along with an error identification number.
The data in error (or some other associated information) is
printed as part of the message text.
For a complete listing of execution-time messages, see the
VS FORTRAN Application Programming' Library Reference
manual.
• A summary error count, printed when the job is completed.
I
140 VS FORTRAN Application Programming: Guide
o
ThQ error count, telling you how many times each error
occurred.
• A traceback map* tracing the subroutine flow back to the main
program, after each error occurrence.
Then the error monitor takes one of the following actions**
• Terminates the job.
• Returns control to the calling routine, which takes a
standard corrective action and then continues execution.
• Calls a usei — written closed subroutine to correct the data
in error and then returns to the routine that detected the
error, which then continues execution.
Program Code With A Debugging Packet:
A DEBUG SUBCHK(ARRAYl), TRACE, INIT(ARRAYl)
B AT 10
C TRACE ON
D (procedural code for debugging)
E AT 40
F TRACE OFF
G DISPLAY I, J, K, L, M, N, ARRAY1
H END DEBUG
10 DO . . . (program tracing begins here; procedural debugging
code executed)
30 CONTINUE
40 WRITE ... (program tracing ends here; values of I, J, K, L,
M, N, and ARRAY1 are displayed)
How Each Debugging statement is Used:
A The DEBUG statement begins the first debugging packet and specifies the following*
• SUBCHK(ARRAYl) requests validity checking for the values of ARRAY1 subscripts
• TRACE specifies that tracing will be allowed within the debugging packet
• INIT(ARRAYl) specifies that ARRAY1 will be displayed when values within it
change
6 AT 10 begins the first debugging packet.
C TRACE ON turns on program tracing at statement number 10.
D (Procedural debugging code contains valid FORTRAN statements to aid in debugging;
for example, to initialize variables.)
E AT 40 ends the first debugging packet and begins the second.
F TRACE OFF turns off program tracing at statement number 40.
G The DISPLAY statement writes the values of I, J, K, L, M, N, and ARRAY1.
H END DEBUG ends the second (and last) debugging packet.
Figure 36. Using Batch Symbolic Debugging Statements
The actions of the error monitor are controlled by settings in
the option table. IBM provides a standard set of option table
Fixing Execution-Time Errors — Advanced Programming 141
entries; your system admini strator may have provided additional
entries for your organization.
By altering the option table at execution-time, through ERRSET, '\_J
you can specify the user exit to be taken.
If no corrective action, either standard or user-written, is to
be taken, make sure the table entry specifies that only one error
is to be allowed before an abnormal termination.
To make changes to the option table dynamically at load module
execution-time, you can use the predefined CALL subroutines,
summarized in the next section.
CONTROLLING EXTENDED ERROR HANDLING — CALL STATEMENTS
For each error condition detected, you have both dynamic and
default control over*
• The number of times the error is allowed to occur before
program termination
• The maximum number of times each message may be printed
• Whether or not the traceback map i s to be printed with the
message
• Whether or not a usei — written erroi — exit routine is to be
called
The action that takes place is governed by information stored in
the option table, which is present in main storage. (A permanent
copy of the option table is maintained in the FORTRAN library.)
Reference documentation for using the option table is given in
the VS FORTRAN Application Programming* Language Reference f \.
manual. \_jj
The predefined CALL routines let you request extended error
handling, so that you get greater control over load module
errors'
CALL ERRMON — causes execution of the error control monitor.
CALL ERRTRA — causes execution of the traceback routines.
(See "Using the Optional Traceback flap.")
CALL ERRSAV — copies an option table entry into an area
accessible to your program.
CALL ERRSTR — stores an entry into the option table from your
program.
CALL ERRSET — changes up to 5 values associated with an entry
in the option table.
When you're using these routines, specify them as follows*
1. Issue CALL ERRMON to make the error handling facilities
avai lable.
2. Issue CALL ERRSAV to make an entry accessible to your
program.
3. Issue CALL ERRSET to change the options in the entry (for
example, to change the number of errors allowed before
termi nati on) .
4. Issue CALL ERRSTR to store the changed entry back into the
option table.
142 VS FORTRAN Application Programming* Guide
When you're planning to use these routines, be sure to consult
your system administrator for options and values you can
specify.
When you're setting option table entries, don't allow more than
255 occurrences of any error; infinite program looping can
result.
The changes you make through these CALL routines are in effect
only during your own program's execution.
These routines ar& described in "Using The Execution-Time
Library."
For reference documentation about these predefined CALL
routines, see the VS FORTRAN Application Programming* Language
Reference manual.
Extended Error Handling — DOS/VSE considerations
jry
Under DOS/VSE, when you're using any of the extended error
handling routines, or any of the service routines, you must
identify the routine by its library module name through a linkage
editor INCLUDE statement. Names you can use are shown in
Figure 37.
VS FORTRAN VS FORTRAN
Source Name Library Name
ERRMON IFYVMOPT
ERRSAV IFYVMOPT
ERRSET IFYVMOPT
ERRSTR IFYVMOPT
ERRTRA IFYVMOPT
DVCHK IFYDVCHK
DUMP/PDUMP IFYVDUMP
CDUMP/CPDUMP IFYVDUMP
EXIT IFYVEXIT
OPSYS IFYOPSYS
OVERFL IFYVOVER
Figure 37. Library Names for DOS/VSE Error Handling and Service
Rout i nes
OBJECT MODULE LISTING — LIST OPTION
jgMfc
The object module listing is useful when you can't discover any
syntax errors in your VS FORTRAN source statements, and yet they
aren't doing what you expected. The object module listing shows
you (in pseudo-assembler format) the machine code the compiler
generated from your source statements. A careful examination of
this can often give you an idea of what's wrong with your source.
The object module listing is especially useful when you're
compiling and executing using one of the OPTIMIZE compiler
options. Further details are given in "Using the Optimization
Feature."
"You request an object module listing by specifying the LIST
option.
The object module listing is in pseudo-assembler language format
showing each assembler language instruction and data item, as
shown in Figure 38.
Fixing Execution-Time Errors — Advanced Programming 143
Each line of the listing is formatted (from left to right) as
follows?
• A 6-digit number shows the relative address of the
instruction or data item, in hexadecimal format.
• The next area gives the storage representation of the
instruction or initialized data item, in hexadecimal format.
• The next area (not always present) gives names and statement
labels, which may be either those appearing in the source
program or those generated by the compiler
(compiler-generated labels are in the form nn nnn nnnnnnn ) ♦
• The next area gives the pseudo-assembler language format for
each statement.
• The last area gives the source program items referred to by
the instruction, such as entry points of subprograms,
variable names, or other statement labels.
The object module listing contains sections in the following
orders
1 . Entry code
2. Format statements
3. Temporary storage for fix/float
4. Constants
5. Variables in COMMON areas
6. Other variables
7. Address constants for ASSIGNED FORMAT statements, COMMON
areas, and external references
8. NAMELIST dictionaries
9. Program code
10. Prolog and epilog code
11. Address constants for prologs, the save area, epilogs, and
parameter 1 i sts
12. Temporary storage areas and generated constants
13. Address constants for block labels
At the end of the listing, you'll find compiler statistics*
• The name of the source program
• The number of statements compiled
• The size of the generated object module (in bytes)
• The number of error messages, listed by severity, produced
during this compilation
if >y
J
i
J
144 VS FORTRAN Application Programming- Guide
ENTRY CODE
000000 47F0 F012 MAIN
000004 06
000005 D4C1C9D5404040
00000C F8F14BF1F1F2
000012 90EC DOOC
000016 9823 F028
00001A S030 D008
00001E 50D0 3004
000022 07F2
FORMAT STATEMENTS
000030 021A0CF1D6E4E3D7 111
000038 E4E340C6D6D94030
000040 000E060E0A0A070C
000048 0F0704020A14101C
000050 22
Figure 38 (Part 1 of 4). Object Module Listing Example — LIST Compiler Option
BC
15,18(0,15)
DC
XLl'06 f
DC
CL7 f MAIN •
DC
CL6 v 8i.ii2*
STM
14,12,12(13)
LM
2,3,40(15)
ST
3,8(13)
ST
13,4(0,3)
BCR
15,2
DC
CL8' 10UTP'
DC
CL8'UT FOR «
DC
CL8' •
DC
CL8 f •
DC
CL1' '
Fixing Execution-Time Errors — Advanced Programming 145
TEMPORARY FOR FIX/FLOAT
-
OOOOCO
OOOOOOOOOOOOOOOO
DC
XL8
OOOOOOOOOOOOOOOO'
OOOOC8
4EOOOOOOOOOOOO0O
DC
XL8'
4EOOO00OO000O00O'
CONSTANTS
0000D0
4F08000000000000
DC
XL8
4F08000000000000'
OOOOD8
4E00000080000000
DC
XL8
4E00000080000000'
OOOOEO
413243F6A791A9E1
PI
DC
XL8'
413243F6A791A9E1'
OOOOE8
4130000000000000
DC
XL8'
4130000000000000'
OOOOFO
00000000
DC
XL4
00000000'
OOOOFO
00000000
DC
XL4
00000000'
OOOOFO
00000000
DC
XL4
00000000'
OOOOF8
00000001
DC
XL4
00000001'
0O0OFC
OOOOOOOE
DC
XL4
OOOOOOOE'
OOOIOO
00000004
DC
XL4
00000004'
000104
00000007
DC
XL4
00000007'
000108
00000008
DC
XL4
00000008'
00010C
00000020
DC
XL4
00000020'
000110
00000080
DC
XL4
'00000080'
000114
OOOOOOAO
DC
XL4
OOOOOOAO'
000118
00000000
DC
XL4
00000000'
00011C
3E2DE00D
DC
XL4
3E2DE00D'
(REAL)
000120
3E89A027
DC
XL4
3E89A027'
(IMAG)
000124
00000019
DC
XL4
'00000019'
000128
00000006
DC
XL4
00000006'
VARIABLES IN
'C0M1 ' COMMON.
000000
NO INITIAL DATA
R4A
DS
11F
(ARRAY)
000004
NO INITIAL DATA
R8A
DS
7D
(ARRAY)
OOOOOC
NO INITIAL DATA
C32
DS
80D
(ARRAY)
00002C
NO INITIAL DATA
C8A
DS
F
(REAL)
000030
NO INITIAL DATA
DS
F
(IMAG)
VARIABLES IN
'COM2 ' COMMON.
FFFFF8
NO INITIAL DATA
12
DS
3F
(ARRAY)
000000
NO INITIAL DATA
LI
DS
X
000001
NO INITIAL DATA
C8B
DS
F
(REAL)
000005
NO INITIAL DATA
DS
F
(IMAG)
VARIABLES
000130
NO INITIAL DATA
R8V
DS
D
000138
NO INITIAL DATA
I
DS
F
00013C
NO INITIAL DATA
J
DS
F
000140
NO INITIAL DATA
Al
DS
F
000144
413243F4
A2
DC
XL4
413243F4'
000148
E2C8C1D9C540D7D9
CHAR14
DC
CL8
SHARE PR'
000150
D6C7D9C1D440
DC
CL6
OGRAM '
\J?'
ADCONS FOR ASSIGNED FORMAT STATEMENTS
000158 00000030
ADCONS FOR COMMONS
00015C 00000000
000160 FFFFFFFC
000164 FFFFFF6C
000168 00000000
00016C FFFFFFF4
ADCONS FOR EXTERNAL REFERENCES
000170 00000000
000174 00000000
000178 00000000
DC
AL4'00000030
^jf/
DC
AL4'
00000000'
DC
AL4'
FFFFFFFC
DC
AL4'
FFFFFF6C
DC
AL4'
00000000'
DC
AL4'
FFFFFFF4*
DC
AL4
00000000'
DC
AL4
00000000'
DC
AL4'
00000000'
COM1
COM1
COM1
COM2
COM2
CXSUB (SUBR)
VSCOM* (SUBR)
VSERH# (SUBR)
Figure 38 (Part 2 of 4). Object Module Listing Example — LIST Compiler Option
146 VS FORTRAN Application Programming: Guide
PROGRAM CODE
0001CC
0001D0
0001D4
0001D8
0001DC
OOOIEO
0001E4
0001E8
OOOIEC
0001FO
0001F4
0001F8
OOOIFC
OOOIFE
000202
000206
00020A
00020C
000210
000214
000218
00021A
00021E
000220
000224
000228
00022C
000230
000234
000238
00023C
000240
000242
5800 D104
5000 D0E8
5870 D10C
6800 7010
6000 D12C
6800 D07C
01 000 00001
7800
6A00
6C00
7000
7900
5850
0785
7800
7900
5850
0785
5800
5000
5870
1B00
4300
1B55
5860
8705
5860
8960
6800
5870
6A06
6000
2B00
6000
DOFO
D12C
D094
DOEC
D0C4
D170
DOFO
D0C4
D170
D0A4
D0E4
D114
7000
D164
6000
D0E4
0003
DODC
D10C
7000
D12C
D134
01 000 00019
01 000 00020
02 001 00020
01 000 00022
L
0,260(0,13)
111
ST
0,232(0,13)
J
I
7,268(0,13}
LD
0,16(0,7)
R8A
STD
0,300(0,13)
.SOI
LD
0,124(0,13)
4F080000
00000000
LE
0,240(0,13)
A2
AD
0,300(0,13)
.SOI
MD
0,148(0,13)
4130. ..0
STE
0,236(0,13)
Al
CE
0,196(0,13)
L
5,368(0,13)
200
BCR
8,5
LE
0,240(0,13)
A2
CE
0,196(0,13)
L
5,368(0,13)
200
BCR
8,5
L
0,164(0,13)
1
ST
0,228(0,13)
I
L
7,276(0,13)
SR
0,0
IC
0,0(0,7)
LI
SR
5,5
L
6,356(0,13)
100
BXLE
0,5,0(6)
L
6,228(0,13)
I
SLL
6,3
LD
0,220(0,13)
R8V
L
7,268(0,13)
AD
0,0(6,7)
R8A
STD
0,200(0,13)
.SOI
SDR
0,0
STD
0,308(0,13)
.S03
0002D2 45E0 F004
0002D6 20000000
0002DA 00000128
0002DE 0000013C
0002E2 45E0 F008
0002E6 0A00D0F4
0002EA OOOOOOFC
0002EE 45E0 FOOC
0002F2 00000004
JD002F6 06000007
O002FA 45E0 F008
0002FE 0700D0EC
000302 45E0 FOOC
000306 OOOOOOOC
00030A OE000014
00030E 45E0 F010
000312 58F0 D120
000316 45E0 F038
00031A 07
00031B E3C8C540C5D5C4
000322 58F0 D120
000326 45E0 F034
00032A 05
00032B 40404040F0
300
BAL 14,4(0,15)
DC XL4'20000000'
DC XL4'00000128'
DC XL4'0000013C
BAL 14,8(0,15)
DC AL4'0A00D0F4'
DC AL4'000000FC»
BAL 14,12(0,15)
DC AL4'00000004»
DC XL4 f 06000007»
BAL 14,8(0,15)
DC AL4'0700D0EC
BAL' 14,12(0,15)
DC AL4 f 0000OO0C
DC XL4'0E000014*
BAL 14,16(0,15)
L 15,288(0,13)
BAL 14,56(0,15)
DC XL1'07'
DC XL7'E3C8C540C5D5C4»
L 15,288(0,13) VSCOM#
BAL 14,52(0,15)
DC XLl»05 f
DC XL5M0404040F0'
CHAR14
14
R8A
Al
C32
VSCOMft
Figure 38 (Part 3 of 4). Object Module Listing Example — LIST Compiler Option
Fixing Execution-Time Errors — Advanced Programming
147
EPILOGUE CODE
000330 58F0 D120
000334 45E0 F034
000328 05
000339 40404040F0
PROLOGUE CODE
000340 58F0 3120
000344 45E0 F040
000348 18D3
00034A 58F0 D150
00034E 07FF
ADCON FOR PROLOGUE
000028 00000340
ADCON FOR SAVE AREA
00002C 00000054
ADCON FOR EPILOGUE
000054 00000330
ADCONS FOR BRANCH TABLES
0000A0 000002C4
0000A4 00000312
ADCONS FOR PARAMETER LISTS
000OAC 00000130
0000B0 00000140
0000B4 800000EO
0000B8 80000124
TEMPORARIES AND GENERATED CONSTANTS
00017C
000180
000184
000188
00018C
000190
000194
000198
00019C
0001A0
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
ADCONS FOR B BLOCK LABELS
0001A4
0001A8
0001AC
0001B0
0001B4
0001B8
0001BC
0001C0
0001C4
0001C8
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
01CC
01FE
020C
0214
0228
0292
02A8
02C4
02CE
0312
L 15,288(0,13)
BAL 14,52(0,15)
DC CL1' •
DC CL5 f f
L 15,288(0,3)
BAL 14,64(0,15)
LR 13,3
L 15,336(0,13)
BCR 15,15
DC XL4'00000340
DC XL4 f 00000054
DC XL4'00000330
VSCOMi
VSCOM#
Figure 38 (Part 4 of 4). Object Module Listing Example
DC
XL4'000002C4'
DC
XL4'00000312 f
DC
AL4 f 00000130 f
R8V
DC
AL4'00000140*
Al
DC
AL4'800000EO f
413243F6
A791A9E1
DC
AL4 , 80000124»
25
DC
XL4 T 00000000 f
DC
XL4 f 00000000»
DC
XL4»00000000'
DC
XL4'00000000»
DC
XL4'00000000»
DC
XL4'00000000'
DC
XL4'00000000 T
DC
XL4 , 00000000'
DC
XL4»00000000'
DC
XL4 , 0OOO0000 f
DC
XL4 , 000001CC I
DC
XL4»000001FE f
DC
XL4 f 0000020C»
DC
XL4 , 00000214 f
DC
XL4 t 00000228'
DC
XL4 , 00000292»
DC
XL4 f 000002A8»
DC
XL4 , 000002C4»
DC
XL4*000002CE f
DC
XL4 f 00000312»
ample-
—LIST Cotnpi ler
Opti on
^y'
O-
148 VS FORTRAN Application Programming? Guide
REQUESTING DUMPS
You can request dynamic dumps of specific areas of storage during
program execution, using the FORTRAN dump subprograms.
REQUESTING DYNAMIC DUMPS — CALL STATEMENT
Four VS FORTRAN predefined CALL routines let you request a
dynamic dump of selected areas of storage during program
execution:
• CALL PDUMP — dumps the requested areas and allocs processing
to continue
• CALL DUMP — dumps the requested areas and terminates
processing
• CALL CPDUMP — dumps the requested character storage areas and
allows processing to continue
• CALL CDUMP — dumps the requested character storage areas and
terminates processing
When you use the DUMP and PDUMP subprograms, you specify as
parameters*
• The variables delimiting the area to be dumped
• A code specifying the format in which the items are to be
dumped
For example, if you wanted to dump one item and continue
processing, you could specify!
CALL PDUMP (A, A, 5)
which would dump the variable A in real format (the code 5
specifies real format).
You can also dump an entire range of items in storage*
CALL DUMP (A,M,0)
which would dump every item in storage, beginning with variable A
and continuing through variable M, in hexadecimal format (the
code specifies hexadecimal format). Processing would then be
termi nated.
When you're using CDUMP and CPDUMP, the output is always in
character format. Therefore, you specify only the del imi ting
variables in the CALL statement. For example, to dump a range of
character variables from character variable CI to character
variable C19, specify*
CALL CDUMP (C1,C19) (and execution terminates)
or
CALL CPDUMP (C1,C19) (and execution continues)
For reference documentation about these routines, see the VS
FORTRAN Application Programming* Language Reference manual.
Dynamic Dumps — DOS/VSE Considerations
Under DOS/VSE, when you're requesting a dynamic dump, you must
also specify its library name with a FORTRAN or a linkage editor
INCLUDE statement. Figure 37 gives the names to specify.
Fixing Execution-Time Errors — Advanced Programming 149
REQUESTING AN ABNORMAL TERMINATION DUMP
How you request an abnormal termination dump depends on the (T J
system you're using. ^-^
Information on interpreting dumps is found in the appropriate
debugging guide* as listed in the Preface.
Requesting a Duirp — OS/VS
Under 0S/VS1, program interrupts causing abnormal termination
produce a dump* called an indicative dump* which displays the
completion code and the contents of registers and system control
f i elds.
To display the contents of main storage as well* you must request
an abnormal termination (ABEND) dump by including a SYSUDUMP DD
statement in the a r,r> ro ni r i cite ^ob sts n . The following example
shows how the statement may be specified for IBM-supplied
cataloged procedures'
//GO. SYSUDUMP DD SYS0UT=A
To specify a dump under MVS* you should include a SYSUDUMP DD
statement.
Requesting a Du?rp — DOS/VSE
Under DOS/VSE* to request a dump you can specify '
// OPTION PARTDUMP
This provides a dump of the partition storage* the registers* and
the areas of the supervisor control blocks that relate to this
parti t i on.
( V
Q
150 VS FORTRAN Application Programming* Guide
PART 3 — FORTRAN SPECIAL FEATURES
This part gives you guidance information on using the following
VS FORTRAN special features*
"Programming Input and Output"
"Coding Calling and Called Programs"
"Using the Optimization Feature"
"Using The Execution-Time Library"
"Using VM/370-CMS with VS FORTRAN"
"Using 0S/VS2-TS0 with VS FORTRAN"
c
PROGRAMMING INPUT AND OUTPUT
This chapter describes how you use VS FORTRAN to create and
process the following types of files*
• Sequential files on unit record* magnetic tape, and direct
access devi ces
• Direct files on direct access devices
• VSAM files on direct access devices
• Internal files for data conversions to and from the
CHARACTER type
I IBM bXltNSION
• Sequential files using list-directed input/output
statements
• Asynchronous files for high-speed sequential input/output
END OF IBM EXTENSION •
USING VS FORTRAN INPUT/OUTPUT STATEMENTS
For each of these forms of input/output you can use the VS
FORTRAN input/output statements 5
FORMAT statement — specifies the structure of FORTRAN
records.
OPEN statement — connects a file to a FORTAN program.
WRITE statement — transmits a record to an external or
internal unit.
READ statement — retrieves a record from an external or
internal unit.
ENDFILE statement — writes an end-of-file record on an
external sequential file.
BACKSPACE statement — backspaces a sequential file one
record.
REMIND statement — positions the file so that the next READ
or WRITE statement processes the first record in the file.
CLOSE statement — disconnects a file from a FORTRAN program.
INQUIRE statement — requests information about a file.
IBM EXTENSION
WAIT statement — completes an asynchronous input/output
transmission.
END OF IBM EXTENSION
USING COMMON OPTIONS FOR INPUT/OUTPUT
For the OPEN, WRITE, READ, ENDFILE, BACKSPACE, and REWIND
statements, there are common options you can specify *•
;#">/
-^
o
152 VS FORTRAN Application Programming: Guide
vv/
/ j**. The UNIT Number
[ fl j which specifies the I/O unit number of the file to be
processed, which you code as an integer or as a variable
expression.
When you specify the UNIT number as a variable expression,
you can use one input/output statement to process more than
one file; that is, between one execution of the statement
and the next, you can change the value of the unit number
and thus change the external unit that the statement refers
to.
The I/O Status
which, after the input/operation is completed, gives you
the result:
Zero, if no error was detected
Positive, if an error was detected
Negative, at sequential end-of-file
If this is a VSAM file, the VSAM return and reason codes
An Error Routine
which you can use to specify special processing after an
error occurs during execution of the I/O statement.
This lets you code a special routine that's executed when an
error occurs. The routine can obtain information about the
last record processed.
^"™v
For example, the routine could close any other open files,
and display information useful in debugging, such as
accumulated totals or current values in selected data
i terns.
Other options are available with specific input/output
statements and with specific file processing techniques.
CONNECTING TO A FILE — OPEN STATEMENT
The OPEN statement connects your program to an external file.
It's required for direct files and VSAM files; for other files,
it's optional. When you specify it, it must be the first
input/output statement executed for the file.
The OPEN statement lets you specify special processing options
for the f i le.
In addition to the common processing options previously listed,
you can also optionally specify-*
The File Status
which lets you specify the file status of this file, as
follows'
NEW for a file that you're creating for the first
time
OLD . for a file that already exists
Programming Input and Output 153
SCRATCH for a temporary file to be be used during this job
and then erased at the end of the job /f^\
UNKNOWN for a file whose status is not currently known to
the program; it may or may not currently exist
The External Filename
lets you specify the name of the file you're connecting.
Depending upon the file's status* this option may or may not
be required. If the STATUS is*«
NEW the filename is optional
OLD the filename is optional
SCRATCH the filename must not be specified
UNKND54N the filename is Optional
For CMS, MVS, and VS1, the filename specified in the OPEN
statement is the DD name.
Example (CMS):
FILEDEF MYFILEl DISK SAMPLE DATA A
OPEN (UNIT=15, FILE='MYFILE1', ...)
Example (MVS,VS1):
//MYFILEl DD DSN=SAMPLE, . . .
OPEN (UNIT=15, FILE=»MYFILE1',...)
For DOS/VSE, the filename specified is contained in the
DLBL statement.
Example (DOS):
//DLBL MYFILEl
OPEN (UNIT=15, FILE='MYFILE1', ...)
The Access Method
which lets you specify the access method for this file:
SEQUENTIAL or DIRECT.
SEQUENTIAL files are always assumed; therefore for these
types of files, specifying the access option is not
required. However r specifying it is useful for
documentation.
For DIRECT files, you must specify the access method. A
direct file must always exist before it is opened. The OPEN
itself neither allocates the file nor initializes it with
skeleton records if the file is new.
How Blanks are Treated
lets you specify how blanks in numeric fields of an input
record are to be treated:
NULL blanks are ignored
ZERO any blanks that aren't leading blanks ar& treated
as zeros
V_-V
154 VS FORTRAN Application Programming: Guide
The Formatting
lets you specify whether this file is connected for
FORMATTED or for UNFORMATTED input/output.
The Record Length
lets you specify the logical record length of a direct file.
If you specify FORMATTED I/O, this length is the number of
characters (bytes) in the record;
If you specify UNFORMATTED I/O, the length is the number of
bytes in the record.
For example, if the record contains two character items,
each 10 characters long, and 2 double precision items, the
length of the record is 36 bytes:
10 bytes each (20 bytes total) for the two character
items
8 bytes each (16 bytes total) for the two double
preci si on i terns
Reference documentation for the OPEN statement is given in VS
FORTRAN Application Programming* Language Reference .
CREATING FILE RECORDS— WRITE STATEMENT
You can use the WRITE statement for two different purposes-
1. To transfer data items from internal storage to a record in
an external f i le
2. For internal files, to transfer a number of data items (each
of which may have a different data type) into one character
i tern
The form of WRITE statement you specify depends upon the access
you f re using. See the descriptions, later in this chapter, of
each type of access.
With the WRITE statement, you can specify any of the common
processing options previously described.
Reference documentation for the WRITE statement is given in the
VS FORTRAN Application Programming* Language Reference manual.
RETRIEVING FILE RECORDS — READ STATEMENT
You use the READ statement in two different ways'
1. To transfer a record from an external file to data items in
internal storage
2. For internal files, to transfer one character item into a
number of data items, each of which may have a different data
type
The form of READ statement you specify depends upon the access
you're using. See the descriptions, later in this chapter, of
each type of access.
With the READ statement, you can specify any of the common
processing options previously described.
Reference documentation for the READ statement is given in the VS
FORTRAN Application Programming: Language Reference manual.
Programming Input and Output 155
OBTAINING FILE INFORMATION— INQUIRE STATEMENT
You use the INQUIRE statement to gather information about an
external sequential or direct file, or about a particular
external unit. Your program can then take alternative actions,
depending upon the information provided.
The INQUIRE statement is never required in a program, and you can
execute it whether or not the file or unit is currently connected
with your program.
You can ask for information about either a file or a unit number;
and you can specify the I/O Status and Error Routine options,
previously described.
n addition, you can request the following information*
Whether or not the file or unit exists.
Whether or not the file or unit is connected.
Get the unit number of the file or unit.
Whether or not the file has a name.
The access to this file — sequential or direct.
If the file can be connected for sequential I/O.
If the file can be connected for direct I/O.
Whether the file is connected for formatted or for
unformatted I/O.
If you can connect the file for formatted I/O.
If you can connect the file for unformatted I/O.
The record length, if this is a direct access file.
The number of the next record in the file, if this is a
di rect .access file.
Whether input blanks are treated as zeros or as nulls.
eference documentation for the INQUIRE statement is given in
he VS FORTRAN Application Programming' Language Reference
manual .
\j^
DISCONNECTING A FILE— CLOSE STATEMENT
You use the CLOSE statement to break the connection between an
external file and a FORTRAN unit.
The CLOSE statement is never required, but it lets you specify
special processing when the connection is broken off.
In addition to the common processing options previously
described, you can also specify whether or not the file still .
exists (internally to the FORTRAN program) after the CLOSE
statement is executed.
If you don't explicitly specify that the file is to be deleted,
the file still exists after you've closed it. In this case, you
can subsequently open the file for updating or retrieval.
If you specify that the file is to be deleted, you can
subsequently open the file only for f i le creati on.
Note: The CLOSE statement does not override what you specify in
the job control statements for the file.
O
156 VS FORTRAN Application Programming. Guide
Reference documenteti on for the CLOSE statement is given in the
VS FORTRAN Application Programming? language Reference manual.
USING UNFORMATTED AND FORMATTED I/O
For sequential and direct files, you can specify either of two
forms of READ and WRITE statements- unformatted or formatted.
Unformatted I/O — lets you use a list of FORTRAN data items to
control the transfer of data; the length of the FORTRAN items in
storage controls the amount of data transferred.
Each unformatted READ or WRITE statement processes a record at a
time, transferring the data items without conversion. (This
means the transfer is quicker than when the program must convert
each item as it is processed.)
Formatted I/O — lets you control input/output by specifying the
format of the FORTRAN records and the form of data fields within
the records.
This form of I/O also lets you convert items from one type to
another during the data transfer. (The conversions cause the
data transfer to be slower than with unformatted input/output.)
In this form of input/output, you specify a FORMAT statement to
be used in conjunction with the READ and WRITE statements. The
FORMAT statement specifies the format of the FORTRAN
records — the receiving field in a WRITE statement and the
sending field in a READ statement.
FORMATTING FORTRAN RECORDS — FORMAT STATEMENT
When you're using formatted I/O, the FORMAT statement lets you
specify the format of the FORTRAN records in READ or WRITE
statements. You can place FORMAT statements anywhere between the
first and last statements in your program unit; you must specify
a statement label.
You can use the FORMAT statement with both external and internal
files.
When you use it for external files, you must ensure that the size
of the FORMAT record doesn't exceed the size of the input/output
medium; for example, if you're sending the record to a printer,
it must not be longer than the printer line length. See "Appendix
A. Device Information" for details on external devices.
Each field in the FORTRAN record is described with a FORMAT code
specifying the data type for the field. The order in which you
specify the codes is their order in the record. Some of the codes
available with VS FORTRAN are shown in Figure 39.
Programming Input and Output 157
FORMAT Code Meaning (O)/
Data Field codes
AM Character data field (optional length specification)
aAW Character data field (optional repeat count)
paEw.dEe Real data field (optional exponent (Ee))
alw.m Integer data field (with minimum number of digits to
be di splayed ( .m) )
IBM EXTENSION
3G»"»dEe Integer* real* or logical data field (optional
exponent (Ee) )
END OF IBM EXTENSION
rf~\ |
Edit Codes:
s End of format control* but only if I/O list is
completely processed
/ End of record
BN Nonleading blanks in a numeric field are ignored on
i nput
BZ Blanks treated as zeros on input
S Specifies display of an optional plus sign
SP Specifies plus sign must be produced on output W
SS Specifies plus sign is not to be produced on output
TLr Data transfer starts r characters to left
TRr Data transfer starts r characters to right
The lower case letters have the following meanings*
a an optional repeat count
d number of decimal places to be carried
e number of digits in the exponent field
Ifl minimum number of digits to be displayed
p the number of digits for the scale factor
r a character displacement in a record
M the total number of characters in a field
Figure 39. Some Codes Used with the FORMAT Statement
Q)
158 VS FORTRAN Application Programming: Guide
c
For example, if you want to define the format of an output
record, you could specify your FORMAT statement as follows?
200 FORMAT (SP,2A10 , 16 .4 ,2E14 .5E2)
which specifies that the output line is to be formatted as
follows*
SP specifies that if the value of any of the numeric
fields is positive a plus sign is to be displayed. (If
the value is negative, a minus sign is always
displayed.)
2A10 specifies that the first and second items are
character items of length 10
16.4 specifies that the third item is an integer item of
total length 6, and that when the line is produced the
display is :
(blank)(+ or -)(4 digits)
2E14.5E2 specifies that the fourth and fifth items are real
items of total length 14; the display for each is shown
i n Fi gure 40 .
In this example, the minimum total width you can
specify for this field is 12 * one character for a
leading blank, seven characters for the numeric field
(including the leading sign and the decimal point),
and four characters for the exponent (including the E
and the si gn) .
In this example, the length of the record you've defined is 54
characters (bytes).
(3 blanks) ( si gn) (decimal point)(5 di gi ts) ( E) ( si gn) (2 digits)
I II I
Numeric Field Exponent
(The sign is displayed as a + or a -)
Figure 40. Display for FORMAT E14.5E2
A formatted WRITE statement uses the statement label for this
FORMAT statement and writes a record in this format.
When you execute a formatted READ statement, your program
expects the external data to be in this format.
Reference documentation for the FORMAT statement is given in the
VS FORTRAN Application Programming' Language Reference manual.
Group FORMAT Specifications
VS FORTRAN lets you specify group speci fi cat i ons nested within
the overall FORMAT specification, by specifying the group within
parentheses. The group can contain a combination of format codes
and groups, each separated by commas, slashes, or colons.
For example, you could specify an input record as follows*
100 FORMAT (BZ,A4,(A8,(I4,E8.4,(E4,E8.2X)))
which specifies that the input receiving fields are structured
as follows 2
Programming Input and Output 159
BZ specifies that blanks in the input are treated as zeros.
The first field in the record*
A4
is a character field of length 4 .
It is followed by a group field
(A8,(I4,E8.4,(E4,E8.2),),)—
consisting of a character field eight characters long
A8
followed by a group field
(I4,E8.4,(E4,E8.2),)
This nested group field contains yet another nested group
field:
(E4,E8.2)
In the VS FORTRAN FORMAT statement, the limit of two for nesting
group fields has been removed.
Using Specifications Repeatedly — FORMAT Control
Your FORMAT statements need not contain a format specification
for each field in the READ or WRITE I/O list. If the end of the
FORMAT speci f i cati on li st is reached before the last item in the
I/O list is processed, control is returned to the rightmost left
parenthesis in the format list; if there aren't any embedded
parentheses, then control is returned to the first item in the
format 1 i st :
10 FORMAT (A4, 2(12, 14), 3(14, 14), E4. 2)
(Control returns to 3(14,14)
You can take advantage of this VS FORTRAN feature to reduce your
coding effort, but be careful to ensure that the items repeated
ar& the items you want repeated.
Using One FORMAT Statement with Variable Formats
You can specify variable FORMAT statements, by placing a format
specification into an array during execution. You could read the
specification in from external storage, or you could initialize
the array using a DATA statement or an explicit specification
statement. You can then use the array as the format specification
in READ or WRITE statements.
Using this feature, you can r&fer to a different array element
each time you execute the READ or WRITE statement, and thus
change the format.
This is an efficient way to use one READ or WRITE statement to
process a file that contains records in many different formats.
This feature (together with a variable unit number) lets you use
a single READ or WRITE statement to process more than one file.
W
160 VS FORTRAN Application Programming: Guide
USING SEQUENTIAL FILES
Sequential files are those in which the records are arranged and
processed in a serial order. The records ar& arranged in the file
in the same order they were created. They can be retrieved only
in that same order.
You can store sequential files on unit record* magnetic tape* or
direct access devices.
If you concatenate sequential files with differing record
lengths, make certain that the first file is the one with the
longer record length. If you don't, the record lengths of the
files are not compatible.
SOURCE PROGRAM CONSIDERATIONS
The FORTRAN statements you can use with sequential file
processing are the OPEN, WRITE, READ, ENDFILE, BACKSPACE,
REWIND, and CLOSE statements.
Using the OPEN statement — Sequential Files
It's never necessary to specify an OPEN statement with
sequential files, unless the file is a VSAM sequential file.
However, the OPEN statement lets you take advantage of the
special processing it makes available. You can, for example,
specify the status of the file — NEW, OLD, SCRATCH, or UNKNOWN —
as well as specifying special processing to be performed if the
OPEN statement fails.
If your OPEN statement doesn't specify the formatting, FORMATTED
i s assumed.
If you don't specify an OPEN statement, the first READ statement
for the file establishes the file connection.
See "Using Common Options For Input/Output" and "Connecting to
a File — OPEN Statement" for descriptions $f the options you can
use.
Using the WRITE Statement — Sequential Files
C
You can use either an unformatted or formatted WRITE statement
with a sequential file; for example:
Unformatted:
WRITE (UNIT=10,ERR=300,IOSTAT=INT)A,E,I,0,U
or
WRITE (10,ERR=300,IOSTAT=INT) A,E,I,0,U
Formatted:
WRITE (UNIT=10,FMT=40,ERR=300,IOSTAT=INT) A,E,I,0,U
WRITE (10,40,ERR=300,IOSTAT=INT)A,E,I,0,U
where, in this example*
10 is the unit number of the external file.
40 is the statement label of the FORMAT statement (used
only with the formatted WRITE statement).
300 is the statement label of the FORTRAN statement to
which control is to be transferred if an error
occurs.
Programming Input and Output 161
INT is the name of an integer variable or an array element
into which is placed a positive or zero value
indicating failure or success of the WRITE operation.
A*E*I*0>U are the names of variables* arrays* array elements*
character substrings* or implied DO lists to be
included in the output record.
Mi thin main storage* these items need not be
contiguous.
See "Using Common Options For Input/Output" for a description of
the options you can use.
Using the read statement — Sequential Files
You can use either an unformatted or a formatted READ statement
with a sequential file; for example*
Unformatted:
READ (UNIT=11*ERR=300,IOSTAT=INT,END=200) A,E*I*0,U
or
READ U1*ERR=300*IOSTAT=INT*END=200) A,E,I*0,U
Formatted:
READ (U,FMT=40*ERR = 300,IOSTAT = INT*END=200> A*E*I,0,U
or
READ Ul*<rO*ERR = 300,IOSTAT = INT*END=200) A*E*I,0*U
where* in this example*
11 is the unit number of the external file.
40 is the statement label of the FORMAT statement (used
only with the formatted READ statement)
300 is the statement label of the FORTRAN statement to
which control is to be transferred if an error occurs
INT is the name of an integer variable or array element
into which is placed a positive or zero value*
indicating failure or success of the READ operation
200 is the statement label of the FORTRAN statement to
which control is transferred when end-of-file is
reached.
A*E*I f 0*U are the names of variables* arrays* array elements*
character substrings* or implied DO lists into which
the input record is transferred.
Mi thin main storage* these items need not be
contiguous.
See "Using Common Options For Input/Output" for a description of
the options you can use.
For an unformatted READ statement*
If an external record contains more data than the items in
the list* the excess external data is skipped.
If an external record contains less data than the items in
the list* an error occurs and processing continues.
'''^y
O
162 VS FORTRAN Application Programming* Guide
Using the ENDFILE Statement— sequential Files
You can use the ENDFILE statement to write an end-of-file record
on an external file. The file must be connected when you issue
the statement.
You can use the ENDFILE statement when you need to write an
end-of-file record for an output file. For example, the
following ENDFILE statement 2
ENDFILE (UNIT=10,IOSTAT=INT,ERR=300)
or
ENDFILE (10,IOSTAT=INT,ERR=300)
performs the following actions*
• Writes an end-of-file record on unit number 10.
• Returns a positive or zero value in INT to indicate failure
or success.
• Transfers control to statement label 300 if an error occurs.
Using the rewind Statement — Sequential Files
You use the REWIND statement to reposition a sequentially
accessed file at its beginning point. The file must be connected
when you execute the statement.
For example, the following REWIND statement*
REWIND (UNIT=11,IOSTAT=INT,ERR=300)
or
REWIND (11,IOSTAT=INT,ERR=300)
performs the f ollowi ng acti ons*
• Positions the file on unit number 11 to its beginning point.
• Returns a positive or zero value in INT to indicate failure
or success.
• Transfers control to statement label 300 if an error occurs.
Using the BACKSPACE statement— sequential Files
O
You use the BACKSPACE statement to reposition a sequentially
accessed file to the beginning of the record last processed. The
file must be connected when you execute the statement .
Before your program issues a BACKSPACE statement, it must issue a
READ, WRITE, or REWIND statement, or the BACKSPACE statement is
i gnored.
You can use the BACKSPACE statement to check the accuracy of
records your program writes on a magnetic tape file or sequential
direct access file*
WRITE ... (writes the record to the file)
BACKSPACE ... (positions the file at the beginning
of the record just written)
READ ... (retrieves the record for checking)
You can use the BACKSPAC.E statement to replace a record in a
magnetic tape file or a sequential direct access file*
Programming Input and Output 163
READ ... (retrieves the record to be replaced)
BACKSPACE (positions the file at the beginning
of the record just retrieved) ,/T^
WRITE ... (writes the new record)
After execution of this WRITE, no records exist in the file
following this record. Any records that did exist are lost.
You can use the I/O common processing options with the BACKSPACE
statement. For example, the following BACKSPACE statements
BACKSPACE (UNIT=10,IOSTAT=INT,ERR=300)
or
BACKSPACE (10,IOSTAT=INT,ERR=300)
performs the following actions*
• Positions the file on unit number 10 at the beginning of the
record last read or written.
• Returns a positive or zero value in INT to indicate failure
or success.
• Transfers control to statement label 300 if an error occurs.
Using the CLOSE statement — Sequential Files
USING ASYNCHRONOUS INPUT/OUTPUT
Asynchronous input/output statements let you transfer
unformatted data quickly between external sequential files and
arrays in your FORTRAN program, and, while the data transfer is
taking place, continue other processing within your FORTRAN
program.
Because the processing overlaps, you must have a method to
ensure that your program doesn't make references to the data
until the data transfer is complete.
The asynchronous input/output statements have special features
to achi eve thi s*
• The WAIT statement — to ensure that data transmission is
complete before your program begins processing the data
• A unique identifier to identify a particular READ, WRITE,
or WAIT statement — and to connect it with other related
asynchronous statements
Using the Asynchronous URITE Statement
To create an asynchronous input/output fi le, you use a special
form of the WRITE statement*
%*J*
You use the CLOSE statement to terminate the connection between
the external file and the unit.
For sequential files, the CLOSE statement is optional; however,
you can use it to specify specific processing actions when you
disconnect from the external file.
See the previous description of the CLOSE statement, in "Using VS y^,
FORTRAN Input/Output Statements," for a description of the
options you can specify.
I IBM EXTENSION ,
,J
164 VS FORTRAN Application Programming* Guide
To Transfer an Entire Array:
WRITE (10,tD=6) ARAY1
To Transfer Part of an Array:
WRITE (10,ID=6) ARAY1(2,2)...ARAY1(5,6">
WRITE (10,ID=6) ARAYK2.2)...
where, in this example'
10 is the unit number for the asynchronous file.
ID=6 is a unique identifier for this WRITE statement,
used in the WAIT statement.
ARAYl is an array whose contents are to be transferred.
In the first WRITE statement* the contents of the
entire array are transferred.
In the second WRITE statement, the contents of
ARAY1(2,2) through ARAY1(5,6) are transferred.
In the third WRITE statement, the contents of
ARAY1(2,2) through the end of ARAYl are transferred.
Using the Asynchronous READ Statement
C
To retrieve an asynchronous input/output file, you use a
special form of the READ statement*
To Transfer an Entire Array:
READ (10,ID=6) ARAYl
To Transfer Part of an Array:
READ (10,ID=6) ARAY1(2,2). ..ARAY1(5,6)
READ (10,ID=6) ARAY1(2,2)...
where, in this example 1
10 is the unit number for the asynchronous file.
ID=S is a unique identifier for this READ statement, used
in the WAIT statement.
ARAYl is an array whose contents are to be transferred.
In the first READ statement, the contents of the
entire array are transferred.
In the second READ statement, the contents of
ARAY1(2,2) through ARAY1(5,6) are transferred.
In the third READ statement, the contents of
ARAY1(2,2) through the end of ARAYl are transferred.
Using the Asynchronous WAIT Statement
After you've executed en asynchronous WRITE or READ statement,
you must ensure that the I/O operation is complete before you
make any further program references to the array being
processed. The WAIT statement tells the program to suspend
operations until the data transfer is complete; that is, it
synchronizes the WRITE or READ statement with the rest of the
program.
Programming Input and Output 165
For example, you can use the following WAIT statement with the
previously described READ or WRITE statements*
WAIT (10,ID=6) ARAY1
or
WAIT (10,ID=6) ARAY1(2,2)...ARAY1(5,6)
where, in this example*
10 is the unit number for the asynchronous file.
ID=6 is a unique identifier for this WAIT statement; it
ties this WAIT statement to the READ or WRITE
statement with the same identifier (the operation
the program is marking time for).
ADAV1
a ►» r»a»,
In the first WAIT statement, the data transfer for
the entire array is being synchronized.
In the second WAIT statement, the data transfer for
array elements ARAY1(2,2) through ARAY1(5,6) is
being synchronized.
END OF IBM EXTENSION
USING LIST-DIRECTED INPUT/OUTPUT
Input Data — List-Directed I/O
You enter list-directed input data as a series of FORTRAN
constants and separators*
• Each constant can be any valid FORTRAN constant. (Enter
character constants within apostrophes.)
Each constant you specify must agree with its corresponding
item in the data list.
You can sign numeric constants, but the sign must
immediately precede the first digit of the data (no
intervening blanks).
• You can specify a repetition factor for any constant or null
item. For example*
1>
List-directed input/output statements — READ and WRITE — simplify
your data entry for sequential files. They let you use formatted
input/output — that is, input/output statements that perform data
conversions as the data is transferred between internal and _.
external storage — without the restrictions of a FORMAT f \
statement. You can enter the data to be transferred without Vj^
regard for column, line, or card boundaries.
In addition, there's no need for you to define the file through
job control statements or CMS FILEDEF commands, because
list-directed input/output uses the standard system data sets or
logical units.
This makes list-directed READ and WRITE statements particularly
useful for terminal input and output, and for developing program
test data.
For VM/370-CMS considerations, see "Using VM/370-CMS with VS
FORTRAN."
For 05/VS2-TS0 considerations, see "Using 0S/VS2-TS0 with VS
FORTRAN."
o
166 VS FORTRAN Application Programming* Guide
3*2.6
specifies that the real constant 2.6 is to appear three times
in the data input stream.
Each separator can be:
— one or more blanks
— a comma
— a line advance (for terminal input)
— an end of card (on card devices)
— a slash (/) (See the following paragraph)
A combination of more than one separator* except for the
comma, represents one separator.
A slash (/) separator indicates that no more data is to be
transferred during this READ operation:
— Any items following the slash are not retrieved during
this READ operation.
— If all the items in the list have been filled* the slash
i s not needed.
— If there are fewer items in the record than in the data
list* and you haven't ended the list with a slash
separator* an error is detected.
— If there are more items in the record than in the data
list* the excess items are ignored.
A null item is represented by two successive commas.
o
List-Directed read statement
The list-directed READ statement retrieves a record from an
input file, with conversions to internal forms of data:
READ (FMT=*,UNIT=5,I0STAT=INT1) A*E*I,0*U
This READ statement specifies:
FMT=*
specifies that this is a list-directed READ statement.
UNIT=5
specifies that 5 is the unit from which the data i s to be
retrieved.
I0STAT=INT1
defines INT1 as the FORTRAN integer variable into which
information about the last operation is placed; by testing
INT1 you can specify special programming actions for
special conditions.
INT1 contains a positive value when an error occurs.
INT1 contains a negative value at end-of-file.
INT1 contains a zero value when neither condition occurs.
A,E,X,0,U
are the data items in which you want the data placed.
When the READ statement is executed* the data placed in A*
E* 0* and U is converted to REAL data of length 4* the data
placed in I is converted to INTEGER data of length 4.
Programming Input end Output 167
List-Directed WRITE Statement
The list-directed WRITE statement writes a record on an output f\
file, with conversions from internal forms of data* W
WRITE (UNIT=6,I0STAT=INT1,FMT=X) A,E,I,0,U
This WRITE statement specif i ess
UNIT=6
specifies that 6 is the unit on which the data i s to be
written.
I0STAT=INT1
defines INT1 as the FORTRAN integer variable into which
information about the last operation is placed; by testing
INT1 you can specify special programming actions for
special conditions.
INT1 contains a positive value when an err'or occurs.
INT1 contains a negative value at end-of-file.
INT1 contains a zero value when neither condition occurs.
FMT=X
specifies that this is a list-directed WRITE statement
A,E,I,0,U
are the source data items for the data transfer.
When the WRITE statement is executed, the data is converted from
the internal formats to external EBCDIC format.
USING INTERNAL FILES
Internal files let you move data from one internal storage area \^
to another while converting it from one format to another . This
gives you a convenient and standard method of making sum
conversi ons.
If your external file is coded in EBCDIC character date, you can
execute an unformatted READ statement to bring it into a
character item (VAR1) in storage*
For sequential Files:
READ (UNIT=11,ERR=300,IOSTAT=INT,END=200) VAR1
or
For Direct Files:
READ <UNIT=11,REC=KEY,ERR=300,IOSTAT=INT,FND=200) VAR1
You can now execute a formatted internal READ statement to
convert individual items in the record from EBCDIC to their
internal formats.
For internal READ and WRITE statements, you specify the UNIT
identifier as an internal data item — a character variable or
substring, or as a character array or array element.
For reference documentation about the internal READ and WRITE
statements, see the VS FORTRAN Application Programming? Language
Reference manual.
o J
168 VS FORTRAN Application Programming* Guide
Using the READ Statement — Internal Files
€
A READ statement referring to an internal unit converts the data
from character format to the internal format (s) of the receiving
i tem( s) -
READ (UNIT=VAR1,FMT=40,ERR=300,IOSTAT=INT,END=200) A,E,I,0,U
or
READ (VAR1,40,ERR=300,IOSTAT=INT,END=200) A,E,I,0,U
where, in this example?
VAR1 is a character variable in this program unit. (It
could also be a character array or array element, or a
character substring.)
40 is the statement label of the FORMAT statement.
300 is the statement label of the FORTRAN statement to
which control i s to be transferred if an error occurs.
INT is the name of an integer variable or array element
into which is placed a positive or zero value,
indicating failure or success of the READ operation.
200 is the statement label of the FORTRAN statement to
which control is transferred when the end of the
storage area is reached.
A,E,I,0,U are the names of variables, arrays, array elements,
character substrings, or implied DO lists into which
the input record is transferred.
Within main storage, these items need not be
contiguous.
Using the WRITE statement — internal Files
A WRITE statement referring to an internal unit converts the data
transferred from internal format to character format '
WRITE (UNIT=VAR1,FMT=40,ERR=300,IOSTAT=INT) A,E,I,0,U
or
WRITE (VARl,4O,ERR=300,IOSTAT=INT)A,E,I,O,U
where, in this example*
VAR1 is a character variable in this program unit. (It
could also be a character array or array element, or
character substri ng. )
40 is the statement label of the FORMAT statement.
300 is the statement label of the FORTRAN statement to
which control is to be transferred if en error occurs.
INT is the name of an integer variable or array element
into which is placed a positive or zero value
indicating failure or success of the WRITE operation.
A,E,I,0,U are the names of variables, arrays, array elements,
character substrings, or implied DO lists to be
i ncluded in VAR1 .
Programming Input and Output 169
Within main storage, these items need not be
contiguous.
/f~V
SYSTEM CONSIDERATIONS — SEQUENTIAL FILES
Each sequential file you use must be defined to the system*
through job control statements. The statements you use vary,
depending upon the system you're executing undei OS/VS,
DOS/VSE, or VM/370-CMS.
For VM/370-CMS considerations, see "Using VM/370-CMS with VS
FORTRAN."
For 0S/VS2-TS0 considerations, see "Using 0S/VS2-TS0 with VS
FORTRAN."
For reference documentation about job control statements, see
the VS FORTRAN Application Programming- System Services
Reference Supplement .
OS/vs considerations — Sequential Files
To define each file to the system, you specify a DD statement;
see "Defining Files — OS/VS DD Statement" in Part 2 for details,
The data sets you can specify and the ddnames you can use for
them are shown in Figure 29 in Part 2.
DOS/VSE Considerations — Sequential Files
USING DIRECT FILES
To define each file to the system, you optionally specify an
ASSGN statement; if it is a file on a direct access device, you
must also specify a DLBL and an EXTENT statement. See "Defining
Files— DOS/VSE ASSGN Statement" in Part 2 for details.
The logical units you can specify and the names you can use for
them are shown in Figure 30 in Part 2.
Direct files &re those in which all the records are arranged in
the file according to the relative addresses of their keys. Each
record is the same size, and each occupies a predefined position
in the file, depending upon its relative record number.
In a direct file, the first record has relative record number 1,
the tenth record has relative record number 10, the fiftieth
record has relati ve record number 50. You can think of the file
as a series of slots, each of which may or may not actually
contain a record. That is, record 50 may hold an actual record,
and be identified as record number 50, evert""though records 24,
38, and 42 are vacant slots.
You can process the records by supplying the relative record
number of the record you want with each READ or WRITE statement.
In order to do this, you'd ordinarily develop an algorithm that
lets you identify each record uniquely and that converts to a
relative record number for record creation and retrieval.
For a discussion of randomizing techniques useful in developing
such algorithms, see the Introduction to IBM Direct Access
Storage Devices and Organization Methods .
You can store direct files only upon direct access devices.
\_-j? !
\J'
170 VS FORTRAN Application Programming: Guide
(C:
SOURCE PROGRAM CONSIDERATIONS
J The FORTRAN statements you can use to process direct files Br&
the OPEN, WRITE, READ, and CLOSE statements.
Using the OPEN statemant — Direct Flies
You must specify an OPEN statement with a direct file; you must
specify the following options*
ACCESS — to specify the file as direct
RECL — to specify record length
The record length you specify when you create the file is the
record length you must specify when you retrieve records from the
file.
If you don't specify the formatting, UNFORMATTED is assumed.
See "Using Common Options For Input/Output" and "Connecting to a
File — OPEN Statement" for descriptions of other options you can
use.
Using the WRITE statement — Direct Files
You can use either an unformatted or formatted WRITE statement
with a direct file? for example 1
Unformatted:
WRITE (UNIT=15,REC=KEY,ERR=300,IOSTAT=INT)A,E,I,O,U
or
WRITE (15,REC=KEY,ERR=300,IOSTAT=INT) A,E,I,0,U
Formatted:
WRITE CUNIT=15,FMT=40,REC=KEY,ERR=300,IOSTAT=INT) A,E,I,0,U
or
WRITE <15,40,REC=KEY,ERR=30 0,IOSTAT=INT)A,E,I,O,U
where, in this examples
15 is the unit number of the external file. It must
identify a direct file.
40 is the statement label of the FORMAT statement (used
only with the formatted WRITE statement).
KEY Is an integer variable into which you place the
relative record number for the record you're writing.
You can specify the variable as an integer item of
length 4.
IBM EXTENSION
You can also specify the variable as an integer item
of length 2.
END OF IBM EXTENSION
300 is the statement label of the FORTRAN statement to
which control i s to be transferred if an error occurs.
Programming Input and Output 171
INT is the name of an integer variable or array element
into which is placed a positive or a zero value
indicating failure or success of the WRITE operation
A>E»X»0>U are the names of variables, arrays t array elements,
character substrings, or implied DO lists to be
included in the output record.
Within main storage, these items need not be
contiguous.
Using the READ statement — Direct Files
You can use either an unformatted or a formatted READ statement
with a direct file, for example:
Unformatted:
READ CUNIT=ii,REC-KEY,ERR-300,I05TAT=INT} A,E,I,G,u
or
READ (11,REC=KEY,ERR=300,IOSTAT=INT> A,E,I,0,U
Formatted:
READ (UNIT=11,FMT=40,REC=KEY,ERR=300,IOSTAT=INT) A,E,I,0,U
or
READ (11,<iO,REC=KEY,ERR=300,IOSTAT = INT) A,E,I,0,U
where, in this example?
H is the unit number of the external file. It must ^"-^
identify a direct file. L /
40 is the statement label of the FORMAT statement (used
only with the formatted READ statement).
KEY is an integer variable into which you place the
relative record number of the record you want to
retri eve.
You can specify the variable as an integer item of
length 4.
IBM EXTENSION
You can also specify the variable as an integer item
of length 2.
END OF IBM EXTENSION
300 is the statement label of the FORTRAN statement to
which control i s to be transferred if an error occurs.
INT is the name of an integer variable or array element
into which is placed a positive or a zero value,
indicating failure or success of the READ operation.
A,E,I,0,U are the names of variables, arrays, array elements,
character substrings, or implied DO lists into which
the input record is transferred.
Within main storage, these items need not be
contiguous.
c
y
172 VS FORTRAN Application Programming: Guide
For an unformatted READ statement!
If an external record contains more data than the items in
the list, the excess external data is skipped.
If an external record contains less data than the items in
the list, an error occurs and processing continues.
Using the CLOSE statement — Direct Files
You use the CLOSE statement to terminate the connection between
the external file and the unit. The CLOSE statement is never
required for direct files; however, you can use it to specify
special processing to occur when you disconnect from the
external f i le.
See the previous description of the CLOSE statement, in "Using VS
FORTRAN Input/Output Statements," for a description of the
options you can specify.
SYSTEM CONSIDERATIONS— DIRECT FILES
You must define each direct file to the system, through job
control statements.
The job control statements differ, depending upon the system
you're operating under — OS/VS, DOS/VSE, or VM/370-CMS.
For VM/370-CMS considerations, see "Using VM/370-CMS with VS
FORTRAN." •
For 0S/VS2-TS0 considerations, see "Using 0S/VS2-TS0 with VS
FORTRAN."
For reference documentation about job control statements, see
the VS FORTRAN Application Programming' System Services
Reference Supplement .
OS/vs Considerations — Direct Files
Before you can write records into the file, it must be
initialized with empty records. Your organization should have a
utility program to do this; check with your system
administrator.
To define each file to the system, you specify a DD statement; in
the DCB parameter, for a direct file, you must specify!
RECFM=F which specifies a fixed record size.
BLKSIZE=rl where rJL is the record length.
For example, if the record length is 80, you must
specify BLKSIZE=80.
The OPEN statement provides the default block size for the file,
unless you override it through the BLKSIZE parameter.
For other DD statement options you can specify, see "Defining
Files — OS/VS DD Statement" in Part 2.
The data sets you can specify and the ddnames you can use for
them are shown in Figure 29 in Part 2.
o
Programming Input and Output 173
D05/VSE Cons i derations — Direct Files
USING VSAM FILES
Before you can write records into the file* you must Preformat it
using the CLEAR disk utility. For documentation, see the DOS/VSE
System Utilities manual.
To define each file to the system, you optionally specify an
ASSGN statement.
You must specify a DLBL statement* using:
BLKSIZE to specify the block size.
The BLKSIZE. you specify must be the same size as the
record length you specify in the FORTRAN OPEN
statement.
You must also specify an EXTENT statement, which defines each
area the file occupies on the direct access device. See "Defining
Files — DOS/VSE ASSGN Statement" in Part 2 for details.
The logical units you can specify and the names you can use for
them are shown in Figure 30 in Part 2.
VS FORTRAN lets you use VSAM to process three kinds of files 1
• VSAM sequential files, using Entry Sequenced Data Sets
(ESDS), which can be processed only sequentially
• VSAM direct files, using Relative Record Data Sets (RRDS),
which can be processed either sequentially or directly
• Under DOS/VSE — you can also process VSAM-managed sequential
files (using the VSAM Space Management for SAM feature);
such files can be processed only sequentially
For documentation explaining VSAM Entry Sequenced Data Sets
(ESDS), Relative Rgcord Data Sets (RRDS), and DOS/VSE
VSAM-Managed SAM files, see the VSAM documentation for the
system you're running under. (VSAM publications titles are given
in the "Related Publications" section at the beginning of this
manual . )
Generally speaking, VSAM files are best used as permanent files,
that is, as files that are processed again and again by one or
more application programs. You shouldn't try to use VSAM files as
"scratch" files, because VSAM files are more difficult to
allocate and erase than other files. (For this reason, FORTRAN
doesn't let you use the NEW or SCRATCH options of the OPEN
statement, or the DELETE option of the CLOSE statement.)
The following general programming considerations apply to VSAM
files:
• Use VSAM sequential files (using ESDS) for applications in
which you create a complete file, one in which you'll never
update any records but to which you may add records in the
future.
• Use VSAM direct files (using RRDS) for work files, or for
files in which records must be created and later updated in
place.
• Under DOS/VSE, use VSAM-Managed SAM files to reduce the
amount of manual control needed to organize and maintain
your non-VSAM sequential files.
The next section, on Source Language, gives programming
considerations for each type of VSAM file.
174 VS FORTRAN Application Programming: Guide
SOURCE LANGUAGE CONSIDERATIONS — VSAM FILES
While a VSAM sequential file (ESDS) is similar to other
sequential files and a VSAM direct file (RRDS) is similar to
other direct files* their organizations are actually different
from other sequential and direct files, and the same source
language can give different results. You must take these
differences into account to get the results you expect.
When you're processing VSAM files, you can use all the VS FORTRAN
input/output statements.
However, the ENDFILE statement has no meaning for a VSAM file and
is treated as documentation. If your program contains an ENDFILE
statement and processes a VSAM file, you'll get a warning message
to inform you of this.
Figure 41 summarizes the FORTRAN input/output statements you can
use with each form of access.
f% ]
File Type
Access
VSAM
Sequent i al
(ESDS)
Sequential
OPEN
(sequential)
WRITE
READ
BACKSPACE
REWIND
CLOSE
VSAM Direct (RRDS)
Sequential
Empty
File:
OPEN
(sequential)
WRITE
BACKSPACE
(has effect
of CLOSE)
REWIND
(has effect
of CLOSE)
CLOSE
Nonempty
File:
OPEN
( sequenti al)
READ
BACKSPACE
REWIND
CLOSE
Di rect
OPEN
(di rect)
WRITE
(update or
replace)
READ
CLOSE
VSAM-
Managed
Sequenti al
Sequenti al
WRITE
READ
BACKSPACE
REWIND
ENDFILE
CLOSE
Figure 41. FORTRAN Statements Valid with VSAM Files
Programming Input and Output
175
In some instances* the VSAM input/output statements have a
different effect than they have for other file processing
techniques. The differences are documented in the following
sections.
Processing VSAM Sequential Files
VSAM sequential files use VSAM Entry Sequenced Data Sets (ESDS);
processing of such files can only be sequential.
When you're processing VSAM sequential files, there are special
considerations for the OPEN, CLOSE, READ, WRITE, BACKSPACE, and
REWIND statements, as described in the following paragraphs.
OPEN AND CLOSE STATEMENTS— "VSAM SEQUENTIAL FILES: When your
program processes a VSAM sequential file, you must specify the
OPEN statement. For VSAM sequential files, specify:
ACCESS=»SEQUENTIAL'
For VSAM files, the STATUS specifier of an OPEN statement may not
be NEW or SCRATCH, and the STATUS specifier of a CLOSE statement
may not be DELETE.
USING THE READ STATEMENT — VSAM SEQUENTIAL FILES: The READ
statement for a VSAM sequential file has the same effect it has
for other sequential files? records are retrieved in the order
they are placed in the fila. Therefore, you must use the
sequential forms of the READ statement.
USING THE WRITE STATEMENT— VSAM SEQUENTIAL FILES: For VSAM
sequential files, the WRITE statement places the records into
the file in the order that the program writes them. If a VSAM
sequential file is nonempty when your program opens it, a WRITE
statement always adds a record at the end of the existing records /"^y
in the file; thus you can extend the file without first reading \t^y
all the existing records in the file.
Once you've written a record into a VSAM sequential file, you can
only retrieve it; you cannot update it. Thus, when processing a
VSAM sequential file, you can't update records in place. That is,
if you code the following statements:
READ ...
BACKSPACE ...
WRITE . ...
the WRITE statement does not update the record you have just
retrieved. Instead, it places the updated record at the end of
the file. (If you want to update records, you should define the
VSAM file as direct. See the following section on "Processing
VSAM Direct Files".)
USING THE BACKSPACE STATEMENT — VSAM SEQUENTIAL FILES: For VSAM
sequential files, you can use the BACKSPACE statement to make the
last record processed the current record:
• For a READ statement followed by a BACKSPACE statement, the
current record is the record you've just retrieved. You can
then retrieve the same record again.
• For a WRITE statement followed by a BACKSPACE statement, the
current record is the record you've just written, that is,
the last record in the file. You can then retrieve the record
at thi s posi ti on.
USING THE REWIND STATEMENT — VSAM SEQUENTIAL FILES: The REWIND
statement for VSAM sequentially accessed files has the same
effect it has for other sequential files: the first record in the
file becomes the current record.
O'
176 VS FORTRAN Application Programming: Guide
For VSAM sequential files, this means that you can rewind the
*%, file and then process records for retrieval only. If you attempt
■jp to update the records, you'll simply add records at the end of
the file.
After a BACKSPACE or REWIND statement is executed, you cannot
update the current record. If you attempt it, you'll simply add
another record at the end of the file.
Processing VSAM Direct Files
VSAM direct files use VSAM Relative Record Data Sets (RRDS). You
can process VSAM direct files using either direct or sequential
access.
Using direct access, you supply the relative record number of the
record you want to process. You should use direct access when
there are gaps in the relative record sequence for the file, or
when you want to update records in place.
Using sequential access, you access each record in turn, one
after another, and you have no control over the relative record
number. For this reason, if you use sequential access to load the
file, there should be no gaps in the relative record number
sequence.
When you're processing VSAM direct files, there are special
considerations for the OPEN and CLOSE statements, and for
sequential and direct access, as described in the following
paragraphs.
USING OPEN AND CLOSE STATEMENTS — VSAM DIRECT FILES: When your
program processes a VSAM direct file, you must specify the OPEN
statement. The options you can use are:
♦ ACCESS='SEQUENTIAL' for sequential access
• ACCESS='DIRECT T for direct access
For VSAM files, the STATUS specifier of an OPEN statement may not
be NEW or SCRATCH, and the STATUS specifier of a CLOSE statement
may not be DELETE.
USING SEQUENTIAL ACCESS — VSAM DIRECT FILES: You can use
sequential access to load (place records into) an empty VSAM
direct file using the WRITE statement, or to retrieve records
from a VSAM direct file using the READ statement. The records are
processed sequentially, one after the other, exactly as a
sequential file is processed, and the relative record numbers of
the records are ignored. In other words, when you're loading the
file, there should not be any gaps in the relative record number
sequence, because space for any missing records will not be
reserved in the file.
For a direct file opened in the sequential access mode, you can
use the WRITE statement only to load (place records into) a file
that is empty when the file is opened. During loading,, if you
specify a BACKSPACE or REWIND statement, you cannot specify any
more WRITE statements.
If the sequentially accessed VSAM direct file already contains
one or more records when it is opened and you issue a WRITE
statement, your program is terminated. In other words, for a VSAM
direct file opened in the sequential access mode, once the file
is loaded, you can't add or update records with FORTRAN programs.
(For updating and adding records, you must use direct access.)
The READ statement for a sequentially accessed VSAM direct file,
retrieves the records in the order they are placed in the file.
The VS FORTRAN program gives you no way of determining the
relative record number of any particular record you retrieve.
Programming Input and Output 177
(If you need to use the relative record number, you must use
direct access.) y~>
Except during file loading, the REWIND statement for a ^-^
sequentially accessed VSAM direct file has the same effect it has
for VSAM sequential files' the first record in the file becomes
the current record, which is then available for retrieval.
During file loading, the REWIND statement has the same effect as
a CLOSE statement followed by an OPEN statement; the first record
in the file is then available for retrieval.
Except during file loading, the BACKSPACE statement for a
sequentially accessed VSAM file has the same effect it has for
VSAM sequential files; the last record processed becomes the
current record, which is then available for retrieval. During
file loading, the BACKSPACE statement has the same effect as a
CLOSE statement, followed by an OPEN statement, followed by file
positioning to the last record written; the last record in the
file is then available for retrieval,
USING DIRECT ACCESS— VSAM DIRECT FILES: You can use direct
access to place records into a VSAM direct file using the WRITE
statement, or to retrieve records from a VSAM direct file using
the READ statement.
For VSAM direct files, if the relative record numbers for the
file are not strictly sequential — that is, if there are .gaps in
the key sequence, for example*
1, 2, 3, 10, 12, 15, 16, 17, 20
— you must load (create records in) the file, using direct access
WRITE statements to provide the relative record number for each
record you write.
Otherwise (if the relative record numbers for the file are x ^
strictly sequential — no gaps), you should sort the records > J
according to the ascending order of their record numbers and then ^^
load them into the file using sequential access. This is because
sequential access is faster than direct access.
For a VSAM direct file opened in the direct access mode, a WRITE
statement uses the relative record number you supply to place a
new record into the file, or to update an existing record.
The method you follow, either for record insertion or record
update, is as follows*
1. In the OPEN statement, specify ACCESS= , DIRECT» for the file.
2. Set the REC variable to the relative record number of the
record to be inserted or updated.
3. Then code the WRITE statement, using the preset REC
variable.
4. Repeat steps 2 and 3 until you've processed all the records
you need to process.
When you are loading (initially placing records into) a file, you
must not use duplicate record numbers during processing. In
other words, you are not allowed to update records while you are
loading the file.
To retrieve records from a directly accessed VSAM direct file,
use the direct access forms of the READ statement. You cannot
open the same file in the same programming uni t for both
sequential and direct access processing.
Don't execute the BACKSPACE or REWIND statements with a directly
accessed VSAM direct file; if you do, your program is terminated.
178 VS FORTRAN Application Programming* Guide
Processing VSAM-Managed Sequential Files
You cannot use an OPEN statement with a VSAM-managed sequential
file.
For VSAM-managed sequential files, you can use all other
input/output statements valid for other non-VSAM sequential
files.
See the section "Using Sequential Files" on page 161.
Obtaining the VSAM Return Code— IOSTAT Option
VS FORTRAN uses the VSAM program to process all VSAM requests.
If you specify the IOSTAT option for VSAM input/output
statements, and an error occurs while VSAM is processing it,
you* 11 get the VSAM return code for the operation attempted in
the IOSTAT data item.
(If the error occurrs while FORTRAN is processing it, you'll get
an IOSTAT code of +1. )
The VSAM return code is formatted in the IOSTAT data item as
follows:
1. The VSAM return code is placed in the first two bytes.
2. The VSAM reason code is placed in the second two bytes.
• IBM EXTENSION
c
To inspect the codes, you can equivalence the IOSTAT variable
with two integer items, each of length 2. After a VSAM
input/output operation, you can then write out the two integer
items, which contain the pair of VSAM codes.
END OF IBM EXTENSION
The VSAM documentation for the system you're operating under
gives the meaning of these return and reason codes. See the list
of "Related Publications" at the beginning of this manual for
VSAM publications titles.
DEFINING A VSAM FILE
To define and use a VSAM file, you must first define a catalog
entry for the file, using Access Method Services commands. When
you execute the commands, you create a VSAM catalog entry for the
file.
You use Access Method Services to create a catalog entry for your
file. The form of the entry depends upon the kind of file you'll
be creating: a VSAM sequential file (ESDS), VSAM direct file
(RRDS), or a VSAM-managed sequential file.
For VSAM sequential and direct files, the following examples
assume that the data space your file is using has already been
defined as VSAM space by the system administrator.
For reference documentation about the DEFINE commands, see the
VS FORTRAN Application Programming: System Services Reference
Supplement .
Programming Input and Output 179
Defining a VSAM Sequential File
To define a VSAM sequential file (ESDS), you can specify* (f^*)
DEFINE CLUSTER
(NAMECMYFILE)
FILE(MYFILEl)
V0LUMESC666666)
NONINDEXED
RECORDSU80)
RECORDSIZEC80 200)
CATALOG(USERCAT))
which defines a file named MYFILE1 as a VSAM file.
NONINDEXED specifies that this is a VSAM sequential file (ESDS).
V0LUMES(666666 ) specifies that the file is contained on volume
666666.
REC0RDSC180) specifies that there can be a maximum of 180 records
in the space.
RECORDSIZE(80 200) specifies that the average length of the
records in the file is 80 bytes, and the maximum length of any
record is 200 bytes.
CATALOG(USERCAT) specifies the catalog in which this file is
entered.
To actually create the entry in the catalog, you must then use
job control statements to execute the DEFINE CLUSTER command.
Defining a VSAM Direct File
To define a VSAM direct file (RRDS), you can specify*
DEFINE CLUSTER
(NAME(MYFILE2)
FILECMYFILE3)
V0LUMESC666666)
NUMBERED
RECORDSC200)
RECORDSIZEC80 80)
CATALOG(USERCAT))
which defines a file named MYFILE3 as a VSAM file.
NUMBERED specifies that the file is a VSAM direct file (RRDS).
V0LUMES(666666) specifies that the file is contained on volume
666666.
RECORDSC200) specifies that there can be a maximum of 200 records
allowed in the space.
RECORDSIZE(80 80) specifies that all the records in the file are
80 bytes long.
CATALOG(USERCAT) specifies the catalog in which this file is
entered.
To actually create the entry in the catalog, you must then use
job control statements to execute the DEFINE CLUSTER command.
Vv
i>
180 VS FORTRAN Application Programming: Guide
Defining a DOS/VSE VSAM-Managed Sequential File
To define a DOS/VSE VSAM-managed sequential file (using the
DOS/VSE VSAM Space Management for SAM feature) , you can specify:
DEFINE CLUSTER
(NAME(MYFILE3)
NONINDEXED
RECORDFORMAT(VB120)
RECORDSIZEC500)
RECORDS(200)
V0LUMES(666666))
which defines a sequential file named MYFILE3, suballocated in
VSAM space.
RECORDFORMATCVB120) specifies that the file has variable blocked
format with average logical records 120 bytes long.
RECORDSIZEC500) specifies that there are four logical records in
each block; 120 bytes for each logical record, plus 4 bytes for
each record descriptor, plus 4 bytes for the block descriptor.
RECORDS(200) specifies that there can be a maximum of 200 records
in the space.
V0LUMES(666666) specifies that the file is contained on volume
666666.
To actually create the entry in the catalog, you must then use
job control statements to execute the DEFINE CLUSTER command.
PROCESSING DEFINE COMMANDS
Once you've created your DEFINE command, you must execute it,
using Access Method Services, to create an entry in a VSAM
catalog. The job control statements you use depend upon the
system you're operating under: VM/370-CMS, OS/VS, or DOS/VSE.
For VM/370-CMS considerations, see "Using VM/370-CMS with VS
FORTRAN."
For 0S/VS2-TS0 considerations, see "Using 0S/VS2-TS0 with VS
FORTRAN."
Processing DEFINE Commands — OS/VS
Under OS/VS, you specify the following job control statements to
catalog your VSAM DEFINE CLUSTER commands:
//VSAMJOB JOB
//STEP EXEC PGM=IDCAM5
//SYSPRINT DD SYS0UT=A
//MYFILE1 DD V0L=SER=MYV0L ,UNIT=SYSDA, DISP=OLD
//SYSIN DD *
(The DEFINE CLUSTER command as data)
/*
//
If the DEFINE command FILE name is MYFILE1, then this is the DD
name you specify in the DD control statement.
o
Programming Input and Output 181
Processing DEFINE Commands — DOS/VSE
Under DOS/VSE, you specify the following job control statements
to execute your DEFINE commands, both DEFINE CLUSTER and DEFINE
NONVSAM:
// JOB DEFINE
// DLBL MYFILE2
// EXTENT (as required)
// EXEC IDCAMS,SIZE=AUTO
(The DEFINE command as data)
/*
/*
If the DEFINE command FILE name is MYFILE2, then this is the file
name you specify in the DLBL control statement.
CREATING AND PROCESSING VSAM FILES
Once you've created a catalog entry for the file, you can
actually load the file (place records in it for the first time)
You can load and process the file using VS FORTRAN statements.
When you execute the FORTRAN program, you must define the file
using job control statements for the system you're using.
For reference documentation about job control statements, see
the VS FORTRAN Application Programming: System Services
Reference Supplement.
Creating and Processing VSAM Files — OS/VS
Under OS/VS, when you execute a FORTRAN program to create or
process a VSAM file, you define the file in a DD statement.
For example, to process MYFILE1 in a FORTRAN load module called
MYPROG, you specify:
//VSAM1 JOB
// EXEC PGM=MYPROG
//MYFILE1 DD DSN=MYFILE,DISP=SHR
//
When MYPROG is executed, the DD statement makes MYFILE1 (and the
information in its catalog entry) available to the program. In
the FORTRAN OPEN statement, MYFILE1 is the name you gse for the
FILE opti on.
Creating and Processing VSAM Files — DOS/VSE
Under DOS/VSE, when you execute a FORTRAN program to create or
retrieve records in a VSAM file, you define the file in DLBL and
EXTENT statements.
For example, to process MYFILE1 in a FORTRAN load module (phase)
called MYPROG, you specify:
// JOB VSAM1
// DLBL MYFILE1
// EXTENT SYS015,VSAMVOL
// EXEC MYPROG, SIZE=xxK
//
When MYPROG is executed, the DLBL and EXTENT statements make
MYFILE1 (and the information in its catalog entry) available to
the program.
\J'
©'
182 VS FORTRAN Application Programming: Guide
Jf'S.
In the EXTENT statement, you need specify only the logical unit
(SYS015) and the volume ID (VSAMVOL), which is the volume
containing the VSAM catalog.
In the FORTRAN OPEN statement, the unit you specify must be
equivalent to that specified in the EXTENT statement. Your
system administrator can tell you the units valid for your
organization.
For VSAM files, you must specify the SIZE parameter in the EXEC
statement. Do not specify a size larger than the size of the
partition the program will run in.
SYSTEM CONSIDERATIONS — INPUT/OUTPUT
For every file your program uses, you may need labels. Record
formats the system uses are also of importance. Both are
described in the f ollowi ng- sect i ons.
USING INPUT/OUTPUT LABELS
Files stored on magnetic tape devices can be labeled or
unlabeled. Files stored on direct access devices must have
labels. The labels are identifiers that help the system keep
track of the files current at any one time.
The tape and direct access files you create can have volume
labels, standard file labels, or user standard labels. The
format and use of magnetic tape and direct access labels are
different; therefore, the following sections discuss each
separately.
Magnetic Tape Labels
Magnetic tape labels can be volume labels, standard file labels,
or user standard labels.
VOLUME LABELS — TAPE FILES: Whenever you specify standard or user
labels in your program, the system also creates volume labels.
The first four characters identify the volume label.
Volume labels precede standard labels on the tape.
STANDARD FILE LABELS — TAPE FILES: When you specify standard
labels, the system creates standard file labels. The first three
characters specify if this is a header, end-of-volume, or
end-of-file label.
Standard file labels follow volume labels and precede user
standard labels (if any) on the tape.
USER STANDARD LABELS — TAPE FILES: The system uses the first four
characters to identify the label as a user header or trailer
label; you supply the contents of the remaining 76 characters.
Your user standard labels follow the standard file labels on the
tape.
When you specify user standard labels, you should also create an
assembler routine to process them.
PROCESSING MAGNETIC TAPE LABELS: Whenever you process a labeled
tape file, the system processes the labels:
When you're creating the file, the system creates labels for
it.
When you're retrieving the file, the system checks the
labels.
Programming Input and Output 183
The system processes volume and standard header labels when you
open the file. __ )
The system processes trailer labels when you close the file, or *\Jr
when the physical end of a reel is reached.
The system processes end-of-volume labels when an end-of-reel
indicator is reached.
The system processes end-of-file trailer labels when you close
the f i le.
OS/vs Tape Label Considerations
You specify magnetic tape labels through the LABEL parameter of
the DD statement; through this parameter, you can specify the
position of the file on the tape, the type of label, if the data
set is password protected, and the type of file processing
allowed.
Reference documentation for the DD statement is given in the VS
FORTRAN Application Programming? System Services Reference
Supplement .
For additional detail on magnetic tape label processing, see the
OS/VS Tape Labels manual.
DOS/VSE Tape Label considerations
You specify magnetic tape labels through the TLBL statement;
through this statement, you can specify the position of the file
on the tape, the generation and version number for this file, and
the expiration date.
Using the LBLTYP statement, when you're processing labeled tape ^^
files, you must also tell the linkage editor to reserve storage W
for label processing.
Reference documentation for the TLBL and LBLTYP statements is
given in the VS FORTRAN Application Programming* System Services
Reference Supplement .
For additional detail on magnetic tape label processing, see the
DOS/VSE Tape Labels manual .
Direct Access Device Labels
Volume Labels
The system uses direct access device labels to identify and
protect files stored on such devices. Files on direct access
devices must be labeled.
For each volume on a direct access device, there's always a
volume label. For each file on that volume, there's always a
standard file label. For each file, you can also specify and
process user standard labels.
Volume labels &re preceded by a 4-byte key field. The key field
and the first four bytes of the data field each contain the
volume identification.
STANDARD FILE LABELS: Standard file labels can be in one of the
following three formats*
• Sequential file format
• Direct file format
O y
184 VS FORTRAN Application Programming: Guide
f £m^ • DOS/VSE format for files using more than three extents on one
V m volume
■\^
USER STANDARD LABELS: User standard labels have the same format
as user standard labels for magnetic tape files.
If you specify user standard labels, you should provide an
assembler language subroutine to process them.
Processing Direct Access Device Labels
The system processes the volume and standard file labels when you
open and close the file.
OS/vs Direct Access Label Considerations
You specify direct access labels through the LABEL parameter of
the DD statement; through this parameter, you can specify the
position of the file on the volume, the type of label, if the
data set is password protected, and the type of file processing
allowed.
Reference documentation for the DD statement is given in the VS
FORTRAN Application Programming: System Services Reference
Supplement .
For additional detail on direct access label processing, see the
OS/VS Data Management Services Guide .
DOS/VSE Direct Access Label Considerations
You specify direct access labels through the DLBL statement?
through this statement, you can specify the identification of
the file on the volume, the type of data set label to be used
(sequential or direct), and the expiration date.
Reference documentation for the DLBL statement is given in the VS
FORTRAN Application Programming? System Services Reference
Supplement .
For additional detail on direct access label processing, see
DOS/VSE DASD Labels .
DEFINING FORTRAN RECORDS — SYSTEM CONSIDERATIONS
Your FORTRAN programs must define the characteristics of the
data records it will process* their formats, their record
length, their blocking, and the type of device upon which they
resi de.
For CMS considerations about record formats, see "Using
VM/370-CMS with VS FORTRAN."
Record Formats — OS/VS
Under VS FORTRAN, you can specify the format of the data records
as:
Fixed-Length Records
All the records in the file are the same size and each is
wholly contai ned within one block. Blocks can contain more
than one record, and there is usually a fixed number of
records in each block.
Variable-Length Records
The records.can be either fixed or variable in length. Each
record must be wholly contained within one block. Blocks
can contain more than one record.
Programming Input and Output 185
Each record contains a record-descriptor field, and each
block contains a block-descriptor field. These fields are
used by the system; they are not available to FORTRAN
programs.
Spanned Records
The records can be either fixed or variable in length and
each record can be larger than a block. If a record is
larger than the remaining space in a block, a segment of the
record is written to fill the block. The remainder of the
record is stored in the next block (or blocks, if required).
Only complete records are made available to FORTRAN
programs.
Each segment in a block, even if it is the entire record,
includes a segment-descriptor field, and each block
includes a block-descriptor field. These fields are used by
the system; they are not available to FORTRAN programs.
Undefined- Length Records
The records may be fixed or variable in length. There is
only one record per block. There are no record-length,
block-descriptor, or segment-descriptor fields.
SEQUENTIAL EBCDIC DATA SETS: You can define FORTRAN records in an
EBCDIC data set as formatted or unformatted, that is, they may or
may not be defined in a FORMAT statement. List-directed I/O
statements are considered formatted.
You can specify formatted records as fixed length, variable
length, or undefined length.
You can specify unformatted records only as variable length.
If you're processing records using asynchronous input/output,
the records must not be blocked.
Defining Records — OS/VS
Under OS/VS, you define data record characteristics through the
DCB parameter of the DD statement.
Through the DCB parameter, you can specify 1
• Record format— -fixed length, variable length, or undefined
Unformatted Records: Unformatted records are those not described ^~*
by a FORMAT statement. The size of each record is determined by
the input/output list of READ and WRITE statements.
Always specify unformatted records as variable and spanned.
In addition, they may be blocked or unblocked.
Use blocked records wherever possible; blocked records reduce
processing time substantially.
SEQUENTIAL ASCII DATA SETS: ASCII data sets may have sequential
organization only. For system considerations, see the
documentation for the system you're using.
FORTRAN records in an ASCII data set must be formatted and
unspanned and may be fixed length, undefined length, or variable
length records.
DIRECT-ACCESS DATA SETS: FORTRAN records may be formatted or
unformatted, but must be fixed in length and unblocked only.
The OPEN statement specifies the record length and buffer length
for a direct-access file. This provides the default value for the
block size.
186 VS FORTRAN Application Programming: Guide
Record length — either the exact length (fixed or undefined),
or the length of the longest record (variable)
Blocking information — such as the block size
Buffer information — the number of buffers -to be assigned
Whether the data set is encoded in the EBCDIC or the ASCII
character set
Special information for tape files
Special information for direct access files
Information to be used from another data set
For reference documentation on the DCB parameter, see the VS
FORTRAN Application Programming* System Services Reference
Supplement .
Record Formats — dos/vse
The DOS/VSE system keeps control information about your data
files in an internal DTF table. There is a DTF table for each
logical unit, including the system logical units, that your
program uses — except for SYSLOG.
The system builds the DTF tables dynamically as each logical unit
is opened for the first time, using information it obtains from
your program. Guidance information on the DTF tables is included
i n DOS/VSE Data Management Concepts and DOS/VSE Macro User's
Gui de ; reference information on the DTF tables is included in
DOS/VSE Macro Reference .
DOS/VSE FORTRAN produces and accepts records that have a
particular format depending on logical unit class, device type,
and the type of FORTRAN input/output operations applying to that
record.
The maximum length of a formatted record depends on the logical
unit or device, as shown in Figure 42.
DOS/VSE Logical
Unit Name
Device
Permitted
Type Of
Operation
Maximum Record
Length
SYSIPT
SYSIN
SYSPCH
SYSLST
SYSLOG
Card reader, tape Input
uni t , or di sk
storage unit
Punch card device, Output
tape unit, or disk
storage unit
Printer, tape, or Output
disk storage unit
Console typwriter Output
or printer
80 bytes
80 bytes
145 bytes for
tape and printer
121 bytes for
disk.
256 bytes for
console typewriter.
Printei the
number of print
positions plus one
for carriage control
Figure 42. DOS/VSE Logical Units and Devices Allowed
Programming Input and Output
187
By device, the maximum size permitted for each record follows*
Device
Card Reader
Card Punch
Pri nter
Tape
Disk (sequential
access)
Direct access
Maximum Bytes
80
80
Number of print
position, plus
one byte for
carriage control
260
Device Dependent
(see Appendi x A. )
As specified in an
OPEN statement.
i
For unformatted input/output, a single WRITE or READ may cause
the transfer of more bytes than are contained in a single record.
The system organizes such data into two or more records.
The system provides eight bytes of control information at the
beginning of each record block. This information indicates the
size of the record and whether it is part of a record that is
continued in one or more other blocks. There is never more than
one record for each block.
When this control information is needed it is provided and
maintained by the system. There's no need to consider it in
writing your input/output instructions.
The first four bytes of control information for unformatted
records constitute a block descriptor word; the next four bytes
constitute a segment-descriptor word.
\^
o
188 VS FORTRAN Application Programming* Guide
CODING CALLING AND CALLED PROGRAMS
You may need to write programs which require a'specific operation
to be performed again and again, with different data for each
repetition; for example, a complex mathematical operation.
You can simplify the writing of such programs if you write the
statements in a separate subprogram that performs the repetitive
operation once; you can then simply refer to the subprogram
throughout the program, as if the operation itself were inserted
at the points you need to use it.
For example^ you can write a general routine to take the cube
root of any number; you can then link-edit that routine, as an
external reference, with any program in which cube root
calculations &re required.
The program that requires the services of the generalized
routine is the calling program.
The generalized routine itself (for example, the cube root
routine) is the called program.
Calling and called programs make up a hierarchy of programs. The
first program unit to call others is the main program , which is
required in every program unit. The main program invokes
subprograms; however, subprograms cannot invoke the main
program.
Subprograms can invoke other subprograms to any depth. However,
a subprogram cannot invoke itself, and it cannot invoke any
subprogram in the hierarchy that invoked it. For example*
A invokes B and E
B invokes C and F
C invokes D
Program D cannot invoke program A, B, or C; it can, however,
invoke program E or F.
Kinds of Called Programs
Called programs in VS FORTRAN can be of three kinds*
• Subroutine Subprograms — which are invoked in the calling
program through the CALL statement. For example 1
CALL CROOT (INTR)
This CALL statement makes the value in INTR available to
subprogram CROOT and transfers control to the first
executable statement in subprogram CROOT. When CROOT has
completed execution, control is transferred back to the main
program.
The point at which execution resumes depends upon the
processing within the subprogram.
Depending upon the logic of the program, CROOT may or may not
return a value in INTR.
Function Subprograms — which are invoked in the calling
program through function references. For example*
ANS = LNGTH * CROOTKINTR)
Coding Calling and Called Programs 189
SHARING DATA BETWEEN PROGRAMS
Calling and called programs can share data between them, as we
have seen in the previous examples.
In FORTRAN, there are two ways to share data' by passing
arguments (data names identifying data items) between the
programs, or by using common data areas (areas that can be shared
by more than one program).
\J'"
When this statement is executed, the main program makes the
value in INTR available to function subprogram CR00T1 and
transfers control to the first executable statement in it.
As soon as CR00T1 finishes processing, control is returned
to the main program together with a value that is multiplied
by LNGTH to give ANS.
FORTRAN-Supplied Intrinsic Functions— which are a special
form of function subprograms with fixed names, available in
the execution-time library. The intrinsic functions perform
often-used mathematical and character functions, such as
obtaining logarithms of numbers, exponentiation,
trigonometric and hyperbolic evaluations, and character
mani pulati ons.
For example, to obtain the square root of INTR, you can use
the SQRT function:
ANS = LNGTH * SQRT(INTR)
which executes the SQRT intrinsic function using the value
of INTR; the function then returns a value to the calling
program, which then uses the returned value in executing the
assignment statement, multiplying LNGTH by the value
returned by SQRT and placing the result in ANS.
The names ARSIN, ARCOS, DARSIN, and DARCOS are intrinsic
function names when using the option LANGLVL(66). The
corresponding names for LANGLVL(77) are ASIN, ACOS, DASIN,
and DACOS. The extended precision names for LANGLVL(66) and
LAHGLVL(77) are QARSIN and QARCOS.
If you use the names ARSIN, ARCOS, DARSIN, or DARCOS under
LANGLVL(77), the corresponding functions are considered to
be external; that is, it is assumed you are supplying these
functions in your library or as one of your subprograms.
However, if you fail to supply your own and are using the MVS ^^lV
or CMS system, the corresponding FORTRAN functions supplied
for the LANGLVL(66) names will be obtained from the library
and used.
However, if your are using DOS, this resolution is not made
and you must supply your own function. In this case, no
indication is given to the non-DOS user that the resolution
was made to the FORTRAN library routine instead of to your
own routine.
PASSING ARGUMENTS BETWEEN PROGRAMS
You can pass data values between a calling program and a
subprogram through the use of paired lists of actual and dummy
arguments. The paired lists must contain the same number of
items, and be in the same order; in addition, items paired with
each other must be of the same type and length. You can use such
paired lists in both SUBROUTINE and FUNCTION subprograms.
dP)-
190 VS FORTRAN Application Programming: Guide
Passing Arguments to a function subprogram
C
You can use actual and dummy arguments when you're invoking a
function subprogram. If your main program contains the following
function reference?
G = B * ZCALCCINUM,X,Y)
the actual arguments in function ZCALC are INUM, X, and Y; they
contain the actual values you want to make available to the
function subprogram.
In the ZCALC function subprogram, you define the dummy
arguments'*
FUNCTION ZCALC(M,X,ZZ)
The dummy arguments of function subprogram ZCALC are M, X, and
ZZ.
When the calling program executes the statement containing the
function reference* the values in the actual arguments are made
available to the dummy arguments :
The Value of: Is Hade Available in:
•INUM M
X X
Y ZZ
again, according to their positions in the argument lists.
M, X, and ZZ can then be used in operations within the function
subprogram.
When control returns to the calling program, a value is returned
to the calling program; then the assignment statement is
executed, using the value returned.
Passing Arguments to a SUBROUTINE Subprogram
You can use actual and dummy arguments to pass data between a
calling program and a SUBROUTINE subprogram. For example, if the
calling program contains the statement 5
CALL MAXNUM( PI, FOURV, XYZ, BIGM, HH)
PI, FOURV, XYZ, BIGM, and HH are actual arguments; they contain
values you want to make available to the SUBROUTINE subprogram.
The MAXNUM subprogram, in order to make the values available,
must contain a matching list of dummy arguments?
SUBROUTINE MAXNUMC A,B,C,D, E)
The dummy arguments of SUBROUTINE subprogram MAXNUM are A, B, C,
D, and E.
When the CALL statement is executed, the addresses of the actual
arguments are used as the addresses of the matching dummy
arguments-'
The Address of: Becomes the Address of:
PI A
FOURV B
XYZ C
BIGM D
HH E
When MAXNUM is executed, the newly assigned values of A, B, C, D
and E can be used in operations.
Coding Calling and Called Programs 191
When control returns to the calling program, the current values
in A, B, C, D, and E are also the current values of PI, FOURV, __ .
XYZ, BIGM, and HH in the calling program. (f\ )
General Rules for Arguments
You must define dummy arguments to correspond in number, order,
and type with the actual arguments. For example, if you define an
actual argument as an integer constant of length 4, you must
define the corresponding dummy argument as an integer of length
4.
Actual arguments are passed by name; if you alter the value of an
argument in the subroutine or function subprogram, you're
altering the value in the calling program as well.
If you define an actual argument as an array, then the size of
your paired dummy array must not exceed the size of the actual
array .
If you define a dummy argument as an array, you must define the
corresponding actual argument as an array or an array element.
If you define the actual argument as an array element, your
paired dummy array must not be larger than the part of the actual
array which follows and includes the actual array element you
speci fy.
Assigning Argument Values
If your subprogram assigns a value to a dummy argument, you must
ensure that its paired actual argument is a variable, an array
element, or an array. Never specify a constant or expression as
an actual argument, unless you are certain that the
corresponding dummy argument is not assigned a value in the / \
subprogram. W^V
Your subprograms should not assign new values to dummy arguments
that are associated with other dummy arguments in the
subprogram, or with variables in COMMON. You may get unexpected
results, but the compiler cannot give you a warning message.
For example, if you define the subprogram DERIV as:
SUBROUTINE DERIV CX,Y,Z)
COMMON W
and if you include the following elements in the calling program'
COMMON B
CALL DERIV (A, B, A)
the DERIV subprogram should not assign new values to X, Y, Z, and
W:
X and Z because they ar& both associated with the same
argument, A.
Y because it is associated with argument B, which is in
COMMON.
U because it also is associated with B.
For reference documentation about dummy arguments and actual
arguments, see the VS FORTRAN Application Programming? Language
Reference manual. /fA
: <U-
192 VS FORTRAN Application Programming: Guide
SHARING DATA STORAGE — COMMON STATEMENT
You can use the COMMON statement to share data storage areas
between two or more program units, and to specify the names of
variables and arrays occupying the shared area.
There are two reasons why you might want to share data storage J
1. To conserve storage, by using only one storage allocation
for variables and arrays used by several program units
2. To implicitly transfer arguments between program units
Arguments passed in a common area are subject to the same rules
as arguments passed in a SUBROUTINE subprogram argument list
(see "General Rules for Arguments").
For reference documentation about the COMMON statement, see the
VS FORTRAN Application Programming: Language Reference manual.
Data Item Order — COMMON statement
Entries in a common area share storage locations; therefore, the
order in which you specify them is significant when you use the
common area to transmit arguments. For example, you specify the
following COMMON statements in the calling program:
COMMON A, B, C, R(100)
REAL A, B, C
INTEGER R
and you specify the following COMMON statement in your
subprogram:
COMMON X, Y, Z, S(IOO)
REAL X, Y, Z
INTEGER S
Figure 43 shows the order in which these variables and arrays are
placed in the common area, and how they share common storage.
Each column of variables starts at the beginning of the common
area. Variables on the same line share the same storage location.
Calling Program Shares Called Program Displacement Bytes From
Item Hith Item Beginning of COMMON
4
8
12
16
20
A
X
B
Y
C
Z
R(l)
S(l)
R(2)
SC2)
R(100) S(IOO)
408
4 12
Figure 43. Example of Shared Data Areas — COMMON Statement
Coding Calling and Called Programs 193
The calling program can assign values to A, B, C, and R, and
those values are available to X, Y, Z, and S of the subprogram.
Conversely, the subprogram can assign values to X, Y, Z» and S,
and those values are available to A, B, C, and R of the calling
program.
Using the COMMON statement in this way, you can share the values
in a number of data items without transmitting them in the
argument list of a CALL statement.
Type and Length Considerations — COMMON statement
In order to pass arguments using the COMMON statement, you must
define the items that are to share common storage with the same
type and length.
For example, if you define a common srsa in a main program and in
three subprograms, as follows*
Main Program* COMMON A,B,C (A and B are 8 storage locations,
C is 4 storage locations)
Subprogram 1* COMMON D,E,F (D and E are 8 storage locations,
F is 4 storage locations)
Subprogram 2* COMMON Q,R,S,T,U (4 storage locations each)
Subprogram 3* COMMON V,W,X,Y,Z (4 storage locations each)
How these variables are arranged within common storage is shown
in Figure 44.
Main Displacement
Program subprogram 1 subprogram 2 subprogram 3 (Bytes)
<— -> D $
8
B < — > E 12
Q
< >
V
R
< >
w
S
< >
X
T
< — >
Y
U
<- — >
z
C < > F < >
Figure 44. Transmitting Values Between Common Areas
16
20
J>
\-^-y'
The main program can transmit values for A, B, and C to
subprogram 1, provided that
• A i s of the same type as D.
• B i s of the same type as E.
• C is of the same type as F.
However, the main program and subprogram 1 cannot, by assigning
values to the variables A and B, or and E, respectively*
transmit values to the variables Q, R, S, and T in subprogram 2,
or V, 1*1, X, and Y in subprogram 3, because the lengths of their
common variables differ.
In the same way, subprogram 2 and subprogram 3 cannot transmit (J y
values to variables A and B, or to D and E. ^-^
194 VS FORTRAN Application Programming* Guide
Values can be transmitted between variables C, F, U, and Z if
each is the same data type as the others.
Also, if each is the same data type, values can be transmitted
between A and D, between B and E, and between Q and V, R and W, S
and X, and T and Y. - ■
However, any assignment of values to A or D destroys any values
assigned to Q, R, V, and W (and vice versa); and any assignment
to B or E destroys the values of S, T, X, and Y (and vice versa).
Efficient Arrangement of variables — COMMON statement
O
Your programs lose some object-time efficiency unless you ensure
that all of the common variables have proper boundary alignment.
(However, it isn't necessary for you to align COMPLEX, INTEGER,
LOGICAL, or REAL variables; your programs will still execute
correctly. )
You can ensure proper alignment either by arranging the
non-CHARACTER type variables in a fixed descending order
according to length, or by defining the block so that dummy
variables force proper alignment.
FIXED ORDER OF VARIABLES — COMMON STATEMENT: If you use the fixed
order, non-CHARACTER type variables must appear in the following
order J
Length Type
IBM EXTENSION 1
32 COMPLEX
16 COMPLEX or REAL
8 REAL
END OF IBM EXTENSION
8 COMPLEX or DOUBLE PRECISION
<\ REAL, INTEGER, or LOGICAL
2 INTEGER
1 LOGICAL
IBM EXTENSION
END OF IBM EXTENSION
USING DUMMY VARIABLES— COMMON STATEMENT: If yoU don't use the
fixed order, you can ensure proper alignment by constructing the
block so that the displacement of each variable can be evenly
divided by the reference length associated with the variable.
(Displacement is the number of storage locations, or bytes, from
the beginning of the block to the first storage location of the
variable.) The reference length in bytes for each type of
variable is as follows:
Coding Calling and Called Programs 195
Type Length Reference
Specification Specification Length (Bytes) ff\)
LOGICAL
INTEGER
REAL
DOUBLE PRECISION
COMPLEX
4
4
4
8
8
i
l
LOGICAL
INTEGER
REAL
REAL
COMPLEX
COMPLEX
1
2
8
16
16
32
t
t-iirk
IBM EXTENSION
The fi rst variable in every common block is positioned as though
its length specification were 8. Therefore* you can assign a
variable of any length as the the first in a COMMON block.
To obtain the proper alignment for the other variables in the
same block, you may find it necessary to add a dummy variable to
the block.
For example, your program uses the variables A, K, and CMPLX
(defined as REAL*4, INTEGER**, and COMPLEXES, respectively) in a
COMMON block defined as:
COMMON A, K, CMPLX
The displacement of these variables within the block is:
variable Displacement (Bytes) » ,
in common ^^
CMPLX
16
The displacements of K and CMPLX are evenly divisible by their
reference numbers.
IBM EXTENSION
However, if you define K as an integer of length 2, then CMPLX
is no longer properly aligned (its displacement of 6 i s not
evenly divisible by its reference length of 8). In this case,
you can ensure proper alignment by inserting a dummy variable
(DV) of length 2 either between A and K or between X and CMPLX.
o :
196 VS FORTRAN Application Programming: Guide
variable
A
DV
Displacement (Bytes)
in COMMON
CMPLX
16
END OF IBM EXTENSION
EQUIVALENCE Considerations — COMMON statement
O
When you use the EQUIVALENCE statement together with the COMMON
statement* there are additional complications resulting from
storage allocations. The following examples illustrate
programming considerations you must take into account.
Your program contains the following items 5
REAL R4A, R4B, R4M(3,5), R4NC7)
DOUBLE PRECISION R8A, R8B, R8M(2)
IBM EXTENSION
L0GICALX1 L1A
END OF IBM EXTENSION
LOGICAL L4A
which are defined in COMMON as follows:
COMMON R4A, R8M, L1A , R8A, L4A, R4M
and which results in the following inefficient di splacements*
Name Displacement Boundary
R4A
R8M
L1A
Doubleword
Word (should be doubleword)
20
— IBM EXTENSION
Word
END OF IBM EXTENSION
R8A
21
L4A
29
R4M
33
Byte (should be doubleword)
Byte (should be word)
Byte (should be word)
Now add an EQUIVALENCE statement to this inefficient COMMON
statement 5
1. First Example (valid but inefficient):
EQUIVALENCE (R4M(1,1), R4B)
EQUIVALENCE (R4B, R8B)
Coding Calling and Called Programs
197
This results in the following additional inefficiencies?
Name Displacement Boundary
R4B 33 Byte (same as R4M(1,1))
R8B 33 Byte (same as R4M(1,1) and R4B)
which means that now both R4B and R8B are now also
inefficiently aligned.
Second Example (illegal):
EQUIVALENCE (R8A, R4N(7))
This is illegal, because the seventh element of R4N has the
same displacement as R8A, or 21.
This means that the f i rst element of R4N is located 24 bytes
(4*6) before this, at displacement -3. It is illegal to
extend a COMMON area to the left in this way.
Third Example (valid but inefficient):
EQUIVALENCE (R8A, R4N(2))
EQUIVALENCE (R4M, R4N(5))
This has the following results:
Name Displacement Boundary
Byte
Byte
Byte
Byte
Byte (same position as R4N(5)
This is valid because the EQUIVALENCE statement places R4M
at displacement 33, the same displacement as that specified
in the COMMON statement. However, it is inefficient because
both R4N and R4M begin at a byte boundary.
4. Fourth Example (illegal):
EQUIVALENCE (R8A, R4N(2))
EQUIVALENCE (R4M, R4N(4))
This has the following illegal results:
Name Displacement Boundary
R4N(2) 21 Byte
R4N(3) 25 Byte
R4N(4) 29 Byte
R4N(5) 33 Byte
R4M 29 Byte (same position as R4N(4)
This is illegal, because the EQUIVALENCE statement (which
places R4M at displacement 29) contradicts the COMMON
statement (which places R4M at displacement 33). The COMMON
statement controls the displacement of R4M, not the
EQUIVALENCE statement.
BLANK AND NAMED COMMON
R4N(2)
21
R4N(3)
25
R4N(4)
29
R4N(5)
33
R4M
33
There are two forms of common storage you can specify: blank
common and named common.
Vj/
\jr"
198 VS FORTRAN Application Programming: Guide
Blank Common
In the preceding example, the common storage area (common block)
is a blank common area, since you gave no name to the storage
area. The variables you specified in the COMMON statements were
assigned locations relative to the beginning of this blank
common area.
When you specify items in blank common, you can't use a BLOCK
DATA program to initialize them.
Named Common
You can name common storage areas (or blocks of storage) — known
as named common . Blocks given the same name occupy the same
space.
You can place variables and arrays in separate common areas
This lets you specify that a calling program is to share one
common block with one subprogram, and to share another common
block with another subprogram. It also gives you better program
documentat i on .
Using Blank Common and Named common
V
There are different FORTRAN rules for blank and named common
areas, which may cause you to choose one type over the other,
depending on what you want your program to do.
The differences are :
• You can define only one blank common block in an executable
program, although you can specify more than one COMMON
statement defining items in blank common; you cannot assign
blank common a name. You can define many named common blocks,
each with its own name.
• You can define blank common as having different lengths in
different program units. You must define a given named
common block with the same length in every program unit that
uses it.
• You can't assign initial values to variables and array
elements in blank common.
• In named common* you can assign initial values to variables
and array elements, through a BLOCK DATA subprogram that
contains DATA statements or explicit specification
statements.
In a COMMON statement, you specify a common block name by
enclosing it in slashes. The following example defines a named
common block, PAYROL, that contains the variables FICA, MANHRS,
SICKDA:
COMMON/PAYROL/FICA, MANHRS, SICKDA
You can define blank common in a COMMON statement by omitting a
name, and defining the blank common area firsts
COMMON A, CG/PAYROL/FICA, MANHRS, SICKDA
and the variables A, C, and 6 are placed in blank common.
You can also specify blank common items after named common items,
by placing two consecutive slashes before the list of blank
common variables:
For example, in the following statement:
Coding Calling and Called Programs
199
COMMON A, C, G /PAYROL/FICA,MANHRS,SICKDA// JJ, VMN, LP7
you've defined the variables A, C, G, JJ, VMN, and LP7 in blank
common, and in that order. You've defined PAYROL as named common,
containing FICA, MANHRS, and SICKDA, in that order.
If you specify more than one COMMON statement in a program, the
definitions are cumulative through the program. For example, if
you specify the following two COMMON statements?
COMMON A, B, C /R/ D, E /S/ F
COMMON G, H /S/ I, J /R/P // W
they have the same effect as if you specified the single
statement*
COMMON A,B,C,G,H,W /R/ D, E, P /S/ F, I, J
(TV
Using Blank and Named Common — Example
The differences in usage between blank and named common are
illustrated in the following example.
Your programs specify that A, B, C, K, X, and Y each occupy four
locations of storage, H and G each occupy eight locations, and D,
E, and F each occupy two locations.
Calling Program
COMMON H, A /R/ X, D, E // B
Subprogram
SUBROUTINE MAPMYC . ..)
COMMON G, Y, C /R/ K, E, F
In the calling program, the statement*
COMMON H, A /R/ X, D, E // B
reserves the following storage*
16 locations in blank common (eight locations for H, and four
each for A and B)
Eight locations in named common R (four for X, and two each
for D and E) .
The following statement in the subprogram MAPMY*
COMMON G,Y,C/R/K,E,F
causes the following common storage sharing*
In blank common, the variables G, Y, and C share the same
storage as H, A, and B, respectively.
In named common, the variables K, E, and F share the same
storage as X, D, and E respectively.
The common storage is laid out as shown in Figure 45.
A )
200 VS FORTRAN Application Programming* Guide
Displacement (Bytes)
in COMMON
Blank Common BLank Common
8
12
16
Named Common R Named Common R
8
Figure 45. Blank and Named Common Storage Sharing
Calling
Program
Called
Program
H
< — >
G
A
< — >
Y
B
< — >
c
X
< — >
K
D/E
< — >
E/F
CODING MAIN PROGRAMS — CALLING PROGRAMS
^
When you're writing a series of program units that communicate
with each other* the first program in the calling chain must be a
main program.
The main program can invoke subprogram units* which in turn can
invoke other subprogram units; however* none of the subprogram
units can invoke the main program, and no program can invoke
itself.
NAMING YOUR MAIN PROGRAM— PROGRAM STATEMENT
To give your main program a name, use the PROGRAM statement as
the first statement in the program* as shown below.
PROGRAM CUBES
DO 10 1=12,26
J = 1**3
10 CONTINUE
END
The PROGRAM statement names your main program CUBES. (The name is
appropriate* since the program cubes the numbers from 12 to 26
and then manipulates those values, perhaps printing both I and J
each time the program goes through the loop.)
If you don't use the PROGRAM statement* your main program is
named MAIN.
For reference documentation about the PROGRAM statement, see the
VS FORTRAN Application Programming' language Reference manual .
INVOKING FORTRAN-SUPPLIED FUNCTIONS
There are a number of FORTRAN-suppli ed functions (intrinsic
functions) you'll find useful* including mathematic functions to
derive trigonometric values* logarithms* exponential values*
maximum and minimum values* sign conversions* absolute values*
error functions* and functions to manipulate character operands.
Coding Calling and Called Programs
201
N|t_ J
Invoke a FORTRAN-supplied function by referring to the function
name within an arithmetic statement; the function name is /f "> )
replaced by the value returned from the invoked function, after
the invoked function has completed its calculations.
For instance, you can invoke the FORTRAN-supplied function
subprogram that returns the square root of a number, with
statements in your program such as*
Y = SQRTCX+Z) X 3.1
If the sum of X and Z is 9.0, then the square root of X+Y is 3.0,
and the value assigned to Y would be 3.0 times 3.1, or 9.3.
In VS FORTRAN, you can use the generic function name, and the
compiler will select the function your program actually should
use,
DOUBLE PRECISION X. Z. Y
Y = SQRKX+Z) * 3.1
In this case, you've specified SQRT, the generic function name;
however, during compilation the compiler selects the DSQRT
function, which gives a double precision result.
When you are using the current language level and specify an
intrinsic function name in an explicit type statement, the
intrinsic function is not removed from its status as an intrinsic
function; this is true whether you specify the predefined
function type or whether you respecify it as another type. When
the intrinsic function is executed, the mode used is the mode
predefined to the compiler.
However, when you are using the old language level and specify an
intrinsic function name in an explicit but conflicting type
statement, you remove it from its intrinsic status and it becomes ^-^ )
the name of a user-supplied external function. ' :
Using FORTRAN-supplied Functions as Arguments — INTRINSIC statement
If you want to pass FORTRAN-supplied function names as
arguments, you must specify an INTRINSIC statement in the
invoking program:
INTRINSIC CSIN,CC0S, TAN, SINH, COSH
This lets you use the FORTRAN-supplied CSIN, CCOS, TAN, SINH, and
COSH mathematical subroutines as arguments in your own functions
or subroutine programs.
In the INTRINSIC statement, you can specify a given function name
only once. That is, in the preceding example, it would be invalid
to repeat CSIN at the end of the list of function names.
When you specify ah INTRINSIC statement, it must precede all the
statement function definitions and executable statements in the
program uni t .
For reference documentation about FORTRAN-supplied functions,
see the VS FORTRAN Application Programming: Library Reference
manual .
For reference documentation about the INTRINSIC statement, see
the VS FORTRAN Application Programming? Language Reference
manual.
Comparing Character Operands — FORTRAN-supplied Functions
When your programs compare character operands using the (i \
following intrinsic functions* \j^
202 VS FORTRAN Application Programming: Guide
LLT— -logically less than
LGT — logically greater than
LLE — logically less than or equal to
LGE — logically greater than or equal to
the character operands are compared using the ASCII collating
sequence.
For example, if CI contains "3AB" and C2 contains "XYZ", the
following comparison:
L = LGT(C1,C2)
will evaluate as "false."
(However, if the same operands are compared, using a relational
operator '>
L = C1.GT.C2
the EBCDIC collating sequence is used for the comparison, and the
statement evaluates as "true.")
The EBCDIC and ASCII collating sequences are listed in the VS
FORTRAN Application Programming* Language Reference manual.
INVOKING FUNCTION AND SUBROUTINE SUBPROGRAMS
c
FUNCTION and SUBROUTINE subprograms are useful for performing
often-repeated routines that might be shared by many
programs — such as error recovery routines for input/output
statements, or of ten-repeated mathemati cal calculations.
Both types of subprograms are discussed in the following
sections.
Invoking function Subprograms
O
Invoke a function subprogram of your own in the same way you
invoke an IBM-supplied function — through a program reference.
The function name is replaced by the value returned from the
invoked function, after the invoked function has completed its
calculati ons.
For instance, you can invoke a function subprogram you've named
BCALC, with the following statement in your invoking program*
R = BCALCCA+B) * 3.1
Your program calculates the sum of A and B and passes that value
to the function subprogram BCALC; when BCALC completes
executing, it returns the value to the invoking program, which
then multiplies it by 3.1 to give the value of R.
FUNCTION SUBPROGRAMS AND THE EXTERNAL STATEMENT-' You use the
EXTERNAL statement wi th your FUNCTION subprograms in two
di fferent ways :
• If you name the program with an IBM-supplied function name,
you must list the name in an EXTERNAL statement.
For example, if you write your own square. root routine, and
you name it SQRT, you must specify it in an EXTERNAL
statement '-
EXTERNAL SQRT
Coding Calling and Called Programs 203
which tells the compiler that you want any SQRT references in
your program to invoke your own SQRT routine rather than the
IBM-supplied SQRT routine.
• If you want to pass a function subprogram as an argument, you
must specify the name of the subprogram in an EXTERNAL
statement.
When you specify an EXTERNAL statement, it must precede all the
statement function definitions and executable statements in your
program. The names you specify in an EXTERNAL statement can be
names of external procedures, dummy procedures, or BLOCK DATA
subprograms.
You can't use the same name in both an EXTERNAL statement and an
INTRINSIC statement.
For reference documentation about the INTRINSIC and EXTERNAL
statements* see the VS FORTRAN Application Programming* Language
Reference manual.
invoking SUBROUTINE subprograms — CALL Statement
To execute a SUBROUTINE subprogram at a certain point in a
program, issue a CALL statement at that point in the invoking
program. The CALL statement can optionally pass actual arguments
to replace the dummy arguments in the called SUBROUTINE
subprogram*
CALL OUT (no actual arguments passed)
CALL SUB1(X+Y*5,ABDF(IND),SINE) (three actual arguments passed)
When it's executed, the CALL statement transfers control to the
SUBROUTINE subprogram, and associates the dummy variables in the
SUBROUTINE subprogram with the actual arguments that appear in '^-^ f
the CALL statement, as shown in Figure 46.
Calling Program SUBROUTINE Subprogram
DIMENSION X(90),Y(90)
SUBROUTINE C0PY(A,B,N)
DIMENSION A(N),B(N)
DO 10 I = 1,N
CALL COPY (X,Y,90) 10 B(I) = A(I)
RETURN
END
Figure 46. CALL Statement Execution
When the CALL COPY statement is executed*
The addresses of the actual arguments, array X and array Y,
become the addresses of the dummy arguments, array A and
array B, in the subprogram.
The variable N in the subprogram is associated with the
value 90.
Thus a call to subprogram COPY, in this instance, results in the
90 elements of array X being copied into the 90 elements of array
Y.
o
204 VS FORTRAN Application Programming* Guide
c
CODING SUBPROGRAMS — CALLED PROGRAMS
There are four types of subprograms that you can use in VS
FORTRAN: FORTRAN-suppli ed functions, FUNCTION subprograms,
SUBROUTINE subprograms, and BLOCK DATA subprograms.
FORTRAN-suppli ed functions let you use predefined calculations
for commonly used mathematical and character manipulations.
FUNCTION and SUBROUTINE subprograms are useful when your program
must perform the same set of computations with different data at
various points in the program.
In a calling program, you invoke a FUNCTION subprogram by a
statement reference to the function name. After the function has
been executed, the function name has a value and can be used in a
calculation just as a variable is used.
In a calling program, you invoke a SUBROUTINE subprogram by a
CALL statement that specifies the subprogram name.
Your calling program can also invoke a SUBROUTINE subprogram by a
CALL statement that specifies an ENTRY name within the
subprogram.
You code a BLOCK DATA subprogram when you want to initialize
variables in named common blocks. These subprograms are neither
called nor invoked by a reference to the subprogram name; they
initialize the variables at compile time.
CODING FUNCTION SUBPROGRAMS
c
The first statement in a FUNCTION subprogram (excluding
debugging statements) is a FUNCTION statement, identifying the
program. For example?
FUNCTION TRIG (DELTA, THETA, ABSVAL)
This statement identifies the subprogram named TRIG as a
FUNCTION subprogram, with dummy arguments DELTA, THETA, and
ABSVAL.
The data type of the function is real of length 4 — derived from
the predefined naming conventions. (The data type of the
function determines the data type of the value it returns to the
invoking program.)
You can also explicitly specify the data type of the function:
DOUBLE PRECISION FUNCTION TRIG (DELTA, THETA, ABSVAL )
which specifies that the data type of TRIG is real of length 8.
I IBM EXTENSION
If you want TRIG to be a real function of length 8, you can
alternatively specify:
REAL FUNCTION TRIG*8(DELTA * THETA, ABSVAL )
END OF IBM EXTENSION
You can also specify a FUNCTION subprogram as being of CHARACTER
type:
CHARACTERK10 FUNCTION TEXT1 (W0RD1 ,W0RD2)
which defines TEXT1 as a CHARACTER function which returns a
CHARACTER value of length 10, using dummy arguments WORD1 and
W0RD2.
Coding Calling and Called Programs 205
In a function subprogram, you can use any FORTRAN statements,
except PROGRAM (which Mould define it as a main program),
SUBROUTINE (which would define it as a SUBROUTINE subprogram),
or BLOCK DATA (which would define it as a BLOCK DATA subprogram)
You must code the last statement in a FUNCTION subprogram as an
END statement.
You can also specify any number of RETURN statements.
Both the END and RETURN statements return control to the
statement making the function reference in the calling program.
For reference documentation about the FUNCTION statement, see
the VS FORTRAN Application Programming' Language Reference
manual .
The first statement in a SUBROUTINE subprogram (excluding
debugging statements) is a SUBROUTINE statement, identifying the
program:
SUBROUTINE TRIG (DELTA, THETA, ABSVAL)
This statement identifies the subprogram named TRIG as a
SUBROUTINE subprogram, with dummy arguments DELTA, THETA, and
ABSVAL.
In a SUBROUTINE subprogram, you can use any FORTRAN statements,
except PROGRAM (which would define it as a main program) ,
FUNCTION (which would define it as a FUNCTION subprogram), or
BLOCK DATA (which would define it as a BLOCK DATA subprogram).
You must code the last statement in a SUBROUTINE subprogram as an
END statement. You can also specify any number of RETURN
statements. Both of these statements return control to the
statement following the CALL statement in the calling program,
except when you specify an alternate return.
For reference documentation about the SUBROUTINE statement, see
the VS FORTRAN Application Programming: Language Reference
manual .
SPECIFYING ALTERNATIVE ENTRY POINTS—ENTRY STATEMENT
When you're developing either FUNCTION or SUBROUTINE
subprograms, you can specify alternative entry points within the
program, using the ENTRY statement.
For example, subprogram TRIG could have an alternative entry
point, depending on the data type of the values you wanted
returned.
Alternative Entry Points in FUNCTION Subprograms
If FUNCTION TRIG had an alternative entry point, the sequence of
statements would look something like this!
FUNCTION TRIG (DELTA, THETA, ABSVAL)
DOUBLE PRECISION BETA,ZETA, ABVAL1 ,TRIG8
RETURN
ENTRY TRIGS (BETA,ZETA , ABVAL1 )
END
206 VS FORTRAN Application Programming: Guide
\ This FUNCTION subprogram can be executed in either of two Mays:
1. When the calling program uses TRIG in a function reference,
the FUNCTION subprogram is entered at the first executable
statement, and the value returned is a real value of length
4.
The RETURN statement returns control to the calling program.
2. When the calling program uses TRIG8 in a function reference,
the FUNCTION subprogram is entered at the first executable
statement following TRIG8, which is defined as a double
precision function; therefore, the value returned is a real
value of length 8.
The END statement returns control to the calling program.
Alternative Entry Points in SUBROUTINE subprograms
If SUBROUTINE TRIG had an alternative entry point, the sequence
of statements would look something like this:
, SUBROUTINE TRIG (DELTA, THETA , ABSVAL )
DOUBLE PRECISION BETA,ZETA, ABVAL1
RETURN
ENTRY TRIG8 (BETA,2ETA , ABVAL1 )
END
This SUBROUTINE subprogram can be executed in either of two ways:
1. When the calling program uses TRIG in a CALL statement, the
SUBROUTINE subprogram is entered at the first executable
statement, and the subprogram uses the arguments DELTA,
THETA, and ABSVAL, which are real items of length 4.
The RETURN statement returns control to the calling program.
2. When the calling program uses TRIG8 in a CALL statement, the
SUBROUTINE subprogram is entered at the first executable
statement following TRIG8, and the subprogram uses the
arguments BETA, ZETA, and ABVAL1, which are real items of
length 8.
The END statement returns control to the calling program.
SPECIFYING ALTERNATIVE RETURN POINTS — RETURN STATEMENT
4F%
'■■^^H(jr
When you're developing SUBROUTINE subprograms, you can specify
alternative return points within the calling program, using the
RETURN statement.
The RETURN statement, with no operands, can serve as one
alternative return point, as the previous examples illustrate.
You can also code the RETURN statement with an integer variable
operand; this allows you to specify variable return points. That
is, you can return control to any labeled statement in the
calling program.
For example, SUBROUTINE subprogram TRIG could have a variable
return point, depending on the data values it develops 5
Coding Calling and Called Programs 207
Calling Program Called Program
SUBROUTINE TRIG (X,Y,Z,*,*) (f^
10 CALL TRIG ( A,B,C,*30 ,*40)
20 Y = A + B 100 IF (M) 200,300,400
200 RETURN
30 Y = A + C 300 RETURN 1
400 RETURN 2
40 Y= B - C END
When statement 10 of the calling program is executed, control is
transferred to the first executable statement in TRIG. In TRIG,
when statement 100 is executed, the value of M in the arithmetic
IF statement determines which RETURN statement is executed:
If M is less than zero, control is transferred to statement
200? and the RETURN statement returns control to statement
20 in the calling program. (This is the statement following
the CALL statement.)
If M is equal to zero, control is transferred to statement
300, and the RETURN 1 statement returns control to the first
statement number in the calling program's actual argument
list (*30). (Thus, control is returned to statement 30 in the
calling program.)
If M is greater than zero, control is transferred to
statement 400, and the RETURN 2 statement returns control to
the second statement number in the calling program's actual
argument list (*40). (Thus, control is returned to statement
40 in the calling program.)
Execution then continues in the calling program.
RETAINING SUBPROGRAM VALUES— SAVE STATEMENT ^
The current FORTRAN standard states that, when a RETURN or an END
statement in a subprogram is executed, all variables become
undefined except for those in blank common, those in the argument
list, and those specified in a SAVE statement. Thus, you use the
SAVE statement to retain such undefined values.
For program portability, you can use the SAVE statement to
ensure, if the program is recompiled on some other FORTRAN
compiler, that values in specific named common blocks,
variables, or arrays are saved when a RETURN or an END statement
i s executed.
In VS FORTRAN, these values are still available after a RETURN or
an END statement is executed; however, the compiler accepts the
SAVE statement and treats it as documentation.
For reference documentation about the SAVE statement, see the VS
FORTRAN Application Programming? Language Reference manual.
INITIALIZING NAMED COMMON— BLOCK DATA SUBPROGRAMS
BLOCK DATA subprograms let you initialize data items in named
common. (You can't initialize data items in blank common.)
The first statement you specify in a BLOCK DATA subprogram mus*
be the BLOCK DATA statement. For example*
BLOCK DATA
BLOCK DATA COMDAT
208 VS FORTRAN Application Programming: Guide
^>
where COMDAT is the name (optional) you've given the BLOCK DATA
subprogram. If you specify a name* it must not be the same as the
name of any other program, of an alternate entry point, of a
common block, or of any data item within this BLOCK DATA
subprogram.
The only statements you can specify in a BLOCK DATA subprogram
are'*
BLOCK DATA (first statement in program)
IMPLICIT (if used, must immediately follow BLOCK DATA
statement)
PARAMETER
SAVE
DIMENSION
COMMON (must specify named common areas, each defined once)
EQUIVALENCE
DATA (must follow data item definitions in named COMMON
statements, and must specify only data items in named
common)
Type statements
END (must be last statement in subprogram)
The presence of a BLOCK DATA subprogram initializes named common
data values in main programs or subprograms that refer to the
named common blocks. Therefore, your programs must not contain
CALL statements or function references to BLOCK DATA
subprograms.
The following example shows how a BLOCK DATA subprogram might be
coded:
BLOCK DATA
COMMON /ELJ/JC,A,B/DAL/Z,Y
REAL B(4)/1.0,0.9,2*1.3/,Z*8(3)/3*5.42311849D0/
INTEGER*2 JC(2)/74,77/
END
this program initializes items in two named common areas, ELJ and
DAL:
• The REAL type statement initializes item B in ELJ and item 2
in DAL.
• The INTEGER type statement initializes item JC in ELJ.
• Because they're not included in either type statement, item
A in ELJ and item Y in DAL are not initialized.
For reference documentation about BLOCK DATA subprograms, see
the VS FORTRAN Application Programming: Language Reference
manual .
SYSTEM CONSIDERATIONS
mTT\
In order to use the subprograms you write, you must catalog them
in a library — so they're available to calling programs. How you
do this depends on the system you're using.
For VM/370-CMS considerations, see "Using VM/370-CMS with VS
FORTRAN."
Coding Calling and Called Programs
209
For OS/VS and DOS/VSE considerations, see "Cataloging Your
Object Module— DOS/VSE" in Part 2.
OVERLAYING PROGRAMS IN STORAGE
the INSERT control statement before the first OVERLAY
control statement.
When you use the overlay features of the linkage editor, you can
reduce the main storage requirements of your program by breaking
the program up into two or more segments that don't need to be in
main storage at the same time. These segments can then be
assigned the same storage addresses and can be loaded at
different times during execution of the program.
You must specify linkage editor control statements to indicate
the relationship of segments within the overlay structure.
Keep in mind, that although overlays reduce storage, they also
can drastically increase program execution time. In other words,
you probably shouldn't use overlays unless they're absolutely
necessary.
The SAVE statement has no effect on overlaid programs. That is,
when a program is overlaid by another, variable values in the
overlaid program become undetermined.
For reference documentation about overlays, see the VS FORTRAN
Application Programming- System Services Reference Supplement .
Specifying OS/VS Overlays
In OS/VS, overlay is initiated at execution time when a
subprogram not already in main storage is referred to. The
reference to the subprogram may be either a FUNCTION name or a
CALL statement to a SUBROUTINE subprogram name. When the
subprogram reference is found, the overlay segment containing |
the required subprogram is loaded — as well as any segments in its f ~~"\J
path not currently in main storage. V_y'
When a segment is loaded, it overlays any segment in storage with
the same relative origin. It also overlays any segments that are
lower (farther from the root segment) in the path of the overlaid
segment.
Whenever a segment is loaded it contains a fresh copy of the
program units that it comprises; any data values that may have
been established or altered during previous processing are
returned to their initial values each time the segment is loaded.
For this reason, you should place subprograms whose data values
must be retained for longer than a single load phase into the
root segment.
The linkage-editor control statements you use to process an
overlay load module in OS are'
• OVERLAY linkage-editor control statement — which indicates
the beginning of an overlay segment and gives the symbolic
name of the relative origin.
OVERLAY control statements are followed by object decks,
INSERT control statements, or INCLUDE control statements.
• INSERT linkage-editor control statement- — which positions
previously compiled routines, when the object decks are not
available, within the overlay structure.
The INSERT control statement gives the names of one or more
control sections (CSECTs) that are to be inserted.
To place the control section in the root segment, position /f~ ~-\ j
sJ'
210 VS FORTRAN Application Programming* Guide
INCLUDE linkage-editor control statement — which includes
control sections from libraries, if the control sections
reside in partitioned data sets or sequential data sets.
When you use an INCLUDE control statement in an overlay
program, you should position it in the input stream at the
point where the control section to be included is required.
The control sections added by an INCLUDE control statement
can be manipulated through use of the INSERT control
statement.
ENTRY linkage-editor control statement — which specifies the
first instruction of the program to be executed, giving the
name of an instruction in the root segment. Usually that name
will be either MAIN* or the
statement (if specified).
name you've given in the PROGRAM
These control statements appear in the input stream after the
//SYSLIN DD statement (or after the //LKED.SYSLIN DD statement
if you use a cataloged procedure)..
Specifying DOS/VSE overlays
/
The linkage-editor control statements you need to create an
overlay phase in DOS are!
• PHASE linkage-editor control statement — which lets you
divide your program into a number of phases.
• INCLUDE linkage-editor control statement — which lets you
specify that a module from the relocatable library i 5 to be
included in the present phase.
OVERLAY PROCEDURE? To keep from running into difficulty when
you're using multiple phases, you should develop your overlay
programs using the following procedures:
1. Select a program name for the root phase of the program, the
first four characters of which are unique in the core image
library.
2. Determine the phase structure of the program and assign
phase names, the first four characters of which are the same
as the root phase name.
3. Write the root phase to serve as a monitor, loading each of
the other phases as needed.
4. Determine the subroutine requirements for each phase.
5. If &v\y modules used are not in the root phase but in the
relocatable library, specify NOAUTO in the PHASE statement
for each phase that refers to a module appearing in a later
phase; when the PHASE statement is executed, the relocatable
library is not searched and the later phases are not loaded.
You must explicitly specify each subsequent phase in an
INCLUDE control statement for the root phase.
USING THE CALL OPSYS STATEMENT: Within the FORTRAN program, when
you want to have a phase loaded, issue a CALL to the library
routine OPSYS. Your program must do this before you invoke the
SUBROUTINE or FUNCTION that you want to execute.
Coding Calling and Called Programs
211
For example* to load and execute subprograms PHASE4 and PHA5E6,
you specify J
CALL OPSYSCLOAD* , 'PHASE* ')
CALL PHASE4(A,B)
CALL 0PSYS('L0AD f ,»PHASE6
CALL PHASE6(D)
These CALL 0P5YS statements result in the phases named PHASER and
PHASE6 being loaded. (The phase name in the CALL OPSYS statement
is always eight alphameric characters, with the name
left-adjusted within the field and padded on the right with
blanks = )
The CALL PHASE* and CALL PHASE6 statements cause the subprograms
PHASE* and PHASE6 to be executed.
For reference documentation about the CALL OPSYS statement, see
the VS FORTRAN Application Programming? Language Reference
manual .
Note: You must explicitly identify the OPSYS service routine by
its library module name (IFYOPSYS) and supply a linkage editor
INCLUDE statement using this name to get the OPSYS module
included into the root phase.
O-
O
212 VS FORTRAN Application Programming* Guide
c
USING THE OPTIMIZATION FEATURE
When you use the 0PTIMIZEC1/2/3) options* you "can get faster
program execution. However* when you use these options* you
should be aware of programming practices that can help or hinder
optimization.
Some of the suggestions ere obvious* some ar^ not. However* it's
easy to forget even the obvious ones when you're developing or
revising programs over a period of time.
The following paragraphs suggest ways you can make your programs
use the OPTIMIZE features to best advantage.
SELECT THE HIGHER OPTIMIZATION LEVELS
In general* you should select the highest level of optimization
The higher the optimization level you select, the longer the
compilation time* however* both object program storage and
execution time are reduced.
Very few iterations through most subroutines can cause
optimization savings to exceed optimized compilation cost.
You should use NOOPTIMIZE or OPTIMIZE(l) only for testing
purposes. For example, they're useful if you want to check the
syntax of the program without executing it* or to debug a
subroutine that doesn't iterate correctly.
Whenever you can* however, you should choose either 0PTIMIZEC2)
or 0PTIMIZEC3) for most programs.
WRITE PROGRAMS OF EFFICIENT SIZE
USE UNFORMATTED I/O
For efficient optimization* programs can be either too large or
too small.
Keep programs smaller than 8*192 bytes in size. Programs larger
than this cause the compiler to remove an address from
optimization and reserve it as a program address register.
Don't write subroutines that perform a small amount of work. The
work done by a small subroutine can be lost in the cost of
calling it. Instead* you should code such subroutines directly
into the main program. This lets the compiler optimize the
operations in the subroutine together with those of the main
program.
Unformatted I/O takes less processing time and uses less storage
than formatted I/O. Unformatted I/O also exactly maintains the
precision of the data items you're processing.
With formatted I/O* each data element is converted between
internal and external format. This takes time and storage. In
addition* rounding errors can accumulate during conversion.
USE ARRAY OPERANDS FOR I/O TRANSFERS
In a READ or a WRITE statement* each operand is interpreted
individually by the data transfer routines. (This is true for
both unformatted and formatted I/O.)
Using the Optimization Feature
213
By using an array operand without subscripts, you can read or
write an entire array with a single operand.
You can also transfer a subset of an array by specifying an
implied DO loop. For example:
(A(I),I=11,99)
which transfer elements 11 through 99 of the array A.
However, when you use implied DO loops in this way, keep the
subscript expressions simple. Don't interleave elements from
several arrays in one implied DO loop; instead, write each array
subscript in a separate implied loop. For example*
CCA(I),B(I),C(I)I=11,99)
requires one call to the I/O subroutines for each array element,
but
(A(I),I=11,99),(B(I),I=11,99),(C(I),I=11,99)
requires only three such calls for the entire array.
USE LOGICAL VARIABLES OF LENGTH 4
LOGICAL variables of length 4 can be accessed directly without
clearing a register.
IBM EXTENSION 1
Every reference to a L0GICAL*1 variable causes a register to be
cleared before the variable is accessed. In some situations,
the compiler allocates a register throughout an entire loop
for this purpose; if not, it must at least generate an extra ^ N |
instruction. ( y
END OF IBM EXTENSION '
USE INTEGER VARIABLES OF LENGTH *
INTEGER variables of length 4 are optimized by strength
reduction; they're also generated into branch-on-i ndex
instructions. You should always use INTEGER variables of length
4 for DO loop indexes.
I IBM EXTENSION
INTEGER*2 variables are not optimized by strength reduction,
and they aren't generated into branch-on-i ndex instructions.
Therefore, they're less efficient than INTEGER*^ variables.
END OF IBM EXTENSION
ELIMINATE EQUIVALENCE STATEMENTS
Equivalenced variables often cannot be optimized. Optimization
can't be performed for a variable equi valenced to another
variable of a different type (for example, logical to integer),
or for a scalar variable equivalenced to an array.
INITIALIZE LARGE ARRAYS DURING EXECUTION
If you initialize large arrays using a DO loop, you get faster
execution and you use less storage than if you initialize using a
DATA statement.
For example, the following statements?
214 VS FORTRAN Application Programming* Guide
Xjr'
DOUBLE PRECISION AC5000)
DATA A(5000)/5000*0.0/
generate 40 , 000 bytes of object module information — more than
500 TXT cards. The 40,000 zeros must be placed in the object
module by the compiler, placed in the load module by the linkage
editor, and fetched into storage when you execute the program.
USE COMMON BLOCKS EFFICIENTLY
Each reference to a variable in COMMON requires that the address
of the COMMON block be in a register. The following
recommendations are based on this fact.
1. Don't use multiple COMMON blocks. The following example
shows why •
Three Registers One Register
Required: Required:
COMMON /X/ A COMMON /Q/ A,B,C
COMMON/Y/ B A=B+C
COMMON /!/ C
A = B + C
As the example shows, you should group concurrently
referenced variables into the same COMMON block.
2. Place scalar variables before arrays in a given COMMON
block. The following example shows whys
Two Registers Required: One Register Required:
COMMON /Z/ X(5000),Y COMMON /Z/ Y, XC5000)
X(1)=Y X(1)=Y
In the same way, you should place small arrays before large
ones. All the scalar variables and the first few arrays can
then be addressed through one address constant. The
subsequent larger arrays will probably each need a separate
address constant.
3. If a scalar variable in a COMMON block is frequently referred
to, assign it from the COMMON block into a local variable.
References to the local variable will not then require that
the COMMON block address be in a register.
If you do this, always remember that changing the local
variable does not change the COMMON variable.
PASS SUBROUTINE ARGUMENTS IN COMMON BLOCKS
If you pass subroutine arguments in a COMMON block rather than as
parameters, you'll avoid the overhead of moving each argument
between the parameter list and local storage.
You must evaluate the effect of placing parameters into common
for both the calling and the called routine.
DON'T USE VARIABLY DIMENSIONED ARRAYS
Subscripting of variably dimensioned arrays requires additional
indexing computations. In addition, if you use a variably
dimensioned array as a subroutine parameter, there are
additional calculations that must be performed on each entrance
into the subroutine.
You can lessen the amount of extra processing, however, in the
f ollowi ng ways 5
Using the Optimization Feature 215
1. If the location and size of the array do not change during
repeated calls to the subroutine* you can insert an
initialization call to the subroutine to define the array;
subsequent execution calls need not then refer to the array*
as the following example shows?
\
Dimensions Calculated
Once:
Dimensions Calculated
At Each Entrance:
Main Program
CALL INIT(A,I,J)
DO 1 N=l*10
CALL EXEC
Main Program
DO 1 N=l,10
CALL EXEC(A*I*J)
Subprogram
SUBROUTINE INIT(A*I,J)
REAL*8 A(I,J)
RETURN
ENTRY EXEC
Subprogram
SUBROUTINE EXECCA*I*J)
REAL *8 ACI*J)
2. Make the variable dimensions of an array the high-order
dimensions* if the indexing can be varied in the low-order
dimensions. This reduces the number of computations needed
for indexing the array* as the following example shows'-
Computation not
Required:
SUBROUTINE EXEC(Z*N)
REAL *8 Z(9,N)
Z(I,5)=A
Computation (IXN)
Required:
SUBROUTINE EXEC(Z,N)
REAL *8 ZCN,9)
ZC5,I)=A
WRITE CRITICAL LOOPS INLINE
( )
If your program has a short heavily-referenced DO loop* it's
probably worth the effort to remove the loop and expand the code
inline in the program. Each loop iteration will execute faster.
ENSURE RECOGNITION OF DUPLICATE COMPUTATIONS
If components of a computation are duplicates* make sure you code
the duplicate elements in one of the following ways:
• At the left end of the computation
• Uithin parentheses
The compiler must follow the left-to-right FORTRAN rules* and
this order of computations follows those rules.
The following examples illustrate this concept*
Duplicates Recognized: No Duplicates Recognized:
A=B*(X*Y*Z)
C=X*Y*Z*D
E=F+(X+Y)
G=X+Y+H
A=B*X*Y*Z
C=X*Y*Z*D
E=F+X+Y
G=X+Y+H
In the pair of examples at the left* the compiler can recognize
X*Y*Z and X+Y as duplicates because they're either coded in
parentheses or coded at the left end of the computation. In the
pair of examples at the right* these rules aret not followed* and
therefore the compiler cannot recognize these duplicates.
216 VS FORTRAN Application Programming: Guide
ENSURE RECOGNITION OF CONSTANT COMPUTATIONS
In a loop, when several components of a computation are constant,
ensure that they can be recognized by following one of these
coding rules*
1. Move all the constant computations to the left end of the
computation.
2. Group constant computations within parentheses.
The compiler follows the left-to-right FORTRAN rules, and this
order of computations allows the compiler to recognize the
constant portions of the computations.
If C, D, and E are constant and V, Ul, and X are variable, the
following examples show the difference in evaluation*
Constant Computations Constant computations
Recognized Not Recognized
V*W*X*(CXD*E) V*W*X*C*D*E
C+D+E+V+W+X V+W+X+C+D+E
EN3URE RECOGNITION OF CONSTANT OPERANDS
The compiler can recognize only local variables as having a
constant value. (It must always assume that operands in common or
in a parameter list can change, and therefore cannot optimize
them. )
Therefore, for such items you should define constant operands as
local variables.
ELIMINATE SCALING COMPUTATIONS
If your program performs calculations representing physical
values of some kind, you can save computation time by using
factoring, as the following simple example shows*
Not Using Factoring Using Factoring
SUM=0.0 SUM=0.0
DO 1 1=1,9 DO 1 1=1,9
1 SUM=SUM+FAC*ARR(I) 1 SUM=SUM+ARR( I)
SUM=SUflxFAC
In many programs, you can use factoring much more extensively
than this simple example shows.
DEFINE ARRAYS WITH IDENTICAL DIMENSIONS
If all your arrays have the same shape, then the compiler can use
a subscript calculated for one array to subscript the others.
In some cases, therefore, you should consider expanding some
smaller arrays to match the dimensions of the other arrays with
which they're involved. The compiler can then maintain only one
index for all the arrays defined as having the same dimensions.
DEFINE ARRAYS NITH IDENTICAL ELEMENT SPECIFICATIONS
If you define arrays as having the same dimensions and the same
element specifications, the compiler can compute a subscript for
one array and then use it without change for the others.
In some cases, therefore, you should consider expanding smaller
arrays to match the elements in the others. You should always do
this for arrays with integer or logical operands.
Using the Optimization Feature 217
USE CRITICAL VARIABLES CAREFULLY
Certain variables cannot be optimized in certain circumstances*
• Control variables for direct access input/output data sets
cannot be optimized at all.
• Variables in input/output statements and in argument lists
cannot be optimized by register optimization in the loops
that contain the statements.
• Variables in COMMON blocks cannot be optimized across
subroutine calls.
You shouldn't use DO loop indexes for any of these purposes.
AVOID UNNEEDED FIXED/FLOAT CONVERSIONS
Avoid forcing the compiler to convert numbers between the
integer and the floating-point internal representations; each
such conversion requires several instructions* including some
double-precision floating-point arithmetic.
The following example shows one method of avoiding such
unnecessary conversions*
One Conversion Needed: Multiple Conversions Needed:
x=i.o
DO 1 1=1,9 DO 1 1=1,9
A(I)=A(I)*X 1 A(I)=A(I)*I
1 X=X+1.0
When you can't avoid using mixed-mode arithmetic, then code the
fixed-point and floating-point arithmetic as much as possible in
separate computations.
MINIMIZE CONVERSIONS BETWEEN SINGLE AND DOUBLE PRECISION
Two, or even three, instructions are required to convert data
between single and double precision.
USE SCALAR VARIABLES AS ACCUMULATORS
When you're accumulating intermediate summations, keep the
result in a scalar variable rather than in an array. Array
accumulators require load and store instructions; scalar
variable accumulators can be maintained in a register.
USE EFFICIENT ARITHMETIC CONSTRUCTIONS
Wherever possible, change subtractions into additions and
divisions i nto mult i p.li cati ons.
In subtraction operations, if only the negative is required,
change the subtraction operations into additions, as follows
Efficient: Inefficient:
Z=-2.0
DO 1 1=1,9 DO 1 1=1,9
1 A(I)=A(I)+Z*B(I) 1 A(I)=A(I)-2.0*B(I)
218 VS FORTRAN Applicati on Programming: Guide
In division operations* do the following:
• For constants, use one of the following constructions:
X*(l. 0/2.0)
0.5*X
rather than the construction X/2.0.
• For a variable used as a denominator in several places, use
the same technique.
USE IF STATEMENTS EFFICIENTLY
In general, use the logical IF statement rather than the
arithmetic IF statement.
If you must use an arithmetic IF statement, try to make the next
succeeding statement one of the branch destinations.
For multiple branches, either use the computed GO TO statement,
or, if the branch can be initialized so that it remains
invariant, use an assigned GO TO statement.
In logical IF statements, if your tests involve a series of AND
and/or OR operators, try to do the following*
• Put the simplest conditions tested in the leftmost
posi ti ons.
• Also, put the tests most likely to be decisive in the
leftmost positions.
• Put the more complex conditions (such as tests involving
function references) in the rightmost positions.
If the first part of the expression causes the logical condition
to test as true, then the rest of the expression need not be
evaluated, saving execution time.
USE THE OBJECT PROGRAM LISTING
Use the object program listing, which you obtain through the LIST
compiler option, to find out what machine instructions the
compiler has generated for your program. You can often tell
whether the program has been well or poorly optimized.
The essential work for most FORTRAN programs is to compute
floating-point numbers (rather than subscripts or DO loop
indexes). Take a quick look at the inner loops for such programs;
if they contain essentially no fixed-point instructions, the
program is efficiently optimized.
Similarly, you can tell from a FORTRAN source program which
additions and multiplications and other operations are necessary
and which ought to disappear under optimization. You can examine
the object program to discover whether there's a reasonable
correlation between the generated program and your expectation.
Using the object code listing in this way, is the best way you
can study the efficiency of source program optimization.
Neither of these examinations requires detailed knowledge of
assembler language.
SOURCE CONSIDERATIONS UITH OPTIMIZED)
When you're using the 0PTIMI2E(3) compi ler opti on, there are
additional coding considerations you should be aware of.
Using the Optimization Feature 219
COMMON EXPRESSION ELIMINATION — OPTIMIZEC3)
0PTIMIZE(3) evaluates expressions and eliminates those that ar& (C^)-
cotnmon to more than one statement. That is, if an expression %Jr
occurs more than once and the path of execution always executes
the first expression and then the second, with no change in the
expression value, the first value is saved and used instead of
the second expression. 0PTIMIZE(3) does this even for
intermediate expressions within expressions. For example, if
your program contains the following statements:
10 A=C+D
20 F=C+D+E
the common expression C+D is saved from its first evaluation at
10, and is used at 20 in determining the value of F.
COMPUTATIONAL REORDERING — 0PTIMIZE13)
0PTIMIZE(3) may move an expression outside of a loop when the
operands of the expression ar& not defined as part of the loop.
This can cause execution differences from nonoptimized code.
For example, when an IF statement controls the execution of a
computation within a loop, and the computation is moved outside
the loop, program execution results may change?
DO 11 1=1,10
DO 12 J=l,10
9 IF (B(I).LT.O) GO TO 11
12 C(J)=SQRT(B(D)
11 CONTINUE
0PTIMIZEC3) moves the library function call to precede statement WV
9, which causes the square root computation to be made before the
test for zero.
To avoid this unwanted code movement, use the 0PTIMIZEC2)
opt i on.
You can also get unexpected results when you use CALL OVRFL or
CALL DVCHK, because the computations causing overflow,
underflow, or divide check conditions could be moved out of the
loop in which the test occurs.
INSTRUCTION ELIMINATION— OPTIMIZE( 3 J
If your program defines nonsubscri pted variables, and their
values are not used between two definitions within one block, or
have not been used before the exit from the block, the compiler
may eliminate any intermediate storing of the variables.
This can cause a change in execution logic if, for example, you
initialize the variables just before issuing a READ statement*
1=7
J=8
K = 9
READ (8,*,END=1) I,J,K
WRITE (6,*) I,J,K
1 END
G
220 VS FORTRAN Application Programming: Guide
0PTIMIZEC3) considers the READ statement as a redefinition of I,
J, and K, and the END statement delimits the block; therefore*
the instructions usually generated to store I, J > and K are
eliminated by the compiler. During execution, if the READ
statement terminates normally before reading into all three
variables, those not read into are not initialized. (If you omit
the END and/or the ERR parameters, the store instructions are not
eliminated.)
f*%.
Using the Optimization Feature 221
USING THE EXECUTION-TIME LIBRARY
The VS FORTRAN execution-time library contains intrinsic
function routines* and subprogram routines for error handling
and service functions. There are several kinds of routines
avai lable:
Mathematical and Character Functions — mathematical and
character routines that are either inline functions or
subroutine functions.
Service Routines — these subprogram routines test for
mathematical exceptions or terminate execution.
Error Routines — these subprograms handle errors
automatically; you can also control error handling directly.
Each category is explained more fully in the following sections.
MATHEMATICAL AND CHARACTER FUNCTIONS
These routines provide intrinsic functions you can use in
mathematical and character operations. There are several
categories of mathematical and character functions*
Logarithmic and exponential routines
Trigonometric routines
Hyperbolic function routines
Miscellaneous mathematical routines
Character manipulation routines
When your VS FORTRAN program requests an intrinsic function* the
routine is either-
• Inserted inline into the program, or
• Included in the load module as a called subroutine during
1 i nk-edi ti ng .
You can use the generic name for a function; VS FORTRAN will then
select the particular function you need, depending upon the
precision of the data you're using.
You can, alternatively, use the name of the specific alternative
entry point you want to use. A prefix to the generic name
specifies an alternative entry point.
See the VS FORTRAN Application Programming? Library Reference
manual for a description of the mathematical and character
functions, and for names of generic functions and their
alternative entry points.
SERVICE ROUTINES
These routines give you control over certain mathematical
exceptions and over program termination when unusual conditions
occur. Using the service routines, you can perform the following
functions?
CALL OVRFLW — Test for exponent overflow or underflow and
return a value indicating the condition that exists.
.^ ^
o
222 VS FORTRAN Application Programming: Guide
CALL DVCHK — Test for a divide-check exception and return a
value indicating the condition that exists.
CALL EXIT — Terminate load module execution and return
control to the operating system.
CALL DUMP/PDUMP — Dynamically dump a specified area of
storage and either terminate (CALL DUMP) or continue
execution (CALL PDUMP). You can specify the format of the
output.
CALL CDUMP/CPDUMP — Dynamically dump a specified area of
storage, in character format, and either terminate (CALL
CDUMP) or continue execution (CALL CPDUMP). The output is
always in character format.
These routines are described in the VS FORTRAN Application
Programming' Library Reference manual.
Reference documentation for these routines is given in the VS
FORTRAN Application Programming? Language Reference manual.
ERROR-HANDLING ROUTINES
The library supplies two kinds of error-handling support*
automatic error handling during compilation or execution, and
error handling under your control.
Automatic Error Handling
f\
During compilation, if the compiler detects an S-level error, it
inserts a call for a library function instead of generating the
code for the statement; during execution, if and when this
statement in the program is reached, an error message (including
the internal statement number) is written and the program is
termi nated.
During program execution, the library issues messages when the
following program interrupts occur:
Operation
Fixed-point divide
Decimal divide
Floating-point divide
Exponent overflow
Exponent underflow
Error Handling Under Your Control
In addition, the execution-time error-handling routines give you
dynamic control over:
• The number of times an error can occur before your program is
terminated
• The maximum number of times a message is printed
• If a traceback map i s to be printed with the message
• If your organization's error routine is to be called
You specify dynamic error control during your program's
execution through?
• CALL ERRMON — causes execution of the error monitor.
Using The Execution-Time Library
223
• CALL ERRSAV — copies an option table entry into an area
accessible to your program.
• CALL ERRSET — changes up to five values associated with an ^y
entry in the option table (for example, the number of errors
permitted or number of messages to be printed).
• CALL ERRSTR — stores an entry into the option table from your
program.
• CALL ERRTRA — causes execution of the error trace routines.
For a description of how you use these routines, see "Fixing
Execution-Time Errors — Advanced Programming" in Part 2.
Reference documentation for these routines is given in the VS
FORTRAN Application Programming* Language Reference, manual.
?
V.-^
v
224 VS FORTRAN Application Programming: Guide
APPENDIXES
This section contains appendixes documenting the following
auxiliary VS FORTRAN material:
• Appendix A — Device Information
• Appendix B — Assembler Language Considerations
Appendixes 225
APPENDIX A. DEVICE INFORMATION
This appendix gives information regarding specific input/output
devices that can be used with a VS FORTRAN program.
MINIMUM AND MAXIMUM BLOCK SIZE VALUES
Device
Type
Fixed
Block
and Undefin
Size (Bytes
Minimum
Maximum
Card Reader
1
80
Card Punch
l
81
Printer Line Len
(1403, 3800, etc
120 characters
132 characters
144 characters
150 characters
gth
.)
1
l
1
1
121
133
145
151
Magnetic Tape
18
32760
Direct Access
2314
3330
3340
3350
1
1
1
1
7294
13030
8368
19069
The minimum and maximum block sizes that can be specified for
specific devices are shown in Figure 47.
Variable Records
Block Size (Bytes)
Minimum
Maximum
9
80
9
89
9
9
9
9
129
141
153
159
18 32760
9
7294
9
13030
9
8368
9
19069
Notes:
1. For DOS/VSE Fixed Block Architecture devices, see the manuals describing the
devices you*re using.
2. For direct access devices with the track overflow feature, the maximum is 32760
for each devi ce.
Figure 47. VS FORTRAN Devices — Minimum and Maximum Block Sizes
Q
)
226 VS FORTRAN Application Programming? Guide
DIRECT ACCESS DEVICE CAPACITIES
■^k^J^
o
The capacities of specific direct access devices are shown in
Figure 48.
Device
Type
Track
Capacity
Tracks per
Cylinder
Number of
Cylinders
Total
Capacity
2314(2319)
7294
20
100
19.176,000
3330
13030
19
404
101,751,270
3330-11
13030
19
808
203,502,340
3340
8535
12
348
34,944,768
3350
19254
30
815
317,498,850
Notes:
• •
1. For DOS/VSE Fixed Block Architecture devices, see the manuals describing the
devices you're using.
2. For the 3375 and 3380 devices, device information will be provided after the
devices are available.
Figure 48. Direct Access Device Capacities
Appendix A. Device Information 227
APPENDIX B. ASSEMBLER LANGUAGE CONSIDERATIONS
You can use assembler language subprograms with your FORTRAN
main programs. In your FORTRAN programs, you can invoke the
assembler subprogram in either of two ways: through CALL
statements or through function references in arithmetic
expressions.
This appendix describes the linkage conventions you must use in
such assembler language subprograms to communicate with the
FORTRAN program.
For documentation about assembler language programs, see:
QS/VS; DOS/VS; and VM/37Q Assembler Language ,' GC-33-6010
05/VS, VM/370 Assembler Programmer* s Guide , GC33-4021
Guide to the DOS/VSE Assembler , GC33-4024
SUBPROGRAM REFERENCES IN FORTRAN
For each subprogram reference, the compiler generates:
• A contiguous argument list containing the addresses of the
arguments; this makes the arguments accessible to the
subprogram.
1 '
THE ARGUMENT LIST
If the calling program was compiled with LANGLVL(77), and if
any arguments in the call to the assembler language
subprogram are of character type, there will be two items in
the argument list for each character argument. The first
item is the address of the start of the character argument,
and the second is the address of the length of the character
argument contained in the full word. If the passed length is
needed in the assembler subprogram, then, when the arguments
are fetched from the parameter list, the length argument
must be received; otherwise, the length argument must be
skipped over. The generation of the length address may be
suppressed for LANGLVLC77) by using the SC compile option.
See the section "SCCnamel ,name2, . . . )" under "Using the
Compile-Time Options" on page 72.
A save area in which the subprogram can place information
about the calling program.
A calling sequence to pass control to the subprogram, using
standard linkage conventions.
The argument list contains addresses of variables, arrays, and
subprogram names used as arguments.
Each entry in the argument list is four bytes long and is aligned
on a fullword boundary. The last three bytes of each entry
contain the address of an argument. The first byte of every entry
except the last contains zeros; in the first byte of the last
entry, the sign bit is set to binary 1.
The calling program places the address of the argument list in
general register 1.
Q)
228 VS FORTRAN Application Programming: Guide
THE SAVE AREA
The calling program contains a save area in which the subprogram
places information 5 the entry point for this program* the
address to which the subprogram returns* general register
contents* and addresses of save areas used by programs other than
this subprogram.
The calling program reserves 18 words of storage for this area.
The calling program places the address of the save area in
general register 13.
THE CALLING SEQUENCE
The FORTRAN compiler generates a calling sequence to transfer
control to the subprogram* placing the following addresses in
the following registers*
• Register 13 — the address of the save area.
• Register 1 — the address of the argument list. (If there is no
argument list* (zero) is placed in general register 1.)
• Register 15 — the entry address.
• Register 14 — the return address.
The program then branches to the address in general register 15.
You can also use register 15 as a condition code register* and as
a RETURN and STOP code register. The values you should use for
these codes are-*
16 for a terminal error detected during subprogram
execution. (A FORTRAN message is also generated.)
when a RETURN or STOP statement is executed in the
subprogram.
4x1 when a RETURN i statement is executed in the
subprogram.
n when a STOP n statement is executed in the subprogram.
LINKAGE IN ASSEMBLER SUBPROGRAMS
You can use two types of assembler subprograms*
Called Subprograms — that is* assembler language subprograms
that don't call another subprogram.
Called and Calling Subprograms — that is* assembler language
subprograms that do call another subprogram.
The rules for coding such subprograms are somewhat different* so
they are documented in separate sections following.
CALLED ASSEMBLER SUBPROGRAMS
For assembler subprograms that don't call other subprograms* you
must include the following linkage instructions*
1. An instruction naming the entry point for this subprogram.
2. Instructions to save any general registers this subprogram
^p^ uses in the save area reserved by the calling program. (You
■ T) don't need to save the contents of linkage registers and
Appendix B. Assembler Language Considerations 229
3. Before returning control to the calling program*
instructions to restore the saved registers. ^~. •
4. An instruction setting the first byte of the fourth word in %J?
the save area to ones, to indicate return of control to the
calling program.
5. An instruction returning control to the calling program.
In addition to these instructions* if arguments are passed, the
assembler subprogram must transfer the arguments from the
calling program and return the arguments to the calling program,
using the address passed in general register 1.
CALLED AND CALLING ASSEMBLER SUBPROGRAMS
MAIN PROGRAMS
A called and calling assembler language subprogram must contain
the same linkage instructions as a called subprogram; it must
also simulate the FORTRAN linkage conventions for calling
subprograms. Therefore, it must also include 2
• A save area and instructions to place entries into its save
area
• A calling sequence and parameter list for the subprogram it
i s calli ng
• An instruction indicating an external reference to the
subprogram it is callin.i
• Additional instructions in the return routine to retrieve
entries from the save area
If the main program is not a FORTRAN main program, you must V>
establish certain FORTRAN linkages after you've established the
save area and before you call the FORTRAN subroutine..
The assembler instructions you must code to establish the
li nkages are'
LR X,13 (where X is any register 2 through 12
to SAVE register 13)
L 13,4(13)
L 15,=V(VSC0M#)
BAL 14,64(15)
LR 13, X (where X is the same as above)
The linkages you establish cause initialization of return coding
and interrupt exceptions, as well as opening of the error message
data set.
If you don't do this and the FORTRAN subprogram terminates in
error or with a STOP statement, any open FORTRAN data sets are
not closed, and the results of the program termination are
unpredictable.
USING FORTRAN DATA IN ASSEMBLER SUBPROGRAMS
Your assembler language subprograms can use data defined in
FORTRAN subprograms, either data contained in common areas or in
argument li sts.
USING COMMON DATA IN ASSEMBLER SUBPROGRAMS
Assembler language subprograms can access data in both blank and
named common areas.
o
230 VS FORTRAN Application Programming: Guide
Using Blank common Data in Assembler Programs
To refer to the blank common area* the assembler language program
must also define a blank common area* using the COM assembler
instruction. Only one blank common area is generated* and the
data it contains is available both to the FORTRAN program
containing the blank COMMON statement and to the assembler
language program containing the COM statement.
In the assembler language program* you can specify the following
1 i nkage?
COM
name DS OF
L ll,=A(name)
USING name*ll
Using Named Common Data in Assembler Programs
To refer to named common areas* your assembler program can use a
V-type address constant:
name DC VCname of common area)
RETRIEVING ARGUMENTS IN AN ASSEMBLER PROGRAM
The argument list contains addresses of variables* arrays* and
program statement labels used as arguments.
Each entry in the argument list is four bytes long and is aligned
on a fullword boundary. The last three bytes of each entry
contain the address of an argument. The first byte of every entry
except the last contains zeros; in the first byte of the last
entry, the sign bit is set to binary 1.
The calling program places the address of the argument list in
general register 1.
Retrieving Variables from the Argument List
The argument list contains the address of a variable. The
assembler program can retrieve the variable using the following
i nstructi ons'>
I Q*x(l)
MVC L0C(y)*z(Q)
where •*
Q is any general register except 0. „
LOC is the location that will contain the variable.
X is the displacement of the variable from the start of
the argument 1 i st.
y is the length of the variable itself.
Z is either or the displacement to correct the value
for an array element.
For example, if a REAL*8 variable is the second item in the
argument list* you could code the following assembler
instructions to retrieve it :
L 5*4(1)
MVC LOC(8),0(5)
Appendix B. Assembler Language Considerations 231
Retrieving Arrays and Array Elements from the Argument List
The address of the first element of an array is placed it« the W_y
argument list. If you must retrieve any other elements in the
array, you must specify the displacement for that element from
the beginning of the array?
L Q,xCl)
L R,disp
L S,0CQ,R)
ST S,L0C
where?
Q and R are any general registers except 0.
disp is the displacement of the element within the array.
w 13 any yenei a* ■ ey i ^>vci •
LOC is the location that will contain the array element.
Returning to Alternative Return Points
To simulate the FORTRAN subprogram RETURN Stn statement,
however, the assembler program can place the value?
4*stn
in general register 15, where stn is the actual argument position
to which return i s to be made.
For example, to return to the second statement in the actual
argument list, the assembler language program must contain?
LA 15,8 O
INTERNAL REPRESENTATION OF FORTRAN DATA
If you're using FORTRAN data in your assembler language
programs, you should be aware of the formats FORTRAN uses within
the computer.
The following examples show how FORTRAN data items appear in
internal storage.
CHARACTER Items in internal storage
CHARACTER items are treated internally as one EBCDIC character
for each character in the item.
LOGICAL Items in Internal Storage
LOGICAL items are treated internally as items either 1 byte or 4
bytes in length. Their value can be "true" or "false".
Their internal representation in hexadecimal notation is?
232 VS FORTRAN Application Programming? Guide
^ I IBM EXTENSION
i'K]
1 byte
"true"
"false"
END OF IBM EXTENSION
[::::i::::i::::i::::]
| 00 | 00 | 00 | 01 | "true"
. _ _ T .. | 00 | 00 | 00 | 00 | "false 1
L 1 X 1 J < 4 bytes >
INTEGER Items in internal Storage
INTEGER items are treated internally as fixed-point signed
operands, either 2 bytes or 4 bytes in length.
Their internal representation is*
I — IBM EXTENSION
INTEGER *2
[!i:z;i:::::::::;]
gT^ < 2 bytes >
END OF IBM EXTENSION
INTEGER *4
[si """"""""""" J™!
< 4 bytes-
S = the sign bit
REAL Items in Internal Storage
The compiler converts REAL items into 4-byte, 8-byte, or 16-byte
floating-point numbers.
Their internal representation is*
REAL X4
[sTc~Tf~~| I™"]
< 4 bytes >
DOUBLE PRECISION (REAL *8)
[sTc~Tf~"T I I I ™7_ l_ ]
< g bytes >
For REAL *4 and DOUBLE PRECISION items, the codes shown are:
Appendix B. Assembler Language Considerations 233
S = sign bit (bit 0)
C = characteristic (or exponent) > in bit positions 1 through 7
F = fraction* which occupies bit positions, as follows:
REAL *4 positions 8 through 31
DOUBLE PRECISION positions 8 through 63
\J"
IBM EXTENSION
REAL *16 (Extended Precision)
■//■
S| C |F | // |
|S| C | F
— // —
I // I
•//■
•//•
64
16 bytes-
72
For Extended Precision Items, the codes are!
F =
sign bit (sign for the item in bit 0; a + sign in bit 64)
characteristic (or exponent), in bit positions 1 through 7
and 65 through 71 (the value in bit positions 63 through 71
is 14 less than that in bit positions 1 through 7)
fraction, in bit positions 8 through 63, and 72 through 127
END OF IBM EXTENSION
COMPLEX Items in internal storage
The compiler converts COMPLEX items into a pair of REAL numbers.
The first number in the pair represents the real part; the second
number in the pair represents the imaginary part.
The internal representations of COMPLEX numbers are :
COMPLEX *8
\H--jy-
(real)
(imag. )
S| C | F | |
S| V |T"j |
L____ I
< 4 bytes >
For COMPLEX *8 items, the codes shown are'
S = sign bit (bit 0)
C = characteristic (or exponent), in bit positions 1 through 7
F = fraction, which occupies bit positions 8 through 31
IBM EXTENSION
COMPLEX *16
S| C | F |
sTc~Tf"T
COMPLEX *32
I
■8 bytes-
(real)
( imag. )
// //
S| C | F | // I |S| C | F | // |
SI C | F | // | |S| C I F | // |
8 64 72
< 16 bytes >
(real)
( imag. )
o
234 VS FORTRAN Application Programming! Guide
For COMPLEX *16 items, the codes shown are:
S = sign bit (bit 0)
C = characteristic (or exponent), in bit positions 1 through 7
F = fraction, which occupies bit positions 8 through 63
For COMPLEX *32 Items, the codes are:
S = sign bit (sign for the item in bit 0; a + sign in bit 64)
C = characteristic (or exponent), in bit positions 1 through 7
and 65 through 71 (the value in bit positions 63 through 71
is 14 less than that in bit positions 1 through 7)
•F = fraction, in bit positions 8 through 63, and 72 through 127
END OF IBM EXTENSION •
Appendix B. Assembler Language Considerations 235
\J
APPENDIX C. DIFFERENCES BETWEEN VS FORTRAN AND CURRENT IMPLEMENTATIONS
In VS FORTRAN, operands of logical typo ara not permitted with
relational operators. FORTRAN H and FORTRAN H Extended permit
this nonstandard usage. Under LANGLVL(66), this nonstandard
usage is accepted and a warning message is issued.
In VS FORTRAN* operands of logical type are not permitted with
arithmetic operators. FORTRAN H and FORTRAN H Extended permit
this nonstandard usage.
The Extended Language features permitted with use of the XL
option from FORTRAN H and FORTRAN H Extended are not supported in
VS FORTRAN.
In VS FORTRAN* the DEBUG statement and the debug packets precede
the program source statements. The new END DEBUG statement
delimits the debug-related source from the program source. For
FORTRAN Gl, the DEBUG statement and the debug packets are placed
at the end of the source program.
In VS FORTRAN, evaluation of arithmetic expressions involving
constants is performed at compile time (including those
containing mixed-mode constants).
In VS FORTRAN, the number of arguments is checked in statement
function references. The mode of arguments is checked for
statement function references under LANGLVLC77) option only.
In VS FORTRAN, the form of the compiler option to name a program
is NAME(nam) under LANGLVLC66).
Arguments are received only by location (or name) in ( )
LANGLVK77). The default in LANGLVLC66) and for FORTRAN H and W
FORTRAN H Extended is receipt by value with the facility to allow
receipt by name by the use of slashes around the dummy argument
in the SUBROUTINE, FUNCTION, or ENTRY statements.
The appearance of an intrinsic function name in a conflicting
type statement has no effect in LANGLVL(77), but is considered
user-supplied under LANGLVL(66) and FORTRAN H and FORTRAN H
Extended.
Direct access files must be Preformatted when using LANGLVL(77).
This is done by the DEFINE FILE statement under LANGLVL(66),
FORTRAN Gl, FORTRAN H, and FORTRAN H Extended. (The reason for
this is that there is no provision in the OPEN statement for the
number of records to be contained in the file as there is in the
DEFINE FILE statement.)
The use of a scale factor with an integer format specifier is
considered a severe error by VS FORTRAN, but is accepted by
FORTRAN Gl, FORTRAN H, and FORTRAN H Extended.
For an implied DO in an input/output list with a variable
incrementation value that is assigned a value of zero at
execution time*
• VS FORTRAN and FORTRAN Gl do not diagnose this invalid case
and the program loops.
• FORTRAN H Extended makes its diagnoses at execution time.
In a standard DO-loop, FORTRAN Gl, FORTRAN H Extended, and VS
FORTRAN under LANGLVL(66) all loop. VS FORTRAN under
LANGLVL(77) bypasses the loop, because it does not meet the
standard requirements for execution.
o :)
236 VS FORTRAN Application Programming* Guide
In VS FORTRAN* when a variable has been initialized with a DATA
statement* that variable cannot appear in an explicit type
statement and a severe level diagnostic is issued. FORTRAN H and
FORTRAN H Extended allow typing following the data
initialization. This is nonstandard usage. FORTRAN Gl issues a
level 8 error diagnostic.
The record designator for direct-access I/O is required to be an
integer expression for both LANGLVLC66) and LANGLVLC77). If it
is not* VS FORTRAN diagnoses with a level 12 error message.
FORTRAN H and FORTRAN H Extended permit this designator to be of
real type. FORTRAN Gl diagnoses with a level 8 error message.
In VS FORTRAN* the use of literal and Hollerith constants to
initialize integer* real* or logical type variables is permitted
under option LANGLVU66) , as it is in FORTRAN Gl, and FORTRAN H
Extended. However* in VS FORTRAN under LANGLVLC77)* a character
constant (that is* a quoted constant)* may be used to initialize
character data type only and* in fact* is the only way to
initialize character type variables and arrays. Hexadecimal
constants may be used in the DATA statement to initialize
integer* real* or logical type variables or arrays under both
LANGLVU66) and LANGLVLC77).
In VS FORTRAN* for LANGLVLC77 ) * character arguments are passed
to a subprogram with both a pointer to the character string and a
pointer to the length of the character string. This is required
because the receiving program may have declared the dummy
character arguments to have inherited length (that is, the
length of the dummy argument is the length of the actual
argument). The parameter list is therefore longer than for
LANGLVL(66), because every character argument generates two
items in the parameter list. For LANGIVL(66) •
• Literal constants passed as arguments generate only one item
in the parameter list.
• Hollerith constants may be passed as subroutine or function
arguments.
In LANGLVL(77)» a level 8 message is received if Hollerith
constants are passed as arguments.
In both languages* only one item is generated in the parameter
list for Hollerith arguments. (See also the section
"SC(namel,name2* . . . )" under "Using the Compile-Time Options" on
page 72. )
In VS FORTRAN* all calculations for adjustably dimensioned
arrays are performed by use of a library routine called at all
entry points that specify such arrays. This method was required
for LANGLVK77)* because it permits redefinition of the
adjustable dimension parameters within the subprogram but
requires that the array properties do not change from those
existing at the entry point.
Appendix C. Differences Between VS FORTRAN and Current Implementations
237
APPENDIX P. INTERNAL LIMITS IN VS FORTRAN
NESTED DO LOOPS
Nested DO loops and nested implied DO loops are limited to 25
each.
EXPRESSION EVALUATION
The maximum depth of the push-down stack for expression
evaluation is 150. This means that, for any given expression, the
maximum number of operator tokens that can be considered before
any intermediate text can be put out is 150. For example, if an
expression starts with 150 left parentheses before any right
parentheses, this expression will exceed the push-down stack
limit.
NESTED STATEMENT FUNCTION REFERENCES
The total number of statement function arguments in any nested
reference is limited to 50.
The total number of nested statement function references is
limited to 50.
The total number of arguments in any statement function
definition is limited to 20.
NESTED INCLUDE STATEMENTS W
The maximum number of nested INCLUDE statements i s 16 .
NESTED BLOCK IF STATEMENTS
Block If statements may be nested to a depth of 25. That is, the
number of IF... THEN, ELSE, and ELSEIF. . . THEN statements
occurring before the occurrence of an ENDIF statement must be no
greater than 25.
CHARACTER CONSTANTS
Character symbolic constants that are defined using the
PARAMETER statement are limited to a maximum length of 255.
Character constants used in PAUSE or STOP statements are limited
to 72 characters. Character data types, defined with an IMPLICIT
statement or an explicit type statement, are limited to a maximum
of 500 characters.
REFERENCED VARIABLES
The maximum number of referenced variables in a program unit is
660.
PARENTHESES GROUPS
The maximum number of parentheses groups in a format is 50.
238 VS FORTRAN Application Programming: Guide
STATEMENT LABELS
w/'
Allowance has been made for up to 2000 user source labels and
compiler-generated labels. However* if optimization level 2 or 3
causes table overflow, the problem may be alleviated by removing
all unreferenced user labels.
Appendix D. Internal Limits in VS FORTRAN
239
GLOSSARY
This glossary includes definitions
developed by the American National
Standards Institute (ANSI), and the
International Organization for
Standari zati on (ISO). This material is
reproduced from the American National
Dictionary for Information Processing,
copyright 1977 by the Computer and
Business Equipment Manufacturers
Association, copies of which may be
purchased from the American National
Standards Institute, 1430 Broadway, New
York, New York 10018.
An asterisk (*) to the right of an item
number indicates an ANSI definition in
an entry that also includes other
def i ni t i ons.
The symbol "(ISO)" at the beginning of a
definition indicates that it has been
discussed and agreed upon at meetings of
the International Organization for
Standardization Technical Committee
97'Subcommi ttee 1 (Data Processing
Vocabulary), and has also been approved
by ANSI and included in the Ameri can
National Dictionary for Information
Processing .
alphabetic character.
the set A, B, C, ... Z
"letter."
A character of
See also
IBM EXTENSION
In VS FORTRAN, the currency symbol
is considered an alphabetic
character.
($)
END OF IBM EXTENSION
alphameric. Pertaining to a character
set that contains letters, digits, and
other characters, such as punctuation
marks.
alphameric character set. A character
set that contains both letters and
digits and also contains control
characters, special characters, and the
space character.
argument. A parameter passed between a
calling program and a SUBROUTINE
subprogram, a FUNCTION subprogram, or a
statement function.
arithmetic constant. A constant of type
integer, real, double-precision, or
complex.
arithmetic expression. One or more
arithmetic operators and/or arithmetic
primaries, the evaluation of which
produces a numeric value. An arithmetic
expression can be an unsigned arithmetic
constant, the name of an arithmetic
constant, or a reference to an
arithmetic variable, array element, or
function reference, or a combination of
such primaries formed by using
arithmetic operators and parentheses.
arithmetic operator. A symbol that
directs VS FORTRAN to perform an
arithmetic operation. The arithmetic
operators are'-
+ addi t i on
subtraction
x multiplication
/ di vi si on
xx exponentiation
array. An ordered set of data items
identified by a single name.
array declarator. The part of a
statement that describes an array used
in a program unit. It indicates the name
of the array, the number of dimensions
it contains, and the size of each
dimension. An array declarator may
appear in a DIMENSION, COMMON, or
explicit type statement.
array element. A data item in an array,
identified by the array name folLowed by
a subscript indicating its position in
the array.
array name. The name of an ordered set
of data items that make up an array.
assignment statement. A statement that
assigns a value to a variable or array
element. It is made up of a variable or
array element, followed by an equal sign
( = ), followed by an expression. The
variable, array element, or expression
can be of type character, logical, or
arithmetic. When the assignment
statement is executed, the expression to
the right of the equal sign replaces the
value of the variable or array element
to the left.
basic real constant. A string of decimal
digits containing a decimal point, and
expressing a real value.
blank common. An unnamed common block.
character constant. A string of one or
more alphameric characters enclosed in
apostrophes. The delimiting apsotrophes
are not part of the constant.
character expression. An expression in
the form of a single character constant,
variable, array element, substring,
function reference, or another
expression enclosed in parentheses. A
,->
240 VS FORTRAN Application Programming: Guide
4^\
character expression is always of type
character.
character type. A data type that can
consist of any alphameric characters; in
storage* one byte is used for each
character.
common block. A storage area that may be
referred to by a calling program and one
or more subprograms.
complex constant. An ordered pair of
real or integer constants separated by a
corvma and enclosed in parentheses. The
first real constant of the pair is the
real part of the complex number; the
second is the imaginary part.
complex type. An approximation of the
value of a complex number, consisting of
an ordered pair of real data items
separated by a comma and enclosed in
parentheses. The first item represents
the real part of the complex number; the
second represents the imaginary part.
connected file. A file that has been
connected to a unit and defined by a
FILEDEF command or by job control
statements.
constant. An unvarying quantity. The
four classes of constants specify
numbers (arithmetic), truth values
(logical), character data (character),
and hexadecimal data.
control statement. Any of the
statements used to alter the normal
sequential execution of FORTRAN
statements, or to terminate the
execution of a FORTRAN program. FORTRAN
control statements are any of the forms
of the GO TO, IF, and DO statements, or
the PAUSE, CONTINUE, and STOP
statements.
data. (1) * (ISO) A representation of
facts or instructions in a form suitable
for communication, interpretation, or
processing by human or automatic means.
(2) In FORTRAN, data includes constants,
variables, arrays, and character
substri ngs.
data item. A constant, variable, array
element, or character substring.
data set. The major unit of data storage
and retrieval consisting of data
collected in one of several prescribed
arrangements and described by control
information to which the system has
access.
data sst reference number. A constant or
variable in an input or output statement
that identifies a data set to be
processed.
data type. The properties and internal
representation that characterize data
and functions. The basic types are
integer, real, complex, logical, double
precision, and character.
* digit. (ISO) A graphic character that
represents an integer. For example, one
of the characters to 9.
DO loop. A range of statements executed
repetitively by a DO statement.
double precision. The standard name for
real data of storage length 8.
DO variable. A variable, specified in a
DO statement, that is initialized or
incremented prior to each execution of
the statement or statements within a DO
range. It is used to control the number
of times the statements within the range
are executed.
dummy argument. A variable within a
subprogram or statement function
definition with which actual arguments
from the calling program or function
reference are positionally associated.
Dummy arguments are defined in a
SUBROUTINE or FUNCTION statement, or in
a statement function definition.
executable program. A program that can
be executed as a self-contained
procedure. It consists of a main program
and, optionally, one or more subprograms
or non-FORTRAN-def i ned external
procedures, or both.
executable statement. A statement that
causes an action to be taken by the
program; for example, to calculate, to
test conditions, or to alter the flow of
control.
existing file. A file that has been
defined by a FILEDEF command or by job
control statements.
expression. A notation that represents
a value: a constant or a reference
appearing alone, or combinations of
constants and/or references with
operators. An expression can be
arithmetic, character, logical, or
relational.
external file. A set of related external
records treated as a unit; for example,
in stock control, an external file would
consist of a set of invoices.
external function. A function defined
outside the program unit that refers to
it.
external procedure. A SUBROUTINE OR
FUNCTION subprogram written in FORTRAN.
file. A set of records. If the file is
located in internal storage, it is an
internal file; if it is on an
input/output device, it i s an external
file.
Glossary
241
■file definition statement. A statement
that describes the characteristics of a
file to a user program. For example, the
OS/VS DD statement or DOS/VSE ASSGN
statement for batch processing, or the
FILEDEF command for CMS processing.
file ref2rence. A reference within a
program to a file. It is specified by a
unit identifier.
formatted record. (DA record,
described in a FORMAT statement, that is
transmitted, when necessary with data
conversion, between internal storage
and internal storage or to an external
record. (2) A record transmitted with
list-directed READ or WRITE statements
and an EXTERNAL statement.
FORTRAN-supplied procedure. See
"intrinsic function".
function reference. A source program
reference to an intrinsic function, to
an external function, or to a statement
functi on.
function subprogram. A subprogram
invoked through a function reference,
and headed by a FUNCTION statement. It
returns a value to the calling program
unit at the point of reference.
IBM EXTENSION
1
hexadecimal constant. A constant that
is made up of the character Z followed
by two or more hexadecimal digits.
END OF IBM EXTENSION
hierarchy of operations. The relative
priority order used to evaluate
expressions containing arithmetic,
logical, or character operations.
implied DO. An indexing specification,
similar to a DO statement, causing
repetition over a range of data
elements. (The word DO is omitted, hence
the term "implied.")
integer constant. A string of decimal
digits containing no decimal point and
expressing a whole number.
integer expression. An arithmetic
expression whose values are of integer
type.
integer type. An arithmetic data type,
capable of expressing the value of an
integer. It can have a positive,
negative, or zero value; it must not
include a decimal point.
internal file. A set of related internal
records treated as a unit.
intrinsic function. A function,
supplied by VS FORTRAN, that performs
mathematical or character operations.
X I/O. Pertaining to either input or
output, or both.
I/O list. A list of variables in an
input or output statement specifying
which data is to be read or which data
i s to be written. An output list may
also contain a constant, an expression
involving operators or function
references, or an expression enclosed in
parentheses.
labeled common. See "named common".
length specification. A source language
specification of the number bytes to be
occupied by a variable or an array
element.
letter. A symbol representing a unit of
the English alphabet.
list-directed. An input/output
specification that uses a data list
instead of a FORMAT specification.
logical constant. A constant that can
have one of two values* "true" or
"false."
logical expression. A combination of
logical primaries and logical
operators. A logical operator can have
one of two values* true or false.
logical operator. Any of the set of
operators .NOT. (negation), .AND.
(connection* both), or .OR. (inclusion*
either or both), .EQV. (equal),
.MEQV.(not equal).
logical primary. A primary that can have
the value "true" or "false." See also
"primary" .
logical type. A data type that can have
the value "true" or "false" for VS
FORTRAN. See also "data type".
looping. Repetitive execution of the
same statement or statements. Usually
controlled by a DO statement.
main program. A program unit, required
for execution, that can call other
program units but cannot be called by
them.
name. A string of from one through six
alphameric characters, the first of
which must be alphabetic. Used to
identify a constant, a variable, an
array, a function, a subroutine, or a
common block.
named common. A separate common block
consisting of variables, arrays* and
array declarators, and given a name.
nested DO. A DO statement whose range of
statements is entirely contained within
the range of another DO statement.
242 VS FORTRAN Application Programming: Guide
4 m \ ]
nonexecutable statement. A statement
that describes the characteristics of
the program unit, of data, of editing
information, or of statement functions,
but does not cause an action to be taken
by the program.
nonexisting file. A file that has not
been defined by a FILEDEF command or by
job control statements.
x numeric character.
digit.
(ISO) Synonym for
numeric constant. A constant that
expresses an integer, real, or complex
number.
preconnected file. A unit or file that
was defined at installation time.
However, a preconnected file does not
exist for a program if the file is not
defined by a FILEDEF command or by job
control statements.
predefined specification. The implied
type and length specification of a data
item, based on the initial character of
its name in the absence of any
specification to the contrary. The
initial characters I-N type data items
as integer; the initial characters A-H,
0-Z, and $ type data items as real. Ho
other data types are predefined. For VS
FORTRAN, the length for both types is 4
bytes.
primary. An irreducible unit of data; a
single constant, variable, array
element, function reference, or
expression enclosed in parentheses.
procedure. A sequenced set of
statements that may be used at one or
more points in one or more computer
programs, and that usually is given one
or more input parameters and returns one
or more output parameters. A procedure
consists of subroutines, function
subprograms, and intrinsic functions.
procedure subprogram. A function or
subroutine subprogram.
program unit. A sequence of statements
constituting a main program or
subprogram.
real constant. A string of decimal
digits that expresses a real number. A
real constant must contain either a
decimal point or a decimal exponent and
may contain both.
real type. An arithmetic data type,
capable of approximating the value of a
real number. It can have a positive,
negative, or zero value.
record. A collection of related items of
data treated as a unit.
relational expression. An expression
that consists of an arithmetic
expression, followed by a relational
operator, followed by another
arithmetic expression or a character
expression followed by a relational
operator, followed by another character
expression. The result is a value that
i s true or false.
relational operator. Any of the set of
operators that can express a comparison
between arithmetic expressions, and
that can be either true or false?
.GT. greater than
.GE. greater than or equal to
.LT. less than
.LE. less than or equal to
. EQ. equal to
.NE. not equal to
scale factor. A specification in a
FORMAT statement that changes the
location of the decimal point in a real
number (and, if there is no exponent,
the magnitude of the number).
specification statement. One of the set
of statements that provides the compiler
with information about the data used in
the source program. In addition, the
statement supplies the information
required to allocate data storage.
specification subprogram. A subprogram
headed by a BLOCK DATA statement and
used to initialize variables in named
common blocks.
Statement. The basic unit of a FORTRAN
program, that specifies an action to be
performed, or the nature and
characteristics of the data to be
processed, or information about the
program itself. Statements fall into two
broad classes? executable and
nonexecutable.
statement function. A name, followed by
a list of dummy arguments, that is
equated to an arithmetic, logical, or
character expression. In the remainder
of the program the name can be used as a
substitute for the expression.
statement function definition. A
statement that defines a statement
function. Its form is a name, followed
by a list of dummy arguments, followed
by an equal sign (=), followed by an
arithmetic, logical, or character
expressi on.
statement function reference. A
reference in an arithmetic, logical, or
character expression to the name of a
previously defined statement function.
statement label.
number".
See "statement
Glossary
243
Statement number. A number of from one
through five decimal digits that is used
to identify a statement. Statement
numbers can be used to transfer control*
to define the range of a DO statement*
or to refer to a FORMAT statement.
subprogram. A program unit that is
invoked by another program unit in the
same program. In FORTRAN* a subprogram
has a FUNCTION* SUBROUTINE, or BLOCK
DATA statement as its first statement.
subroutine subprogram. A subprogram
whose first statement is a SUBROUTINE
statement. It optionally returns one or
more parameters to the calling program
uni t .
X subscript. (1) (ISO) A symbol that is
associated with the name of a set to
identify a particular subset or element.
(2) A subscript quantity or set of
subscript quantities* enclosed in
parentheses and used with an array name
to identify a particular array element.
subscript quantity. A component of a
subscript? an integer constant* an
integer variable* or an expression
evaluated as an integer constant.
IBM EXTENSION
In VS FORTRAN, a subscript quantity
may also be a real constant* variable*
or expression.
END OF IBM EXTENSION
type declaration. The explicit
specification of the type of a constant*
variable* array* or function by use of
an explicit type specification
statement.
unformatted record. A record that is
transmitted unchanged between internal
storage and an external record.
unit. A means of referring to a file in
order to use input/output statements. A
unit can be connected or not connected
to a file. If connected* it refers to a
file. The connection is symmetries that
is* if a unit is connected to a file*
the file is connected to the unit.
unit identifier. The number that
specifies an external unit.
1. An integer expression whose value
must be zero or positive. For VS
FORTRAN* this integer value of
length 4 must correspond to a DD
name* a FILEDEF name, or an ASSGN
name.
2. An asterisk (*) that corresponds on
input to FT05F001 and on output to
FT06F001.
3. The name Qf a character array*
character array element, or
character substring for an internal
file.
variable. (1) * A quantity that can
assume any of a given set of values.
(2) A data item, identified by a name*
that is not a named constant* array* or
array element* and that can assume
different values at different times
during program execution.
V_jr
o
244 VS FORTRAN Application Programming: Guide
INDEX
Special Characters
. (period)* job control syntax 71
... (ellipses), job control syntax 72
+ as addition symbol 15, 55
I (OR sign), job control syntax 72
$ as first character in names 9
* (asteri sk)
job control syntax 71
multiplication symbol 15, 55
two as exponentiation symbol 15, 55
- (hyphen), job control syntax 72
- as subtraction symbol 15, 55
/ (slash)
division symbol 15, 55
format code 158
job control syntax 71
/+ (end-of-procedure delimiter,
DOS/VSE 88
// (concatenation operator), in
character expressions 56
, (comma), job control syntax 71
[ ] (square brackets)
job control syntax 72
' (colon)
format code 158
in array declarators 48
in substring notation 49
() (parentheses)
arithmetic expressions 15
in array declarators 48
in substring notation 49
job control syntax 71
3>PR0CESS statement 73, 74
' (apostrophe or single quote)
delimits character constants 44
job control syntax 71
within character constant 45
= (equal sign)
assignment statement 14, 58
job control syntax 71
%J
A, format code 158
abnormal termination
exceptions causing 138
not initializing, common error 68
about this book iii-vi
ACCESS command, VM/370-CMS 94
access method option, OPEN
statement 154
Access Method Services, catalogs DEFINE
commands 181
ACTION, DOS/VSE linkage editor control
statement 128
actual argument
common coding errors 69
description 191
rules for use 192
statement function references 61
addition, evaluation order 15, 55
address column, in storage map 117
algebraic equation, similar to
assignment statement 58
ALLOCATE command for compilation,
0S/VS2-TS0 104
ALLOCATE command, 0S/VS2-TS0 103,
110-111
alphabetic character, definition 240
alphameric character set,
definition 240
alphameric, definition 240
American National Standard FORTRAN iv
flagging for 120-121
AMSERV CMS command, processes DEFINE
commands 100
apostrophe
delimits character constants 44
job control syntax 71
within character constant 45
appendixes
A, device information 226-227
B, assembler language
considerations 228-235
overall description 225
ARC0S 190
argument
arrayp and assembler subprograms 232
assembler programs and . 231-232
assigning values to 192
COMMON statement and 193
cross reference dictionary lists 119
definition 240
FUNCTION subprograms and 191
general rules 192
intrinsic functions as 202
passing between programs 190-192
SUBROUTINE subprograms and 191-192
variable, and assembler
subprograms 231
arithmetic efficiency, for
optimization 218
arithmetic errors, common 69
arithmetic expression
assignment statement processes 14-15
definition 240
description 53-55
evaluation of 53
evaluation rules 14-15
in assignment statement 59
operator precedence in 15
ari thmetic expressi on, definition 240
arithmetic IF statement
arithmetic operators in 53
simplified FORTRAN programming 16
arithmetic operator, definition 240
arithmetic operators and their
meanings 55
arithmetic results, ensuring needed
precision 55
array declarator, definition 240
array element, definition 240
array element, internal file unit 168
array name, definition 240
arrays
as actual arguments 192
assembler subprograms and 232
character, substrings of elements 49
Index
245
cross reference dictionary lists 119
defining 12-13
definition 240
description 46-49
DO statement processes 17-18
efficient common arrangement 195-197
elements, in assignment statement 58
EQUIVALENCE statement and 51
explicit lower bounds 48
expressions and 53
implicit and explicit lower bounds,
illustration of 48
implicit lower bounds 47
implicit sharing through
EQUIVALENCE 52
initializing 50-51
initializing an entire 51
initializing character elements 50
initializing efficient!*' 214
initializing elements 50
initializing, common error 68
input/output operations and 213
internal file unit 168
multidimensional 13, 47
multidimensional, processing 17
negative lower bounds, illustration
of 49
one-dimensional 12, 47
one-dimensional, processing 17
optimizing identically
dimensioned 217
opt imi zi ng wi th identical
elements 217
physical layout, illustration 13
programming considerations 49
signed subscripts and 48-49
storage sharing between,
illustration 52
stored in column-major order 47
subscript references invalid, common
error 69
variably dimensioned, recommendation
against 215
ARSIN 190
ASCII character comparisons, in
intrinsic functions 202
ASCII collating sequence, used in
character intrinsic functions 57
ASCII encoded files, record formats 186
assembler language considerations
appendix B 228-235
common data in 230-231
FORTRAN data 230-235
FORTRAN subprogram
references 228-229
linkage considerations 229-230
LIST option listing and 143
main programs 230
retrieving arguments 231-232
subprograms 230-235
ASSGN control statement, DOS/VSE
description 85-86
sequential files 170
when required for DOS/VSE
compilation 88
ASSIGN statement .cross reference
dictionary lists 119
ASSIGN statement, sets GO TO variable 66
assigned GO TO, invalid as DO loop
terminal statement 65
assignment statement
arithmetic 59
character 59
definition 240
description 58-60
evaluates arithmetic
expressions 14-15
evaluation rules 14
initializes data items 14
initializing principal diagonal
using 51
intrinsic functions in 15-16
logical 60
simplified FORTRAN programming 13-16
statement functions in 60-61
substring references valid in 49
asterisk (*), job control syntax 71
asynchronous input/output
statements 164-166
AT statement, description 139-140
ATTRIB command, 0S/VS2-TS0 103
audience iii
autolink feature, DOS/VSE 128
automatic cross compilation 71
automatic cross system support,
link-editing 122
avoiding coding errors 68-70
o
en
108
background command procedures, TSO
BACKSPACE statement
checking accuracy of records
with 163
invalid for directly accessed VSAM
di rect f i les 178
replace a record 163
sequential files 163-164
sequentially accessed VSAM direct
files 177, 178
VSAM sequential file
considerations 176
basic real constant with real exponent,
defining 43
basic real constant, definition 43, 240
BG, DOS/VSE linkage editor control
option 128
blank character ( ), job control
syntax 72
blank common
definition 240
description 199-201
example of use 200-201
illustration of use 201
initializing invalid 199
must be unnamed 199
only one allowed 199
rules for use 199-200
blank common, example of use 200
blanks, OPEN statement and 154
BLKSIZE parameter, for direct files 174
BLKSIZE, for direct files 173
BLOCK DATA statement
BLOCK DATA subprogram and 209
description of use 208
initializes named common 209
BLOCK DATA subprograms
coding 208-209
coding example 209
statements valid 209
block IF statement
description 61-64
execution rules 63-64
W
o
246 VS FORTRAN Application Programmi ng' Guide
f\,
BN,
BZ,
invalid as DO loop terminal
statement 65
nested DO statements and 64
nesting 63
valid forms 63
format code 158
format code 158
CD
CALL CDUMP library routine 223
CALL command for compilation,
0SWS2-TS0 104-105
CALL command, 0S/VS2-TS0 103, 106
CALL CPDUMP library routine 223
CALL DUMP library routine 223
CALL DVCHK library routine 222
CALL ERRMON error-handling routine 223
CALL ERRSAV error-handling routine 224
CALL ERRSET error-handling routine 224
CALL ERRSTR error-handling routine 224
CALL ERRTRA error-handling routine 224
CALL EXIT library routine 223
CALL loader option, OS/VS 127
CALL OVRFLW library routine 222
CALL PDUMP library routine 223
CALL statement
CDUMP 223
CPDUMP 223
DUMP 223
DVCHK 222
ERRMON 223
ERRSAV 224
ERRSET 224
ERRSTR 224
ERRTRA 224
EXIT 223
extended error handling 143
extended error handling and 143
general description 189
OPSYS, DOS/VSE 211
OVRFLW 222
PDUMP 223
calling and called programs
assembler considerations 228-235
called program, definition 189
calling program* definition 189
coding 201-209
common coding errors 69
detai led description 189-212
invocation example 189
main program, definition 189
shared data areas, example 193
subprogram definition 189
system considerations 209-212
CANCEL, DOS/VSE li nkage edi tor control
option 128
capacities, direct access devices 227
card deck, for source input 20
card punch files, VM/370-CMS 99
card reader files, VM/370-CMS 99
cataloged procedure
compile-only, OS/VS 20
DOS/VSE, writing and using 88-89
modifying , OS/VS 77-84
modifying, DOS/VSE 88-89
OS/VS compilation data sets and 77
retrieving, DOS/VSE 88
unique identifier, DOS/VSE 88
using for program output 134
using, OS/VS 77-84
catalogi ng
DOS/VSE record size 88
load module 127
object module 92
subprograms 209 -
VSAM DEFINE commands 181-182
CATALP, and DOS/VSE cataloged
procedures 88
CATALR DOS/VSE function, catalogs object
module 92
CATALS DOS/VSE function, catalogs source
program 91
changing program execution
sequence 16-18
character array element, internal file
unit 168
character constant
definition 240
maximum size 46
PAUSE statement and 67
STOP statement and 67
character data type
constant 42
constant, defining by value 44-45
defining 10
definition 241
description 39-41
EQUIVALENCE statement restriction 52
general description 9
internal representation 232
substrings of items 49
valid lengths 39
variables, hexadecimal constants
i ni t i al i ze 45
character expression
character operators in 53
definition 240
description 55-56
in assignment statement 59
character library functions 222
character substring, internal file
unit 168
CLEAR, DOS/VSE linkage editor control
option 128
CLOSE statement
description 156-157
di rect f i les 173
sequential files 164
VSAM direct file considerations 177
VSAM sequential file
considerations 176
closed loop errors 29
CMS commands, using 93
CMS considerations
See VM/370-CMS considerations
codes
compiler messages 22
compiler messages, error severity 22
coding errors to avoid 19
coding form, FORTRAN 7 , 38
coding your program
coding errors to avoid 68-70
complete FORTRAN programming 38-70
0PTIMI2EC3) considerations 219-221
sharing data 190-201
simplified FORTRAN programming 7-19
colon ( '* )
in array declarators 48
in substring notation 49
comma (,), job control syntax 71
command procedures, TSO 108
common block, definition 241
Index
247
COMMON blocks, storage maps and 117
common errors
source program 19, 68-70
common expression elimination,
0PTIMIZEC3) 220
common input/output statement
options 152
common items, in cross reference
dictionary 119
COMMON statement
argument usage 193
assembler programs and 230
blank common 199-201
BLOCK DATA subprogram and 209
data item order in 193-194
defines arrays 47
description of use 193-201
dummy variables for alignment 195
efficient data arrangpmpnt 195-197
example of use 200-201
fixed order variable alignment 195
length considerations 194-195
named common 199-201
passing subroutine arguments
using 215
rules for use 199-200
shared data areas, example 193
storage maps and 117
transmitting values using 194
type considerations 194-195
using efficiently 215
compi lat i on
automatic cross compilation 71
batch, DOS/VSE 87
batch, OS/VS 76
complete FORTRAN programming 71, 92
DOS/VSE compile, link-edit, and
execute procedure 28
DOS/VSE files for 88
entering source program 20
fixing errors 22-23
link-edit and execute, DOS/VSE 133
link-edit and execute, OS/VS 131
modification of defaults 89
OS/VS compile, link-edit* and execute
procedure 27
0S/VS2-TS0 104-105
output, illustration of 91
requesting 20, 21
requesting under DOS/VSE 87-88
requesting under OS/VS 76
requesting, DOS/VSE 21
requesting, OS/VS 20-21
simplified FORTRAN programming 20-21
statistics in object listing 144
VM/370-CMS 95
compile time options
DECK 72
defaults for 72
EXEC statement specifies in
DOS/VSE 87
EXEC statement specifies in OS/VS 72
FIPS 72
FIXED 73
FLAG 73
FORTVS command specifies in VM/370
CMS 72
FREE 73 "
GOSTMT 73
LANGLVLC66I77) 73
LINECOUNT 73
LIST 73
MAP 73
NAME 73
NODECK 72
NOFIPS 72
NOGOSTMT 73
NOLIST 73
NOMAP 73
NOOBJECT 73
NOOPTIMIZE 73
NOSOURCE 74
NOTERMINAL 74
NOXREF 74
OBJECT 73
OPTIMIZE(0|1|2|3) 73
OPTION statement specifies in
DOS/VSE 72
SC 73
SOURCE 74
TERMINAL 74
XREF 74
compile-only, when to request 20
compiler messages
See diagnostic messages
compi ler output
cross reference listing, XREF
option 115-120
default options and 89
description 89-92
end of compilation message 120
explicit options and 90
i llustrati on of 91
LIST file, 0S/VS2-TS0 105
listing 112-121
LISTING file, VM/370-CMS 96
listing, header 112
message listing, FLAG option 113-115
OBJ file, 0S/VS2-TS0 105
simplified FORTRAN programming 21
source program 90-91
source program listing 112
source program, DOS/VSE 91
source program, OS/VS 90
standard language flagging 120-121
storage map listing, MAP
option 115-120
TEXT file, VM/370-CMS 96
under 0S/VS2-TS0 105
under VM/370-CMS 96
complete FORTRAN programming
coding errors to avoid 68-70
compilation 71, 92
description 33-150
executing your program 130-134
fixing compile time errors 112-121
fixing execution-time errors 135-150
general description 33
link-editing your program 122-129
OPTIMIZEO) considerations 219-221
program coding 38-70
completion code in dumps 138
complex constant, definition 44, 241
complex data type
constant 42
constant, defining by value 44
defining 10
definition 241
descripti on 39
general description 9
internal representation 234-235
reference length in common 196
valid in arithmetic expressions 55
valid lengths 39
computational reordering,
0PTIMIZEC3) 220
^
o
248 VS FORTRAN Application Programming* Guide
computations, how compiler recognizes
duplicate 216, 217
concatenation operator (//), in
character expressions 56
conditional control transfers, GO TO
statement 66-67
connected file, definition 241
constant
arithmetic, description 42
assignment statement 58
character, description 42
character, STOP statement and 67
complex, description 42
cross reference dictionary lists 119
defining by name 11-12, 46
defining by value 11, 42-45
definition 241
description 42-46
expressions and 53
hexadecimal 42
Hollerith 42
integer, description 42
literal, old FORTRAN 42, 45
logical, description 42
real, description 42
restrictions as actual arguments 192
subscripts 47
constant computations, how compiler
recognises 217
constant operands, recognition of 217
CONTINUE statement, description 64
control statement
complete FORTRAN programming 61-68
definition 241
simplified FORTRAN programming 16-18
control variable for GO TO, set by ASSIGN
statement 66
COPY, EDIT subcommand, 0S/VS2-TS0 103
CP commands, using 93
critical variables, limitations on
optimizing 218
cross reference dictionary
compiler output 90
description 118-120
using 115-120
XREF option requests 74
cross system support, link-editing 122
current FORTRAN, definition iv
current FORTRAN, description 1
current language documented in this
book 2.
current language, definition iv
current standard, flagging for 120
LU
DARCOS 190
DARSIN 190
data
assignment statement assigns values
to 58
classifications of 42-49
constants 11-12, 42-46
defining 8-13, 39-41
definition 7, 38, 241
dictionary, compiler output 119
efficient arrangement, common
areas 195-197
EQUIVALENCE statement, reuses storage
for 51-53
explicit type statement and 10, 41
IMPLICIT statement and 10, 40-41
incorrect input, causes errors 30
initializing 14, 50-51
items, description 13
length considerations, common
areas 194-195
order in COMMON areas 193-194
retrieval of, with READ 8
shared areas, example 193
sharing between programs 190-201
sharing storage for 193-201
truncation, common coding error 68
type considerations, common
areas 194-195
types and lengths 39
types, general description 9
typing groups of 40-41
using efficiently 50-53
variables 42
WRITE statement displays 18
data f i les
DOS/VSE test files 27
OS/VS test files 26
VM/370-CMS 98-101
data item, definition 241
data set reference number,
definition 241
data set, definition 241
DATA statement
BLOCK DATA subprogram and 209
initializes arrays 50-51
initializes data 50-51
data type
COMMON statement
considerations 194-195
constants and 42-46
cross reference dictionary and 119
definition 241
descriptions 39-41
explicit type statement and 41
general description 9
IMPLICIT statement and 40
initializing required 14
predetermined definitions 9, 40
specifying for groups of items 40-41
specifying for single items 41
valid lengths 39
DATA, VM/370-CMS filetype 98
date of compilation, compiler
default 89
date, in output listing header 112
DCB parameter, defines OS/VS
records 186
DD control statement, OS/VS
defining direct files using 173
description 75-76
direct access labels and 185
modifying in cataloged
procedures 83-84
sequential files 170
tape labels and 184
VSAM file processing 182
debug packets
detailed description 139-140
general description 30
DEBUG statement, description 139-140
debugging
debug packets for 139-140
dumps, requesting 149-150
extended error handling and 140-143
GOSTMT option and 136
LIST option and 137
Index
249
symbolic debugging example 141
decimal divide interrupt message 223
DECK compiler option 72
DECK option output, detailed
description 122-124
DECK option, compiler output 90
DECLARED column in cross reference
dictionary 119
defaults
data types 9
extended error handling 140
defaults, modification of 89
DEFINE command, VSAM
creates catalog entry 179-181
creating under VM/370-CMS 100
execution of 181-182
VSAM direct files 180
VSAM sequential files 180
VSAM-managfed sequential files 181
DEFINED column in cross-reference
dictionary 120
defining records 185-188
DELETE command, 0S/VS2-T50 103
designing your program
complete FORTRAN programming 34-37
resources available and 34
simplified FORTRAN programming 6
top-down development and 34-37
typical structure and 34
device information
appendix A 226-227
maximum block size values 226
minimum block size values 226
when corrections required 22
devices valid for DOS/VSE execution 132
devices valid for OS/VS execution 130
diagnostic messages
compile time, example 114
compiler default 89
compiler module identifier in 114
compi ler output and 21
detailed description 113-115
DOS/VSE considerations 115
example 22
execution time 29
execution-time 135-139
format of 22-23
GOSTMT option and 136
i denti f i er for 22
IFX compiler message prefix 114
IFY, execution error message
prefix 135
language standard flagging 90
library 135
library message number 135
library message, origin 135
library, program action after 135
LIST option and 137
message number identifies 114
operator 138-139
OS/VS considerations 115
prefix meanings 29
program interrupt 137-138
self explanatory 113
severity level in 114
traceback map and 135-136
using 23
digit, definition 241
DIMENSION statement
BLOCK DATA subprogram and 209
defines arrays 13, 47
severity level in 22
simplified programming examples 12
direct access device capacities 227
direct access files, control statements
for 86
direct access labels
description of use 184-185
processing 185
direct access, VSAM direct files 178
direct file processing
CMS FILEDEF command and 98
complete FORTRAN programming 170-174
direct access devices valid 170
formatted, description 157-160
internal files and 168
record formats 186
source program
considerations 171-173
unformatted, description 157
valid VSAM source statements,
5 U m in a r y 175
VM/370-CMS 98-99
VSAM considerations 174-183
VSAM direct access for 178
VSAM sequential access for 177-178
VSAM source language 177-179
diskette, as source input device 20
displacement, definition 195
DISPLAY statement, description 140
displaying program results 18
division, evaluation order 15, 55
DLBL command, VM/370-CMS 100
DLBL control statement, DOS/VSE
description 86
direct access labels 185
di rect f i les 174
sequential files 170
VSAM file processing 182
DO list, implied, in DATA statement 51
DO loop, definition 241
DO statement
batch compilation 87
block IF statement and 64
branches into loops, warning 64
CONTINUE statement useful with 64
control transfers into, common coding
error 69
description 64-66
DO loop, active upon execution 65
flexibility of processing with 65
incrementing loop controls 65
invalid as DO loop terminal
statement 65
multidimensional arrays 17-18
nested 17-18, 64
one-dimensional arrays 17
preventing loop execution 65
simplified FORTRAN programming 17-18
when execution completed 65
writing loops inline 216
DO variable, definition 241
DOS/VSE considerations
abnormal termination dumps 150
automatic cross compilation 71
cataloged procedures, writing and
using 88-89
cataloging load modules 127
cataloging source program 91
common input/output error 69
compilation files 88
compile, link-edit, and execute
job 133
compiler options and 72
DEFINE command 182
defining records 187-188
"Y
\y
250 VS FORTRAN Application Programming: Guide
o
direct access labels 185
di rect f i les 174
execute-only job 133
job control statement
descriptions 85-87
link-edit and execute job 133
link-edit* executing 128
linkage editor, using 127-128
logical units needed for
execution 132
maximum record length 188
message codes 115
object module* cataloging 92
overlay procedure 211
overlays 211-212
phase execution 133
program execution 27-28
publications vi
requesting compilation 21, 87-88
sequential files 170
tape labels 184
VSAM file creation 182-183
VSAM fi le processing 182-183
VSAM-managed sequential files 181
double precision data type
conversions of 218
defining 10
double precision, definition 241
double precision data type, reference
length in common 196
dummy argument
common coding errors 69
cross reference dictionary lists 119
definition 241
description 191
restrictions on assigning values 192
rules for use 192
statement function definitions
and 60
dummy variables, alignment using 195
DUMP, requests dynamic dump 149
dumps
completion code in 138
requesting 149-150
duplicate computations, how compiler
recognizes 216
dynamic dumps, requesting 149
E, error code 22, 114
E, format code 158
EBCDIC collating sequence, used in
relational expressions 57
EBCDIC data sets, record formats 186
EBCDIC data, and internal files 168
EBCDIC items, hexadecimal constants
ini tial ize 45
EDIT command, 0S/V52-T50 103
EDIT command, 05/VS2-TS0, source program
creation 102-104
EDIT command, VM/370-CMS 94
EDIT command, VM/370-CMS, source program
creation 93-95
elimination of instructions,
0PTIMI2EC3) 220
ellipses ( ... ), job control syntax 72
ELSE IF statement, description 61-64
ELSE IF, invalid as DO loop terminal
statement 65
ELSE statement, description 61-64
ELSE, invalid as DO loop terminal
statement 65
END DEBUG statement, description 140
END IF statement, description 61-64
END IF, invalid as DO loop terminal
statement 65 v
end of compilation message 120
END record, in object module 124
END statement
BLOCK DATA subprogram and 209
description 68
executable 19, 68
invalid as DO loop terminal
statement 65
simplified FORTRAN programming 19
end-of-file labels, when processed 184
end-of-procedure delimiter, DOS/VSE 88
end-of-volume labels, when
processed 184
END, EDIT subcommand, 0S/VS2-TS0 103
ENDFILE statement
sequential files 163
VSAM files treat as
documentation 175
ending a program 19, 68
ENTRY control statement, OS/VS 211
entry point, traceback map lists 136
entry sequenced data set (ESDS), source
language considerations 175-179
ENTRY statement
description 41
in subprograms 206-207
EP loader option, OS/VS 127
equal sign (=)
assignment statement 14, 58
job control syntax 71
EQUIVALENCE statement
arrays and, illustration 52
BLOCK DATA subprogram and 209
COMMON statement and 197-198
description 51-53
errors using 198
execution time efficiency,
illustration 54
execution-time efficiency and 52-53
invalid references, common error 69
optimization and 214
restriction on CHARACTER items 52
equivalenced items, in cross reference
dictionary 119
ERRMON, requests extended error
control 142
error code 22
error handling library
functions 223-224
error messages
See diagnostic messages
error occurrences, warning on number
of 143
error routine option, input/output 153
error summary, in traceback map 136
errors
fixing compilation 22-23, 112-121
fixing execution 29-30, 135-150
errors to avoid 19, 68-70
ERRSAV, alters entry in option table 142
ERRSET, changes entry in option
table 142
ERRSTR, stores entry in option table 142
ERRTRA, requests traceback 142
ERRTRA, requests traceback maps 136
ESD record types 123
Index
251
ESD record, in object module 123
ESDS, under 0S/VS2-TS0 111
ESDS, under VM/370-CMS 99-101
ESDS, VSAM sequential files 174
exception codes, program interrupt
messages 137
EXEC command, VM/370-CMS 94
EXEC control statement, DOS/VSE
cataloged procedures and 88
cataloged procedures use PROC
parameter 88
description 86-87
DOS/VSE compilation size 87
LINKEDT, for link-editing 128
OV (override) parameter 89
SIZE parameter required for VSAM
files 183
EXEC control statement, OS/VS
description 75
linkage editor options, OS/VS 125
loader data sets 127
loader processing options 126
modifying in cataloged
procedures 82-83
executable program, definition 241
executable statement, definition 7, 38,
241
EXECUTE option 73
executing a program, 0S/VS2-TS0 106-107
execution errors, fixing
complete FORTRAN programming 135-150
simplified FORTRAN programming 29-30
execution time efficiency and
EQUIVALENCE 52-53
execution time efficiency, illustration
of EQUIVALENCE 54
execution time error messages
detailed description 135-139
interrupt 223
library 135
operator 138-139
program interrupt 137-138
traceback map with 135-136
execution-time library
automatic error handling 223
description 222-224
DOS/VSE SYSRLB used for 128
user controlled error
handling 223-224
execution, compiler
See compi lati on
execution, program
complete FORTRAN programming 130-134
DOS/VSE compile, link-edit, and
execute procedure 28
DOS/VSE considerati ons 27-28
error messages 29
OS/VS compile, link-edit, and execute
procedure 27
OS/VS considerati ons 26-27
0S/VS2-TS0 106-107
output 28
simplified FORTRAN programming 26-28
test data files and 27
under 0S/VS2-TS0 105
under VM/370-CMS 97
existing file, definition 241
explicit type statement
BLOCK DATA subprogram and 209
cross reference dictionary and 119
def i nes arrays 47
simplified FORTRAN programming 10
type changes using, common coding
. error 69
exponent overflow interrupt message 223
exponent underflow interrupt
message 223
exponentiation, evaluation order 15,
53, 55
expressi on
common, 0PTIMIZEC3) eliminates 220
defining and using 53-58
definition 7, 38, 241
integer or real, in DO statement 65
integer, in computed GO TO 66
PARAMETER statement and 46
restrictions as actual arguments 192
scaling elimination 217
extended error handling
complete FORTRAN programming 140-143
control through CALL statements 143
extensions, how documented 3
EXTENT control statement, DOS/VSE
description 86
parameters required for VSAM 182
required for direct files 174
sequential files 170
VSAM file processing 182
external file, definition 241
external function, definition 241
external procedure, definition 241
EXTERNAL statement, description 203-204
153
factoring expressions 217
file definition statement,
definition 242
file identifier, VM/370-CMS 98
file labels, direct access 184
file labels, tape files 183
file reference, definition 242
file status option, OPEN statement
file, definition 241
FILE, EDIT subcommand, VM/370-CMS 94
file, INQUIRE statement and 156
FILEDEF command for data files 98-99
FILEDEF command, VM/370-CMS 94, 98-99
filemode, VM/370-CMS 98
filename option, OPEN statement 154
filename, VM/370-CMS 98
filetype, VM/370-CMS 98
finding execution errors 29-30
FIPS compiler option 72
FIPS option, output for 120-121
FIXED compiler option 73
fixed form input 38
fixed length records, description 185
fixed order variable alignment 195
fixed-point divide interrupt
message 223
fixed-point items, conversions of 218
fixing compilation errors 23
fixing compile-time errors
complete FORTRAN programming 112-121
simplified FORTRAN programming 22-23
using compiler output
listing 112-121
fixing execution-time errors
complete FORTRAN programming 135-150
simplified FORTRAN programming 29-30
FLAG compiler option 73, 113
o ;
252 VS FORTRAN Application Programming: Guide
^
o
FLAG compiler option, detailed
description 115
floating-point divide interrupt
message 223
floating-point items, conversions
of 218
FMODE, EDIT subcommand, VM/370-CMS 94
FNAME, EDIT subcommand, VM/370-CMS 94
foreground command procedures, TSO 108
FORMAT statement
codes, examples 158
cross reference dictionary lists 119
description 157-160
display example 159
group specifications 159-160
nested specifications 159-160
repeated specifications 160
variable specifications 160
formatted I/O
external 157-160
internal READ statement 169
internal WRITE statement 169
formatted record, definition 242
formatting information, in READ
statement 8
formatting rules, common errors 68
FORTRAN
See VS FORTRAN
FORTRAN publications
current FORTRAN source programs 7
current language documented in this
book 2
old FORTRAN source programs 7
related systems publications v-vi
usage of 2-3
usage, illustration 3
VS FORTRAN Application
Programming iv
VS FORTRAN Installation and
Customization iv-v
FORTRAN 77, definition iv
FORTRAN-suppl i ed functions
See intrinsic functions
FORTRAN, VM/370-CMS filetype 98
FORTVC cataloged procedure, OS/VS 78
FORTVCG cataloged procedure, OS/VS 81
FORTVCL cataloged procedure, OS/VS 78
FORTVCLG cataloged procedure, OS/VS 79
FORTVG cataloged procedure, OS/VS 80
FORTVL cataloged procedure, OS/VS 81
FORTVLG cataloged procedure, OS/VS 80
FORTVS command,. VM/370-CNS 94, 95-96
FREE command, 0S/VS2-TS0 103
FREE compiler option 73
FREE compiler option, 0S/VS2-TS0
considerations 105
FREE compiler option, VM/370-CMS
considerations 96
free form input 38, 95
FTnnFnnn, data sets for OS/VS
execution 130
FTnnFnnn, optional OS/VS loader data
set 127
full FIPS flagging 121
function reference
definition 242
evaluation order 15, 55
explicit type statement and 202
general description 189, 190
FUNCTION statement, in subprogram 205
FUNCTION subprograms
arguments in 191-192
CALL OPSYS loads, DOS/VSE 211
coding 205-206
definition 242
ENTRY statement in 206-207
general description 189
invoking 203-204
paired arguments in 190
RETURN statement in" 207-208
SAVE statement as documentation 208
top-down development and 37
using 203-204
F1-F6, DOS/VSE linkage editor control
options 128
LH
G, format code 158
general description, VS FORTRAN 1-3
general logic structure of programs 6
GENMOD command, VM/370-CMS 97
GETFILE, EDIT subcommand, VM/370-CMS 94
GLOBAL command, VM/370-CMS 94, 96-97
glossary
ANSI definitions 240
definitions of terms 240-244
ISO definitions 240
GO TO statement
assigned, description 66
computed, description 66-67
control transfer to next executable
statement 67
warning on branches into loops 64
when invalid as DO loop terminal
statement 65
GOSTMT compiler option 73
description 73
traceback map and 136
group format specifications 159-160
E3
103
HELP command, 0S/VS2-TS0 103
HELP, EDIT subcommand, 0S/VS2-TS0
hexadecimal constant
definition 242
description 42, 45
hierarchy of operations, definition 242
Hollerith constant, description 42, 45
hyphen (-), job control syntax 72
E
I/O list, definition 242
I/O status option, input/output 153
I/O, definition 242
I, format code 158
I, informational code 22, 114
i denti ty matrix, initializing 51
IF block 62
IF statement
block, repeated ELSE IF statements
in 63
block, valid forms 63
common errors using 0PTIMIZEC3) 69
Index
253
logical, optimization of 219
logical, simpl i fi ed FORTRAN
programming 16-17
optimization and 219
0PTIMIZEC3) and 220
simplified programming 16-17
IF-level 62
IFX, compiler message prefix 22, 114
IFY, execution error message prefix 29,
135
imaginary part of a complex constant,
def i n i ng 44
IMPLICIT statement
BLOCK DATA subprogram and 209
data initialization and 50
description 40-41
simplified FORTRAN programming 10
type changes using, common coding
error 69
wraparound scan of 40
implied DO list, in DATA statement 51
implied DO, definition 242
INCLUDE command, VM/370-CMS 94, 97
INCLUDE statement, FORTRAN
advantages in top-down
development 37
can be nested 36
CMS record size 95
OS/VS record size 77
SYSLIB required for CMS 95
SYSLIB required under OS/VS 77
SYSSLB required under DOS/VSE 88
top-down development and 36-37
INCLUDE, DOS/VSE linkage editor
control 211
INCLUDE, DOS/VSE linkage editor control
statement 128
INCLUDE, OS/VS linkage editor control
statement 126, 211
incorrect input, and errors 30
incorrect logic, and errors 30
industry standards iii-iv
information messages, compiler
default 89
informational code 22
initialization errors, common 69
initializing named common 199
i nput/output
common errors 69
common statement options 152
data sets for OS/VS 130
detailed description 152-188
DOS/VSE logical units 132
formatted 157-160
formatted, description 157-160
optimization and 213
statement list 152
unformatted, description 157
INPUT, EDIT subcommand, 0S/VS2-TS0 103
INPUT, EDIT subcommand, VM/370-CMS 94
INQUIRE statement, description 156
INSERT control statement, OS/VS 210
INSERT, EDIT subcommand, 0S/VS2-TS0 103
instruction elimination,
OPTIMIZED) 220
integer constant with real exponent,
defining 43
integer data type
constant 42
constant, defining by value 43
default names for 9
defining 10
definition 242
description 39-41
. division gives integer results 55
general description 9
internal representation 233
optimization efficiency and 214
predetermined definition 9
reference length in common 196
valid in arithmetic expressions 55
vali d lengths 39
variable as 13
variable in DO statement 65
variable, array subscripts and 47
integer expression in computed GO TO 66
integer expression, definition 242
internal file
complete FORTRAN programming 168-170
definition 242
internal sequence number (ISN)
compile-time messages optionally
contain 115
compiler messages 23
source program listing 21
source program listing prints 112
traceback map uses 136
intrinsic functions
ASCII character comparisons in 202
cross reference dictionary lists 119
definition 242
explicit type statement and 202
general description 190
invoking 201-203
simplified FORTRAN programming 15-16
storage map lists 116
TSO usage of 106
INTRINSIC statement
description of use 202
IOSTAT Option, VSAM return code placed
in 179
ISO FORTRAN iv
ISO, identifies ISO glossary
definitions 240
/On
job control considerations
DOS/VSE 84-87
OS/VS 74-76
job control statement syntax 71-72
JOB control statement, DOS/VSE
description 85
JOB control statement, OS/VS
description 74-75
JOBLIB DD, using 131
jobname
DOS/VSE compile-only example
OS/VS compile-only procedure
21
20
m
LABEL column in cross reference
dictionary 119
LABEL parameter, DD statement 185
LABEL parameter, tape files 184
labels, description of use 183-185
LANGLVL(66|77) compiler option 73
language extensions, how documented 3
language levels, manuals valid 38
o
254 VS FORTRAN Application Programming* Guide
#"N
^L^
LBLTYP control statement, tape labels
and 184
length specification, definition 242
LET linkage editor option, OS/VS 125
LET loader option, OS/VS 126
letter, definition 242
level codes
description of 114
E (error) 114
I (information) 114
S (serious error) 114
U (abnormal termination) 115
W (warni ng) 114
(information) 114
12 (serious error) 114
16 (abnormal termination) 115
4 (warning) 114
8 (error) 114
library
See execution-time library
library messages 135
See also diagnostic messages
library module, identified in
messages 135
LIBRARY, OS/VS linkage editor control
statement 126
LINECOUNT compiler option 73
LINK command, 0S/VS2-TS0 103, 106
1 i nk-edi t i ng
complete FORTRAN programming 122-129
cross system support, automatic 122
DECK option and 122
DOS/VSE compile, link-edit, and
execute procedure 28
DOS/VSE logical units 128
execution 128
execution with load module,
OS/VS 131
execution with phase, DOS/VSE 133
for immediate execution 124
for later execution 127
input for 122
optional OS/VS linkage editor data
sets 126
OS/VS compile, link-edit, and execute
procedure 27
OS/VS linkage editor control
statements 126
output 129
required OS/VS linkage editor data
sets 126
simplified FORTRAN programming 24-25
TSO listings 106
under DOS/VSE 24-25, 128
under OS/VS 24, 125-127
under 0S/VS2-TS0 105-107
under VM/370-CMS 97
linkage editor program, OS/VS 125-127
LIST compiler option 73
description of listing 143-148
example of output 148
format of listing 144-148
traceback map and 137
LIST compiler option, 0S/VS2-TS0
considerations 105
list directed input/output
description 166-168
input data 166
READ statement 167
WRITE statement 168
LIST file, 0S/VS2-TS0 105
LIST linkage editor option, OS/VS 125
LIST option, compiler output 90
list-directed, definition 242
LIST, EDIT subcommand, 0S/VS2-TS0 103
LISTFILE command, VM/370-CMS 94
LISTING file, VM/370-GMS 96
literal constant, description 42
literal constant, old FORTRAN 45
LOAD command, VM/370-CMS 94, 97
load module
cataloging, DOS/VSE 127
DOS/VSE execution 133
DOS/VSE logical units 132
execution of 130, 134
execution output 134
OS/VS execution 131-132
OS/VS program data sets 130
producing 124
using cataloged 131
loader program under TSO 107
loader program, OS/VS 126-127
LOADGO command, OS/VS2-TS0 103
logic errors, MAP option helps find 116
logic structure of programs, general 6
logic, incorrect, and errors 30
logical constant, definition 242
logical data type
constant 42
constant, defining by value 44
data items used in logical
expressions 57
definition 242
description 39
internal representation 232
optimization efficiency and 214
reference length in common 196
simplified FORTRAN programming 16-17
valid lengths 39
logical expression
definition 242
description 57-58
in assignment statement 60
logical IF statement and 16-17
logical operators in 53
logical operator, definition 242
logical operators and their meanings 57
logical primary, definition 242
logical units for DOS/VSE linkage
editing 128
logoff, 0S/VS2-TS0 102
logoff, VM/370-CMS 93
logon, 0S/VS2-TS0 102
logon, VN/370-CMS 93
looping, definition 242
loops, programming
block IF statement and 64
branches into, warning 64
complete FORTRAN programming 64-66
CONTINUE statement useful with 64
description 64-66
errors in 29
for multidimensional arrays 17-18
for one-dimensional arrays 17
nested 17-18, 64
0FTIMI2E(3) and 220
simplified FORTRAN programming 17-18
writing inline 216
lower bound, in substring notation 49
lower bounds, in arrays 48
lower case items, job control syntax 71
Index
255
DD
magnetic tape labels
See tape labels
main program
coding 201-204
common coding errors 69
definition 242
general description 189
invocation example 189
naming 201
manual organization iii
manuals* valid for language levels 38
MAP compiler option
compiler output 90
description 73, 115-118
example 116
MAP compiler option, 0S/VS2-TS0
considerations 105
MAP linkage editor option, OS/VS 125
MAP loader option, OS/VS 126
MAP option* using 115
MAP, DOS/VSE linkage editor control
option 128
mathematical equivalence, when
implied 52
mathematical errors 30
mathematical functions
assignment statement uses 15-16
mathematical functions, in assignment
statement 15
mathematical library functions 222
maximum block size values 226
maximum record length, DOS/VSE 188
message format, operator 139
message number, compiler 114
message prefix, compiler 114
message text
compiler messages 23, 115
library messages 135
programmei — specified in PAUSE
statement 139
programmer-specified in STOP
statement 139
messages
See diagnostic messages
minimum block size values 226
misspelling words, common error 68
MODE column in cross reference
dictionary 119
MODE column, in storage map 116
modification of compiler defaults 89
modifier statements, DOS/VSE cataloged
procedures 88
module identifier, compiler
messages 114
MOVE, EDIT subcommand, 0S/VS2-TS0 103
multiplication, evaluation order 15, 55
MVS considerations
abnormal termination dumps 150
automatic cross compilation 71
batch compilation 76
cataloged load modules, using 131
cataloged procedures 77-84
cataloging load modules 125
cataloging source program 90
compilation data sets 76-77
compile-only cataloged procedure 20
compile, link-edit and execute
job 131
compiler options and 72
data sets needed for execution
defining records 186-187
direct access labels 185
di rect f i les 173
execution-only job 131
job control statements 74-76
link-edit and execute job 131
link-edit execution 125-126
linkage editor, using 125-126
load module execution 131-132
loader program under TSO 107
loader, using 126-127
message codes 115
object module, cataloging 92
overlays 210-211
program execution 26-27
publications v
requesting compilation 20-21,
sequential files 170
tape labels 184
VSAM DEFINE command 181
VSAM file creation 182
VSAM file processing 182
130
76
n, programmei — specified in PAUSE
statement 139
n, programmei — specified in STOP
statement 139
name
complete FORTRAN programming 40-49
cross reference dictionary and 119
definition 242
PARAMETER statement uses 46
simplified FORTRAN programming 9-13
table of, compiler output 90
name column in cross reference
dictionary 119
NAME column, in storage map 116
NAME compiler option 73
named common
definition 242
description 199-201
example of use 200-201
illustration of use 201
i ni tiali zing 199
length restriction 199
naming 199
rules for use 199-200
named common, BLOCK DATA programs
initialize 208
named common, example of use 200
NCAL linkage editor option, OS/VS 125
NCAL loader option, OS/VS 127
nested DO loops 17-18
nested DO, definition 242
nested format specifications 159-160
NOAUTO, DOS/VSE linkage editor control
option 128
NODECK compiler option 72
NOFIPS compiler option 72
NOGOSTMT compiler option 73
NOLET loader option, OS/VS 126
NOLIST compiler option 73
NOMAP compiler option 73
NOMAP loader option, OS/VS 126
NOMAP, DOS/VSE linkage editor control
option 128
V/
256 VS FORTRAN Application Programming! Guide
c
nonexecutable statement* definition 7,
38, 243
nonexi sting fi le, definition 243
NOOBJECT compiler option 73
N0OPTIMI2E compiler option 73
NOPRINT loader option, OS/VS 127
NORES loader option, OS/VS 127
NOSOURCE compiler option 74
notation, substring 49
NOTERMINAL compiler option 74
NOXREF compiler option 74
number, 1 i brary message 135
numeric character, definition 243
numeric constant, definition 243
numeric constant, PAUSE statement
and 67
numeric constant, STOP statement and 67
H
OBJ file, 0S/VS2-TS0 105
OBJECT compiler option
description 73
produces load module 124
OBJECT compiler option, 0S/VS2-TS0
considerations 105
object module
card image listing, compiler
output 90
cataloging 92
cataloging, DOS/VSE 92, 127
cataloging, OS/VS 92
compiler default 89
compiler output 21
DECK option and 122
END record in 124
ESD record in 123
example of listing 148
example of structure 124
link-editing 122-129
link-editor input 122
listing, compiler output 90
listing, optimization usage 219
obtaining listing of 143-148
RLD record in 123
TXT record in 123
object of a branch, cross reference
dictionary lists 119
OBJECT option, produces load module 127
object time efficiency, illustration of
EQUIVALENCE 54
old FORTRAN, definition iv
old FORTRAN, description 1
old language, definition iv
OPEN statement
description 153-155
di rect f i les 171
EXTENT statement and, DOS/VSE VSAM
files 183
invalid for VSAM-managed sequential
files (DOS/VSE) 179
sequential files 161
VSAM direct file considerations 177
VSAM sequential file
considerations 176
operands, recognition of constant 217
operation interrupt message 223
operator message format 139
operator message identification 139
operator messages 138-139
operator precedence in expressions
arithmetic 55
arithmetic operators 15
logical 57
order of 53
operator responses
PAUSE statement 67, 139
operator, communicating with 67-68
OPSYS, using in DOS/VSE 211
OPTIMIZE compiler option
arithmetic conversions, avoiding 218
array initialization 214
array operands and 213
arrays, optimizing identically
dimensioned 217
arrays, opt imi zi ng wi th identical
elements 217
arrays, variably dimensioned not
recommended 215
COMMON blocks, using efficiently 215
common expressions, 0PTIMIZE(3)
eliminates 220
constant operand recognition 217
description 73
double precision conversions and 218
duplicate computation
recognition 216, 217
efficient accumulator usage 218
efficient arithmetic constructions
and 218
efficient program size 213
EQUIVALENCE statement not
recommended 214
higher levels best 213
IF statement and 219
instruction elimination,
0PTIMIZEC3) 220
integer variables and 214
logical variables and 214
loops and 0PTIMIZEC3) 220
object listing and 219
object module useful with 143
OPTIMIZED) considerations 219-221
passing subroutine arguments in
COMMON 215
scaling elimination 217
single precision conversions and 218
source program
considerations 213-221
unformatted input/output and 213
variables, optimization
. limi tati ons 218
writing loops inline 216
0PTIMIZE(3), common errors using 69
OPTION control statement, DOS/VSE
description 85
option table, warning on error
occurrences 143
OR sign ( I ), job control syntax 72
organization of this manual iii
origin of library messages 135
0S/VS1 considerations
abnormal termination dumps 150
automatic cross compilation 71
batch compilation 76
cataloged load modules, using 131
cataloged procedures 77-84
cataloging load modules 125
cataloging source program 90
compilation data sets 76-77
compile-only cataloged procedure 20
compile, link-edit and execute
job 131
Index
257
compiler options and 72
data sets needed for execution 130
defining records 186-187
direct access labels 185
di rect f i les 173
execution-only job 131
job control statements 74-76
link-edit and execute job 131
link-edit execution 125-126
linkage editor, using 125-126
load module execution 131-132
loader, using 126-127
message codes 115
object module, cataloging 92
overlays 210-211
program execution 26-27
publications v-vi
requesting compilation 20-21, 76
sequential files 170
tape labels 184
VSAM DEFINE command 181
VSAM file creation 182
VSAM file processing 182
output li sting
general description 89-90
illustration of 91
simplified programming 21
using 112-120
using the object module
listing 143-148
output listing header 112
output, link-editing 129
output, program
error free 29, 134
with errors 30, 134
OVEND (end of modifiers) statement,
D05/VSE 89
overlay 210-212
OVERLAY control statement, OS/VS 210
overview, VS FORTRAN 1-3
OVLY linkage editor option, OS/VS 126
E3
PARAMETER statement
advantages in using 46
BLOCK DATA subprogram and 209
data initialization and 50
names constants 11-12, 46
parameter, symbolic 77-84
parentheses (), in arithmetic
expressions 15
parentheses (), in array declarators 48
parentheses (), in substring
notation 49
parentheses (), job control syntax 71
passing arguments between
programs 190-192
PAUSE statement
description 67
operator message and 139
PDUMP, requests dynamic dump 149
period (.), job control syntax 71
PHASE control statement, DOS/VSE
linkage editor "128
overlay and 211
phase, DOS/VSE
execution of 130, 133-134
logical units needed for
execution 132
precision errors, common 69
precision in arithmetic results,
ensuring needed 55
preconnected file, definition 243
predefined CALL statements
predefined specification,
definition 243
predetermined data type definitions 9
preface i i i -vi
prefixes for messages 29
primary, definition 243
principal diagonal, initializing 51
PRINT command, VM/370-CMS 94
PRINT loader option, OS/VS 127
printer files, VM/370-CMS 99
printing program results 18
PROC statement, modifying in cataloged
procedures 82
procedure subprogram, definition 243
procedure, definition 243
PROCESS, 3), statement 76
processing options, OS/VS linkage
editor 125
program action after library
messages 135
program constants
See constant
program desi gn
complete FORTRAN programming 34-37
resources available and 34
simplified FORTRAN programming 6
top-down development and 34-37
typical structure and 34
program interrupt messages 137-138
program output
error free 29, 134
with errors 30, 134
program references, substring references
vali d in 49
PROGRAM statement, using 201
program stub 34
program switches, assigned GO TO
statement 66
program termination, ends DO loop
execution 65
program uni t
definition 243
sharing storage between 193-201
program-name
program, coding
See coding your program
program, sample 31
programming, general logic structure 6
publi cat i ons
current FORTRAN source programs 7
current language documented in this
book 2
DOS/VSE publications vi
MVS publications v
old FORTRAN source programs 7
OS/VS publications v-vi
0S/VS1 publications v-vi
related systems publications v-vi
usage of 2-3
usage, illustration 3
VM/370-CMS publications v
VS FORTRAN Application
Programming iv
VS FORTRAN Installation and
Customization iv-v
PUNCH command, VM/370-CMS 94
punctuation, common errors in 68
^"Yf
258 VS FORTRAN Application Programming: Guide
en
c
QUIT, EDIT subcommand, VM/370-CMS 94
m
READ statement
asynchronous 165
description 155
direct files 172-173
directly accessed VSAM direct
files 178
errors in 30
FORMAT statement and 157
internal files 168, 169
internal, simplified FORTRAN
programming 8
list-directed 167
sequential files 162
sequentially accessed VSAM direct
files 177
simplified FORTRAN programming 7-8
unformatted record size and 186
VSAM considerations 176
real constant with real exponent,
defining 43
real constant, definition 243
real data type
constant 42
constant, defining by value 43-44
default names for 9
defining 10
definition 243
description 39-41
general description 9
internal representation 233-234
predetermined definition 9
reference length in common 196
subscripts 47
valid in arithmetic expressions 55
valid lengths 39
variable in DO statement 65
real part of a complex constant,
defining 44
RECFM=F required for direct files 173
record formats, direct access files 186
record formats, OS/VS 185-186, 187
record formatting, OPEN statement
and 155
record length, OPEN statement and 155
record size, source program 20
record, definition 243
records, defining 185-188
recursive calls, common coding
errors 69
reference number, data set
(definition) 241
reference numbers, for DOS/VSE
execution 132
reference numbers, for OS/VS
execution 130
REFERENCES column in cross-reference
dictionary 119, 120
references, substring 49
register usage, traceback map lists 136
relational expression
character operands in 57
description 56-57
in subprograms 207-208
relational operators in 53
relational expression, definition 243
relational operator, definition 243
relational operators and their
meanings 56
relative record data set (RRDS), source
language considerations 175-179
relative record number, in direct
files 170
remainder, integer division
truncates 55
RENAME command, VM/370-CMS 94
repeated format specifications 160
reply to PAUSE statement, operator 67
RES loader option, OS/VS 127
RETURN statement
ends DO loop execution 65
invalid as DO loop terminal
statement 65
simulated in assembler
subprograms 232
REWIND statement
invalid for directly accessed VSAM
di rect f i les 178
sequential files 163
sequentially accessed VSAM direct
files 177, 178
VSAM sequential file
considerations 176
RLD record, in object module 123
routines, listed in traceback map 136
RRDS, under 0S/VS2-TS0 111
RRDS, under VM/370-CMS 99-101
RRDS, VSAM direct files 174
rules for use 192
RUN command, VM/370-CMS 94
m
S, severe error code 22, 114
SAM data sets, VSAM-managed sequential
files 174
sample program 31
SAVE statement
BLOCK DATA subprogram and 209
in subprograms 208
SAVE, EDIT subcommand, 0S/VS2-TS0 103
SC compiler option 73
scale factor, definition 243
secondary input, defining using
VM/370-CMS 97
sequential access, VSAM direct
files 177-178
sequential file processing
ASCII considerations 186
asynchronous input/output
statements 164-166
CMS FILEDEF command and 98
complete FORTRAN programming 161-170
concatenating, warning on 161
devices valid for 161
EBCDIC encoded records 186
formatted, description 157-160
internal files and 168
list-directed 166-168
READ, simplified FORTRAN
programming 7"*8
source program
considerations 161-166
Index
259
unformatted, description 157
valid VSAM source statements,
summary 175
VM/370-CMS 98-99
VSAM considerations 174-183
VSAM source language 175-179
WRITE, simplified FORTRAN
programming 18
service routine library
functions 222-223
severe error code 22
severity level, compiler messages 114
sharing data between programs 190-201
simplified FORTRAN programming
coding your program 7-19
common coding errors 19
compiling your program 20-21
description 5-31
designing your program 6
executing your program 26-28
fixing compile time errors 22-23
fixing execution time errors 29-30
general description 5
link-editing your program 24-25
single precision, conversions of 218
SIZE linkage editor option, OS/VS 126
SIZE loader option, OS/VS 127
SIZE parameter, VSAM file
processing 183
slash (/), job control syntax 71
slashC/), format code 158
SOURCE compiler option 74,112-113
SOURCE compiler option, 0S/VS2-TS0
considerations 105
source program
cataloging 90-91
direct file processing 171-173
efficient size 213
input/output 152-188
internal files in 168-170
sequential f i le
considerations 161-168
using 0S/VS2-TS0 102-104
using VM/370-CMS 93-95 »
source program elements, definition 7
source program listing
compiler default 89
description 112-113
simplified FORTRAN programming. 21
using MAP and XREF 115
source program map, using 115
source program optimization, detailed
description 213-221
source program reordering,
0PTIMIZEC3) 220
SP, format code 158
spanned records, description 186
specification statement, definition 243
specification subprogram,
definition 243
SPF (Structure Programming Facility),
using under TSO 102
square brackets ([]), job control
syntax 72
SS, format code 158
standard file labels, direct access 184
standard file labels, tape files 183
standard user labels, direct access 185
standard user labels, tape files 183
standards
applicable for VS FORTRAN iii-iv
current FORTRAN iv
current standard, definition iv
FORTRAN 77, definition iv
old FORTRAN iv
old standard, definition iv
START command, VM/370-CMS 94
statement
definition 7, 38
specification, and data
initialization 50
statement function
common coding error 69
cross reference dictionary lists 119
def i ni ti on of 60
definition, placement of in
program 61
description 60-61
references to in program 61
storage map lists 116
statement function definition,
definition 243
statement function reference,
definition 243
statement function, definition 243
statement labels 239
statement number
assembler subprograms and 232
ASSIGN statement sets 66
assigned GO TO statement list 66
cross reference dictionary lists 119
definition 243
dictionary, compiler output 119
END statement, valid in 19, 68
storage maps and 118
statement number, definition 243
statement number, description 12
statement options, input/output 152
STATUS command, 0S/VS2-TS0 103
STEPLIB DD, using 131
STOP statement
causes program termination 139
description 67
ends DO loop execution 65
invalid as DO loop terminal
statement 65
operator message and 139
storage map description 116-118
storage map, example 116
storage sharing
See EQUIVALENCE statement
Structure Programming Facility (SPF),
using under TSO 102
structured programming, description 61
stub, program 34
SUBMIT command, 0S/VS2-TS0 103
subprogram
arguments in, general rules 192
BLOCK DATA 208-209
coding 205-209
common coding errors 69
cross reference dictionary names 119
definition 189, 244
FUNCTION 205-207
function, general description 189
general description 189
intrinsic function, general
description 190
intrinsic functions, using 201-203
invocation example 189
paired arguments in 190
storage map lists 116
SUBROUTINE 206-208
subroutine, general description 189
top-down development and 37
SUBROUTINE statement, in subprogram 206
\j?
260 VS FORTRAN Application Programming? Guide
SUBROUTINE subprogram
arguments in 191-192
CALL OPSYS loads, DOS/VSE 211
coding 206-208
definition 244
ENTRY statement in 206-207
general description 189
invoking 204
paired arguments in 190
RETURN statement in 207-208
SAVE statement as documentation 208
top-down development and 37
using 203-204
subscript
complete FORTRAN programming 47
defining 12-13
definition 244
description 46-49
explicit louer bounds and 48
implicit lower bounds and 47
initializing array elements and 50
initializing character array elements
and 50
integer variable as 13
invalid values for, common coding
error 69
multidimensional arrays and 47
one-dimensional arrays and 12, 47
order of processing 47
programming considerations 49
signed 48-49
subscript quantity, definition 244
subset FIPS flagging 121
substring notation 49
substring, internal file unit 168
substrings of character items 49, 60
subtraction, evaluation order 15, 55
summary of errors, in traceback map 136
symbolic debugging example 141
symbolic parameter 77-84
syntactical unit, definition 72
syntax errors, compile-only runs
find 20
syntax errors, MAP option helps find 116
syntax, job control statements 71-72
SYSCLB, DOS/VSE link-edit logical
unit 128
SYSIN, data set for OS/VS execution 130
SYSIN, logical unit for DOS/VSE
execution 132
SYSIN, required OS/VS compilation data
set 77
SYSIPT, logical unit for OS/VS
execution 132
SYSLIB required for CMS 95
SYSLIB, optional for OS/VS linkage
editor 126
SYSLIB, optional OS/VS compilation data
set 77
SYSLIB, optional OS/VS loader data
set 127
SYSLIB, OS/VS
catalogs OS/VS object module 92
catalogs source program 90
SYSLIN, optional OS/VS compilation data
set 77
SYSLIN, OS/VS loader required data
set 127
SYSLIN, required for OS/VS linkage
editor 126
SYSLMOD, cataloging load modules
and 125
SYSLMOD, required for OS/VS linkage
editor 126
SYSLNK, DOS/VSE link-edit logical
unit 128
SYSLOUT, optional OS/VS loader data
set 127
SYSLST, DOS/VSE link-edit logical
unit 128
SYSPRINT, required for OS/VS linkage
editor 126
SYSPRINT, required OS/VS compilation
data set 77
SYSPRINT, required OS/VS loader data
set 127
SYSPUNCH, optional OS/VS compilation
data set 77
SYSRES, DOS/VSE link-edit logical
unit 128
SYSRLB, DOS/VSE link-edit logical
unit 128
system considerations, direct
files 173-174
system considerations, sequential
files 170
system considerations, TSO 111
SYSTERM, optional for OS/VS linkage
editor 126
SYSTERM, optional OS/VS compilation data
set 77
SYSUT1, required for OS/VS linkage
editor 126
SYS001, DOS/VSE link-edit logical
unit 128
m
38
TAG column in cross reference
dictionary 119
TAG column, in storage map 117
tape f i les
ASCII considerations 186
CMS FILEDEF command and 98-99
tape labels
description of use 183-184
processing 183-184
TERM compiler option, 0S/VS2-TS0
considerations 105
termi nal
free-form input useful with
source input device 20
using with 0S/VS2-TS0 102
using with VM/370-CMS 93
TERMINAL compiler option 74
terminal files, VM/370-CMS FILEDEF
command and 99
TEST command, 0S/VS2-TS0 103
TEXT file, VM/370-CMS 96
Time Sharing Option
See TSO (Time Sharing Option)
time, in output listing header 112
TL, format code 158
TLBL control statement, tape labels
and 184
top-down design and development
advantages of 35
description 34-37
example 36
F0RTPAN considerations 36-37
INCLUDE statement and 36-37
subprograms and 37
Index
261
TR, format coda 158
TRACE ON | OFF statements,
description 140
TRACE ON/OFF statements,
description 140
traceback map
description 135-136
trailer labels, when processed 184
transfer of control, ends DO loop
execution 65
truncation, common coding error 68
TSO (Time Sharing Option)
ALLOCATE command 110-111
background command procedures 108
command procedures under 108
compilation 104-105
creating source programs 102-104
description of use 102-111
executing 105-107
file naming conventions 109
foreground command procedures 108
free form source and 105
linkage editor listings 106
LIST compiler option and 105
loader program and 107
loading 105-107
logoff 102
logon 102
MAP compiler option and 105
OBJECT compiler option and 105
SOURCE compiler option and 105
system considerations 111
TERM compiler option and 105
terminal usage 102
using commands 102
VSAM data files 111
TSO command procedures 108
TSO commands, using 102
TXT record, in object module 123
TYPE command, VM/370-CMS 94
type declaration, definition 244
type statement
See explicit type statement
uppercase items, job control syntax 71
user standard labels, direct access 185
user standard labels, tape files 183
using terminals 93, 102
m
U, unrecoverable error code 22, 115
unconditional GO TO, invalid as DO loop
terminal statement 65
undefined length records,
description 186
unformatted input/output 157
unformatted record, definition 244
unformatted records, EBCDIC encoded
files 186
unit
definition 244
external, in input/output 153
external, in READ 8
external, in WRITE 18
internal, in READ 8
internal, in READ and WRITE 168
unit identifier, definition 244
UNIT option, input/output 153
unit record files, VM/370-CMS FILEDEF
command and 99
unit, INQUIRE statement and 156
unrecoverable error code 22
upper bound, in substring notation 49
upper bounds, in arrays 48
variable
accumulator usage 218
and assembler subprograms 231
as actual arguments 192
assignment statement 58
character, hexadecimal constants
i ni tial i ze 45
character, substrings of 49
definition 244
description 42
dummy, for alignment in common 195
efficient common arrangement 195-197
EQUIVALENCE statement and 51
example in WRITE statement 18
expressions and 53
fixed order alignment in common 195
integer or real, in DO statement 65
internal file unit 168
internal representation 232-235
optimization limitations 218
READ statement example 8
recognition when constant 217
storage map lists 116
subscript 13
subscripts 47
variable format specifications 160
variable-length records,
description 185
VM/370-CMS considerations
compilation 95-96
compiler options and 72
creating source programs 93-95
description of use 93-101
executing 97
file identifier 98
FILEDEF command for data files 98-99
filemode 98
f i lename 98
filetype 98
free form source and 96
library availability 96-97
load module creation 97
loading 97
logoff 93
logon 93
terminal usage 93
VSAM data files 99-101
VSAM file creation 101
VSAM file definition under 100
VSAM file processing 101
volume labels, direct access 184
volume labels, tape files 183
VS FORTRAN
coding form 7
common coding errors 68-70
complete FORTRAN programming 33-150
current FORTRAN language level 1
current language documented in this
book 2
extensions, how documented 3
features 1-2
general description 1-3
input/output features 152-188
-j^
262 VS FORTRAN Application Programming : Guide
old FORTRAN language level 1
overview 1-3
reference numbers for DOS/VSE
execution 132
reference numbers for OS/VS
execution 130
simplified FORTRAN programming 5-31
source input format rules 20
source program elements 7
special features 101, 111, 151
VSAM file processing
catalog entry creation 179-181
complete FORTRAN programming 174-183
creation of files 182-183
IOSTAT option obtains return
code 179
processing of files 182-183
source language
considerations 175-179
under 0S/VS2-TS0 111
under VM/370-CMS 99-101
valid source statements, summary 175
VSAM-managed sequential files
(DOS/VSE) 179
VSCOM, common errors using 69
unformatted record size and
VSAM considerations 176
186
H
74, 115
detai led
XREF compiler option
XREF compiler option,
description 120
XREF compiler option, output 90
XREF linkage editor option, OS/VS
125
yy, operator message identifier 139
m
U, warning error code 22, 114
WAIT statement, asynchronous
input/output 165-166
waits, errors in 29
warning error code 22
WRITE statement
asynchronous 164-165
description 155
direct files 171-172
directly accessed VSAM direct
files 178
errors in 30
FORMAT statement and 157
internal files 168, 169
list-directed 168
sequential files 161-162
sequentially accessed VSAM direct
files 177
simplified FORTRAN programming 18
0, in operator message 139
0, informational code 22, 114
m
12, severe error code 22, 114
16, abnormal termination code 22, 115
4, warning error code 22, 114
H
8, error code 22, 114
^pl|v
Index
263
SC26-3985-2
<
CO
Tl
O
30
H
>
>
■o
■o
o
3
"D
-^
O
CO
-1
Q>
3
3
5"
to
a.
z
p
CO
CO
VI
o
C71
5'
s.
5'
c
CO
>
CO
o
O)
CO
CO
00
c
