Trailing-Edge
-
PDP-10 Archives
-
fortv11
-
manual.mem
There are no other files named manual.mem in the archive.
TOPS-10/20 FORTRAN
Language Manual
| AD-N383B-T1
| February 1987
This document describes the language elements of FORTRAN-10 and
FORTRAN-20.
| This manual supercedes the TOPS-10/20 FORTRAN Language Manual, Order
| Number AA-N383B-TK.
| OPERATING SYSTEM: TOPS-10, V7.03
| TOPS-20, V4.1 (KS)
| TOPS-20, V6.0 (KL)
|
| SOFTWARE: FORTRAN-10, Version 11
| FORTRAN-20, Version 11
| LINK-10, Version 5.1
| LINK-20, Version 6
| RMS-20, Version 3
i
First Printing, February 1983
Revised, May 1985
| Updated, February 1987
The information in this document is subject to change without notice
and should not be construed as a commitment by Digital Equipment
Corporation. Digital Equipment Corporation assumes no responsibility
for any errors that may appear in this document.
The software described in this document is furnished under a license
and may only be used or copied in accordance with the terms of such
license.
No responsibility is assumed for the use or reliability of software on
equipment that is not supplied by DIGITAL or its affiliated companies.
| Copyright C , 1987, Digital Equipment Corporation.
All Rights Reserved.
The postage-prepaid READER'S COMMENTS form on the last page of this
document requests the user's critical evaluation to assist us in
preparing future documentation.
The following are trademarks of Digital Equipment Corporation:
DEC DECnet IAS
DECUS DECsystem-10 MASSBUS
Digital Logo DECSYSTEM-20 PDT
PDP DECwriter RSTS
UNIBUS DIBOL RSX
VAX EduSystem VMS
VT
ii
CONTENTS
CHAPTER 1 INTRODUCTION
1.1 OVERVIEW . . . . . . . . . . . . . . . . . . . . . 1-1
1.2 MANUAL ORGANIZATION . . . . . . . . . . . . . . . 1-2
1.2.1 FORTRAN Language Elements (Part I) . . . . . . . 1-2
1.2.2 FORTRAN Statements (Part II) . . . . . . . . . . 1-2
1.2.3 FORTRAN Language Usage (Part III) . . . . . . . 1-3
1.2.4 APPENDIXES . . . . . . . . . . . . . . . . . . . 1-4
CHAPTER 2 CHARACTERS AND LINES
2.1 CHARACTER SET . . . . . . . . . . . . . . . . . . 2-1
2.2 STATEMENT DEFINITION AND FORMAT . . . . . . . . . 2-3
2.2.1 Statement Label Field and Statement Numbers . . 2-3
2.2.2 Line Continuation Field . . . . . . . . . . . . 2-4
2.2.3 Statement Field . . . . . . . . . . . . . . . . 2-4
2.2.4 Remark Field . . . . . . . . . . . . . . . . . . 2-4
2.3 LINE TYPES . . . . . . . . . . . . . . . . . . . . 2-5
2.3.1 Initial and Continuation Lines . . . . . . . . . 2-5
2.3.2 Multi-Statement Lines . . . . . . . . . . . . . 2-6
2.3.3 Comment Lines and Remarks . . . . . . . . . . . 2-6
2.3.4 Debug Lines . . . . . . . . . . . . . . . . . . 2-7
2.3.5 Blank Lines . . . . . . . . . . . . . . . . . . 2-8
2.4 LINE-SEQUENCED SOURCE FILES . . . . . . . . . . . 2-8
CHAPTER 3 CONSTANTS
3.1 INTRODUCTION . . . . . . . . . . . . . . . . . . . 3-1
3.2 INTEGER CONSTANTS . . . . . . . . . . . . . . . . 3-1
3.3 REAL CONSTANTS . . . . . . . . . . . . . . . . . . 3-2
3.4 DOUBLE-PRECISION CONSTANTS . . . . . . . . . . . . 3-3
3.4.1 Comparison of Real, D-floating, and G-floating . 3-4
3.5 COMPLEX CONSTANTS . . . . . . . . . . . . . . . . 3-4
3.6 CHARACTER CONSTANTS . . . . . . . . . . . . . . . 3-5
3.7 OCTAL AND DOUBLE-OCTAL CONSTANTS . . . . . . . . . 3-6
3.8 LOGICAL CONSTANTS . . . . . . . . . . . . . . . . 3-7
3.9 HOLLERITH CONSTANTS . . . . . . . . . . . . . . . 3-7
3.10 STATEMENT LABEL CONSTANTS . . . . . . . . . . . . 3-8
CHAPTER 4 SYMBOLIC NAMES, VARIABLES, AND ARRAYS
4.1 SYMBOLIC NAMES . . . . . . . . . . . . . . . . . . 4-1
4.2 VARIABLES . . . . . . . . . . . . . . . . . . . . 4-2
4.3 ARRAYS . . . . . . . . . . . . . . . . . . . . . . 4-3
4.3.1 Array Element Subscripts . . . . . . . . . . . . 4-3
iii
4.3.2 Dimensioning Arrays . . . . . . . . . . . . . . 4-4
4.3.3 Order of Stored Array Elements . . . . . . . . . 4-6
4.4 CHARACTER SUBSTRINGS . . . . . . . . . . . . . . . 4-8
CHAPTER 5 EXPRESSIONS
5.1 ARITHMETIC EXPRESSIONS . . . . . . . . . . . . . . 5-1
5.1.1 Rules for Writing Arithmetic Expressions . . . . 5-2
5.1.2 Arithmetic Constant Expressions . . . . . . . . 5-6
5.1.2.1 Integer Constant Expression . . . . . . . . . 5-6
5.2 CHARACTER EXPRESSIONS . . . . . . . . . . . . . . 5-6
5.2.1 Character Constant Expression . . . . . . . . . 5-8
5.3 LOGICAL EXPRESSIONS . . . . . . . . . . . . . . . 5-8
5.3.1 Logical Constant Expression . . . . . . . . . 5-11
5.4 RELATIONAL EXPRESSIONS . . . . . . . . . . . . . 5-12
5.5 EVALUATION OF EXPRESSIONS . . . . . . . . . . . 5-14
5.5.1 Parenthetical Subexpressions . . . . . . . . . 5-14
5.5.2 Hierarchy of Operators . . . . . . . . . . . . 5-15
5.5.3 Mixed-Mode Expressions . . . . . . . . . . . . 5-16
5.5.4 Use of Logical Operands in Mixed-Mode
Expressions . . . . . . . . . . . . . . . . . 5-17
5.6 CONSTANT EXPRESSIONS . . . . . . . . . . . . . . 5-17
CHAPTER 6 EXECUTABLE AND NONEXECUTABLE STATEMENTS
6.1 EXECUTABLE STATEMENTS . . . . . . . . . . . . . . 6-1
6.2 NONEXECUTABLE STATEMENTS . . . . . . . . . . . . . 6-2
6.3 ORDERING OF FORTRAN STATEMENTS . . . . . . . . . . 6-3
6.4 COMPILATION CONTROL STATEMENTS . . . . . . . . . . 6-5
6.4.1 PROGRAM Statement . . . . . . . . . . . . . . . 6-5
6.4.2 INCLUDE Statement . . . . . . . . . . . . . . . 6-5
CHAPTER 7 SPECIFICATION AND DATA STATEMENTS
7.1 DIMENSION STATEMENT . . . . . . . . . . . . . . . 7-1
7.1.1 Adjustable Dimensions . . . . . . . . . . . . . 7-3
7.1.2 Assumed-size Arrays . . . . . . . . . . . . . . 7-4
7.2 TYPE SPECIFICATION STATEMENTS . . . . . . . . . . 7-5
7.2.1 Numeric Type Specification Statements . . . . . 7-5
7.2.2 Character Type Specification Statements . . . . 7-7
7.3 IMPLICIT STATEMENTS . . . . . . . . . . . . . . . 7-8
7.4 COMMON STATEMENT . . . . . . . . . . . . . . . . 7-10
7.4.1 Dimensioning Arrays in COMMON Statements . . . 7-12
7.4.2 Character Data in COMMON . . . . . . . . . . . 7-12
7.5 EQUIVALENCE STATEMENT . . . . . . . . . . . . . 7-13
7.5.1 EQUIVALENCE and Extended Addressing . . . . . 7-22
7.6 EXTERNAL STATEMENT . . . . . . . . . . . . . . . 7-22
7.7 INTRINSIC STATEMENT . . . . . . . . . . . . . . 7-23
7.8 PARAMETER STATEMENT . . . . . . . . . . . . . . 7-25
iv
7.9 DATA STATEMENT . . . . . . . . . . . . . . . . . 7-26
7.10 SAVE STATEMENT . . . . . . . . . . . . . . . . . 7-30
CHAPTER 8 ASSIGNMENT STATEMENTS
8.1 ARITHMETIC ASSIGNMENT STATEMENT . . . . . . . . . 8-1
8.2 LOGICAL ASSIGNMENT STATEMENTS . . . . . . . . . . 8-4
8.3 ASSIGN (STATEMENT LABEL) ASSIGNMENT STATEMENT . . 8-5
8.4 CHARACTER ASSIGNMENT STATEMENT . . . . . . . . . . 8-6
CHAPTER 9 CONTROL STATEMENTS
9.1 GO TO STATEMENTS . . . . . . . . . . . . . . . . . 9-2
9.1.1 Unconditional GO TO Statements . . . . . . . . . 9-2
9.1.2 Computed GO TO Statements . . . . . . . . . . . 9-2
9.1.3 Assigned GO TO Statements . . . . . . . . . . . 9-3
9.2 IF STATEMENTS . . . . . . . . . . . . . . . . . . 9-4
9.2.1 Arithmetic IF Statements . . . . . . . . . . . . 9-4
9.2.2 Logical IF Statements . . . . . . . . . . . . . 9-5
9.2.3 Logical Two-Branch IF Statements . . . . . . . . 9-5
9.2.4 Block IF Statements . . . . . . . . . . . . . . 9-6
9.2.4.1 Statement Blocks . . . . . . . . . . . . . . . 9-9
9.2.4.2 Block IF Examples . . . . . . . . . . . . . . 9-9
9.2.4.3 Nested Block IF Constructs . . . . . . . . . 9-10
9.3 DO STATEMENT . . . . . . . . . . . . . . . . . . 9-11
9.3.1 Indexed DO Statement . . . . . . . . . . . . . 9-11
9.3.1.1 Executing an Indexed DO Statement . . . . . 9-13
9.3.1.2 DO Iteration Control . . . . . . . . . . . . 9-14
9.3.2 DO WHILE Statement . . . . . . . . . . . . . . 9-15
9.3.3 The Range of a DO Statement . . . . . . . . . 9-16
9.3.4 Nested DO Statements . . . . . . . . . . . . . 9-16
9.3.5 Extended Range . . . . . . . . . . . . . . . . 9-18
9.3.6 Permitted Transfer Operations . . . . . . . . 9-19
9.4 END DO STATEMENT . . . . . . . . . . . . . . . . 9-20
9.5 CONTINUE STATEMENT . . . . . . . . . . . . . . . 9-20
9.6 STOP STATEMENT . . . . . . . . . . . . . . . . . 9-21
9.7 PAUSE STATEMENT . . . . . . . . . . . . . . . . 9-22
9.8 END STATEMENT . . . . . . . . . . . . . . . . . 9-23
CHAPTER 10 DATA TRANSFER STATEMENTS
10.1 DATA TRANSFER OPERATIONS . . . . . . . . . . . . 10-5
10.2 DATA ACCESS . . . . . . . . . . . . . . . . . . 10-5
10.2.1 Sequential Access . . . . . . . . . . . . . . 10-6
10.2.2 Direct Access . . . . . . . . . . . . . . . . 10-6
10.2.3 Keyed Access (TOPS-20 RMS) . . . . . . . . . . 10-6
10.3 FORMATTED AND UNFORMATTED DATA TRANSFERS . . . . 10-7
10.3.1 Formatted Data Transfers . . . . . . . . . . . 10-7
10.3.1.1 Internal Files . . . . . . . . . . . . . . . 10-8
v
10.3.2 Unformatted Data Transfers . . . . . . . . . . 10-9
10.3.3 Unformatted Data Transfer to ASCII Devices . . 10-9
10.4 DATA TRANSFER STATEMENT FORMS . . . . . . . . . 10-10
10.4.1 Data Transfer Statement Names . . . . . . . . 10-11
10.4.2 Data Transfer Control-Information List . . . . 10-11
10.4.3 Unit References in Data Transfer Statements . 10-13
10.4.3.1 FORTRAN Logical Unit Identifier . . . . . . 10-13
10.4.3.2 Internal File Identifier . . . . . . . . . . 10-16
10.4.4 Record Number References In Data Transfer
Statements . . . . . . . . . . . . . . . . . . 10-16
10.4.5 Format References in Data Transfer Statements 10-17
10.4.5.1 FORMAT-Statement Formatting . . . . . . . . 10-18
10.4.5.2 List-Directed Formatting . . . . . . . . . . 10-19
10.4.5.3 NAMELIST-Statement Formatting . . . . . . . 10-20
10.4.6 Optional End-of-File Transfer of Control
(END=) . . . . . . . . . . . . . . . . . . . . 10-21
10.4.7 Optional Data Transfer Error Control (ERR=) . 10-22
10.4.8 Optional Error Variable For Error Reporting
(IOSTAT=) . . . . . . . . . . . . . . . . . . 10-24
10.4.9 Key-Field-Value Specifier (TOPS-20 RMS) . . . 10-25
10.4.9.1 Key Attributes . . . . . . . . . . . . . . . 10-27
10.4.10 Key-of-Reference Specifier . . . . . . . . . . 10-27
10.4.11 Data Transfer Statement Input/Output Lists . . 10-27
10.4.11.1 Simple List Elements . . . . . . . . . . . . 10-28
10.4.11.2 Implied DO Lists . . . . . . . . . . . . . . 10-29
10.5 READ STATEMENT . . . . . . . . . . . . . . . . . 10-32
10.5.1 Formatted READ Transfers . . . . . . . . . . . 10-34
10.5.1.1 Sequential FORMAT-Statement READ . . . . . . 10-34
10.5.1.2 Direct-Access FORMAT-Statement READ . . . . 10-35
10.5.1.3 Sequential List-Directed READ . . . . . . . 10-36
10.5.1.4 Sequential NAMELIST-Statement READ . . . . . 10-37
10.5.2 Unformatted READ Transfers . . . . . . . . . . 10-37
10.5.2.1 Sequential Unformatted READ . . . . . . . . 10-38
10.5.2.2 Direct-Access Unformatted READ . . . . . . . 10-38
10.5.3 Indexed READ Transfers (TOPS-20) . . . . . . . 10-39
10.5.3.1 Sequential Indexed READ . . . . . . . . . . 10-40
10.5.3.2 Formatted Indexed READ . . . . . . . . . . 10-40
10.5.3.3 Unformatted Indexed READ . . . . . . . . . 10-41
10.6 WRITE STATEMENT . . . . . . . . . . . . . . . . 10-42
10.6.1 Formatted WRITE Transfers . . . . . . . . . . 10-44
10.6.1.1 Sequential FORMAT-Statement WRITE . . . . . 10-44
10.6.1.2 Direct-Access FORMAT-Statement WRITE . . . . 10-45
10.6.1.3 Sequential List-Directed WRITE . . . . . . . 10-46
10.6.1.4 Sequential NAMELIST-Statement WRITE . . . . 10-47
10.6.2 Unformatted WRITE Transfers . . . . . . . . . 10-48
10.6.2.1 Sequential Unformatted WRITE . . . . . . . . 10-49
10.6.2.2 Direct-Access Unformatted WRITE . . . . . . 10-49
10.6.3 Writing to RMS Files (TOPS-20) . . . . . . . . 10-50
10.7 REREAD STATEMENT . . . . . . . . . . . . . . . . 10-51
10.7.1 Sequential FORMAT-Statement REREAD . . . . . . 10-52
10.7.2 Sequential List-Directed REREAD . . . . . . . 10-53
10.8 ACCEPT STATEMENT . . . . . . . . . . . . . . . . 10-55
vi
10.8.1 Sequential FORMAT-Statement ACCEPT . . . . . . 10-55
10.8.2 Sequential List-Directed ACCEPT . . . . . . . 10-56
10.9 TYPE STATEMENT . . . . . . . . . . . . . . . . . 10-57
10.9.1 Sequential FORMAT-Statement TYPE . . . . . . . 10-58
10.9.2 Sequential List-Directed TYPE . . . . . . . . 10-59
10.10 PRINT STATEMENT . . . . . . . . . . . . . . . . 10-61
10.10.1 Sequential FORMAT-Statement PRINT . . . . . . 10-61
10.10.2 Sequential List-Directed PRINT . . . . . . . . 10-62
10.11 PUNCH STATEMENT . . . . . . . . . . . . . . . . 10-63
10.11.1 Sequential FORMAT-Statement PUNCH . . . . . . 10-64
10.11.2 Sequential List-Directed PUNCH . . . . . . . . 10-65
10.12 INTERNAL FILES AND ENCODE/DECODE STATEMENTS . . 10-65
10.12.1 Internal READ and WRITE Statements . . . . . . 10-66
10.12.2 ENCODE and DECODE Statements . . . . . . . . . 10-68
10.13 DELETE STATEMENT (TOPS-20 RMS) . . . . . . . . . 10-72
10.13.1 Current-Record DELETE . . . . . . . . . . . . 10-73
10.13.2 Direct-Access DELETE . . . . . . . . . . . . . 10-73
10.14 REWRITE STATEMENT (TOPS-20 RMS) . . . . . . . . 10-74
10.14.1 Formatted REWRITE . . . . . . . . . . . . . . 10-75
10.14.2 Unformatted REWRITE Statement . . . . . . . . 10-75
10.15 UNLOCK STATEMENT (TOPS-20) . . . . . . . . . . . 10-75
CHAPTER 11 FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
11.1 FILE-CONTROL STATEMENTS . . . . . . . . . . . . 11-1
11.2 OPEN STATEMENT . . . . . . . . . . . . . . . . . 11-2
11.2.1 Implicit OPEN . . . . . . . . . . . . . . . . 11-3
11.2.2 OPEN on a Connected Unit . . . . . . . . . . . 11-4
11.3 OPEN STATEMENT SPECIFIERS . . . . . . . . . . . 11-4
11.3.1 ACCESS Specifier . . . . . . . . . . . . . . . 11-7
11.3.2 ASSOCIATEVARIABLE Specifier . . . . . . . . . 11-9
11.3.3 BLANK Specifier . . . . . . . . . . . . . . . 11-10
11.3.4 BLOCKSIZE Specifier . . . . . . . . . . . . . 11-11
11.3.5 BUFFERCOUNT Specifier . . . . . . . . . . . . 11-12
11.3.6 BYTESIZE Specifier . . . . . . . . . . . . . . 11-13
11.3.7 CARRIAGECONTROL Specifier . . . . . . . . . . 11-13
11.3.8 DEFAULTFILE Specifier (TOPS-20) . . . . . . . 11-15
11.3.9 DENSITY Specifier . . . . . . . . . . . . . . 11-16
11.3.10 DEVICE Specifier . . . . . . . . . . . . . . . 11-16
11.3.11 DIALOG Specifier . . . . . . . . . . . . . . . 11-17
11.3.12 DIALOG= Specifier . . . . . . . . . . . . . . 11-18
11.3.13 DIRECTORY Specifier (TOPS-10) . . . . . . . . 11-18
11.3.14 DIRECTORY Specifier (TOPS-20) . . . . . . . . 11-20
11.3.15 DISPOSE Specifier . . . . . . . . . . . . . . 11-20
11.3.16 ERR Specifier . . . . . . . . . . . . . . . . 11-21
11.3.17 FILE Specifier . . . . . . . . . . . . . . . . 11-22
11.3.17.1 Remote File Specifications (TOPS-20) . . . . 11-23
11.3.18 FILESIZE (INITIALIZE) Specifier (TOPS-10 Only) 11-23
11.3.19 FORM Specifier . . . . . . . . . . . . . . . . 11-24
11.3.20 IOSTAT Specifier . . . . . . . . . . . . . . . 11-25
11.3.21 KEY Specifier (TOPS-20) . . . . . . . . . . . 11-26
vii
11.3.22 LIMIT Specifier . . . . . . . . . . . . . . . 11-27
11.3.23 MAXREC Specifier (TOPS-20) . . . . . . . . . . 11-28
11.3.24 MODE Specifier . . . . . . . . . . . . . . . . 11-28
11.3.25 NAME Specifier . . . . . . . . . . . . . . . . 11-30
11.3.26 NOSPANBLOCKS Specifier (TOPS-20) . . . . . . . 11-31
11.3.27 ORGANIZATION Specifier (TOPS-20) . . . . . . . 11-31
11.3.28 PADCHAR Specifier . . . . . . . . . . . . . . 11-32
11.3.29 PARITY Specifier . . . . . . . . . . . . . . . 11-33
11.3.30 PROTECTION Specifier (TOPS-10) . . . . . . . . 11-33
11.3.31 PROTECTION Specifier (TOPS-20) . . . . . . . . 11-37
11.3.32 READONLY Specifier . . . . . . . . . . . . . . 11-38
11.3.33 RECL (RECORDSIZE) Specifier . . . . . . . . . 11-39
11.3.34 RECORDTYPE Specifier . . . . . . . . . . . . . 11-41
11.3.35 SHARED Specifier . . . . . . . . . . . . . . . 11-43
11.3.36 STATUS (TYPE) Specifier . . . . . . . . . . . 11-44
11.3.37 TAPEFORMAT SPECIFIER . . . . . . . . . . . . . 11-46
11.3.38 UNIT Specifier (Required) . . . . . . . . . . 11-47
11.3.39 USEROPEN Specifier (TOPS-20) . . . . . . . . . 11-47
11.3.40 VERSION Specifier (TOPS-10) . . . . . . . . . 11-48
11.4 CLOSE STATEMENT . . . . . . . . . . . . . . . . 11-48
11.4.1 Implicit CLOSE . . . . . . . . . . . . . . . . 11-49
11.5 CLOSE STATEMENT SPECIFIERS . . . . . . . . . . . 11-49
11.5.1 DEVICE, DIRECTORY, FILE, NAME, and PROTECTION
Specifiers . . . . . . . . . . . . . . . . . . 11-51
11.5.2 DIALOG Specifier . . . . . . . . . . . . . . . 11-51
11.5.3 DIALOG= Specifier . . . . . . . . . . . . . . 11-52
11.5.4 DISPOSE Specifier . . . . . . . . . . . . . . 11-53
11.5.5 ERR Specifier . . . . . . . . . . . . . . . . 11-54
11.5.6 IOSTAT Specifier . . . . . . . . . . . . . . . 11-55
11.5.7 LIMIT Specifier . . . . . . . . . . . . . . . 11-55
11.5.8 STATUS Specifier . . . . . . . . . . . . . . . 11-56
11.5.9 UNIT Specifier (Required) . . . . . . . . . . 11-57
11.6 OPEN AND CLOSE STATEMENT EXAMPLES . . . . . . . 11-57
11.7 INQUIRE STATEMENT . . . . . . . . . . . . . . . 11-58
11.7.1 INQUIRE by File . . . . . . . . . . . . . . . 11-58
11.7.2 INQUIRE by Unit . . . . . . . . . . . . . . . 11-59
11.7.3 INQUIRE Specifiers . . . . . . . . . . . . . . 11-60
11.7.3.1 ACCESS Specifier . . . . . . . . . . . . . . 11-60
11.7.3.2 BLANK Specifier . . . . . . . . . . . . . . 11-60
11.7.3.3 BYTESIZE Specifier . . . . . . . . . . . . . 11-61
11.7.3.4 CARRIAGECONTROL Specifier . . . . . . . . . 11-61
11.7.3.5 DIRECT Specifier . . . . . . . . . . . . . . 11-61
11.7.3.6 ERR Specifier . . . . . . . . . . . . . . . 11-62
11.7.3.7 EXIST Specifier . . . . . . . . . . . . . . 11-62
11.7.3.8 FORM Specifier . . . . . . . . . . . . . . . 11-62
11.7.3.9 FORMATTED Specifier . . . . . . . . . . . . 11-63
11.7.3.10 IOSTAT Specifier . . . . . . . . . . . . . . 11-63
11.7.3.11 KEYED Specifier . . . . . . . . . . . . . . 11-63
11.7.3.12 NAME Specifier . . . . . . . . . . . . . . . 11-63
11.7.3.13 NAMED Specifier . . . . . . . . . . . . . . 11-65
11.7.3.14 NEXTREC Specifier . . . . . . . . . . . . . 11-65
11.7.3.15 NUMBER Specifier . . . . . . . . . . . . . . 11-65
viii
11.7.3.16 OPENED Specifier . . . . . . . . . . . . . . 11-66
11.7.3.17 ORGANIZATION Specifier . . . . . . . . . . . 11-66
11.7.3.18 RECL (RECORDSIZE) Specifier . . . . . . . . 11-66
11.7.3.19 RECORDTYPE Specifier . . . . . . . . . . . . 11-67
11.7.3.20 SEQUENTIAL Specifier . . . . . . . . . . . . 11-67
11.7.3.21 UNFORMATTED Specifier . . . . . . . . . . . 11-67
11.8 DEVICE CONTROL STATEMENTS . . . . . . . . . . . 11-71
11.8.1 FIND Statement . . . . . . . . . . . . . . . . 11-72
11.8.2 REWIND Statement . . . . . . . . . . . . . . . 11-73
11.8.3 UNLOAD Statement . . . . . . . . . . . . . . . 11-74
11.8.4 BACKSPACE Statement . . . . . . . . . . . . . 11-74
11.8.5 ENDFILE Statement . . . . . . . . . . . . . . 11-75
11.8.6 SKIPRECORD Statement . . . . . . . . . . . . . 11-76
11.8.7 SKIPFILE Statement . . . . . . . . . . . . . . 11-77
11.8.8 BACKFILE Statement . . . . . . . . . . . . . . 11-78
CHAPTER 12 FORMATTED DATA TRANSFERS
12.1 FORMAT-STATEMENT FORMATTING . . . . . . . . . . 12-3
12.1.1 Specifying a Format List in a FORMAT Statement 12-3
12.1.2 Specifying a Format Specification as a
Character Expression . . . . . . . . . . . . . 12-5
12.1.3 Specifying a Format Specification in a Numeric
Array . . . . . . . . . . . . . . . . . . . . 12-5
12.1.4 Specifying a FORMAT Statement Using an ASSIGNed
Variable . . . . . . . . . . . . . . . . . . . 12-6
12.1.5 The Ordering and Interpretation of Format List
Items . . . . . . . . . . . . . . . . . . . . 12-6
12.2 EDIT DESCRIPTORS . . . . . . . . . . . . . . . . 12-7
12.2.1 Repeatable Edit Descriptors . . . . . . . . . 12-8
12.2.2 Nonrepeatable Edit Descriptors . . . . . . . . 12-10
12.2.3 Carriage-Control Specifiers . . . . . . . . . 12-12
12.3 INTERACTION OF INPUT/OUTPUT LIST AND FORMAT LIST 12-14
12.3.1 General Description . . . . . . . . . . . . . 12-14
12.3.2 Formatted Input . . . . . . . . . . . . . . . 12-17
12.3.3 Formatted Output . . . . . . . . . . . . . . . 12-18
12.3.4 Embedded Format Specifications . . . . . . . . 12-18
12.4 FORMAT EDITING . . . . . . . . . . . . . . . . . 12-20
12.4.1 Apostrophe (') Editing . . . . . . . . . . . . 12-20
12.4.2 H Editing . . . . . . . . . . . . . . . . . . 12-21
12.4.3 Positional Editing . . . . . . . . . . . . . . 12-22
12.4.3.1 T, TL, and TR Editing . . . . . . . . . . . 12-23
12.4.3.2 X Editing . . . . . . . . . . . . . . . . . 12-26
12.4.4 $ (Dollar Sign) Editing . . . . . . . . . . . 12-27
12.4.5 / (Slash) Editing . . . . . . . . . . . . . . 12-28
12.4.6 : (Colon) Editing . . . . . . . . . . . . . . 12-29
12.4.7 S, SP,and SS Editing . . . . . . . . . . . . . 12-30
12.4.8 P Editing . . . . . . . . . . . . . . . . . . 12-31
12.4.9 BN and BZ Editing . . . . . . . . . . . . . . 12-34
12.4.10 Q Editing . . . . . . . . . . . . . . . . . . 12-35
12.4.11 Numeric Editing . . . . . . . . . . . . . . . 12-35
ix
12.4.11.1 I Editing . . . . . . . . . . . . . . . . . 12-37
12.4.11.2 F Editing . . . . . . . . . . . . . . . . . 12-38
12.4.11.3 E and D Editing . . . . . . . . . . . . . . 12-39
12.4.11.4 G Editing . . . . . . . . . . . . . . . . . 12-40
12.4.11.5 Complex Editing . . . . . . . . . . . . . . 12-43
12.4.11.6 O (Octal) Editing . . . . . . . . . . . . . 12-44
12.4.11.7 Z Editing . . . . . . . . . . . . . . . . . 12-44
12.4.12 L Editing . . . . . . . . . . . . . . . . . . 12-45
12.4.13 A Editing . . . . . . . . . . . . . . . . . . 12-46
12.4.14 R Editing . . . . . . . . . . . . . . . . . . 12-48
12.5 LIST-DIRECTED FORMATTING . . . . . . . . . . . . 12-49
12.6 NAMELIST-STATEMENT FORMATTING . . . . . . . . . 12-52
12.7 NAMELIST STATEMENT . . . . . . . . . . . . . . . 12-52
12.7.1 NAMELIST-Controlled Data Input Transfer . . . 12-54
12.7.2 NAMELIST-Controlled Data Output Transfers . . 12-55
CHAPTER 13 FUNCTIONS AND SUBROUTINES
13.1 INTRINSIC FUNCTIONS . . . . . . . . . . . . . . 13-2
13.1.1 Using an Intrinsic Function . . . . . . . . . 13-2
13.1.2 Character Intrinsic Functions . . . . . . . . 13-12
13.1.3 Character Comparison Functions . . . . . . . . 13-15
13.1.4 Bit Manipulation Functions . . . . . . . . . . 13-16
13.2 STATEMENT FUNCTIONS . . . . . . . . . . . . . . 13-17
13.2.1 Defining a Statement Function . . . . . . . . 13-17
13.2.2 Using a Statement Function . . . . . . . . . . 13-18
13.2.3 Statement Function Restrictions . . . . . . . 13-19
13.3 EXTERNAL FUNCTIONS . . . . . . . . . . . . . . . 13-20
13.3.1 FORTRAN-Supplied External Functions . . . . . 13-21
13.3.2 User-Defined External Functions . . . . . . . 13-22
13.3.3 Function Subprogram Restrictions . . . . . . . 13-23
13.3.4 Using a Function Subprogram . . . . . . . . . 13-24
13.4 SUBROUTINES . . . . . . . . . . . . . . . . . . 13-25
13.4.1 FORTRAN-Supplied Subroutines . . . . . . . . . 13-27
13.4.1.1 ALCCHR Subroutine . . . . . . . . . . . . . 13-28
13.4.1.2 CDABS Function . . . . . . . . . . . . . . . 13-28
13.4.1.3 CDCOS Subroutine . . . . . . . . . . . . . . 13-29
13.4.1.4 CDEXP Subroutine . . . . . . . . . . . . . . 13-29
13.4.1.5 CDLOG Subroutine . . . . . . . . . . . . . . 13-30
13.4.1.6 CDSIN Subroutine . . . . . . . . . . . . . . 13-31
13.4.1.7 CDSQRT Subroutine . . . . . . . . . . . . . 13-31
13.4.1.8 CHKDIV Subroutine . . . . . . . . . . . . . 13-32
13.4.1.9 CLRFMT Subroutine . . . . . . . . . . . . . 13-33
13.4.1.10 DATE Subroutine . . . . . . . . . . . . . . 13-33
13.4.1.11 DIVERT Subroutine . . . . . . . . . . . . . 13-34
13.4.1.12 DTOGA . . . . . . . . . . . . . . . . . . . 13-34
13.4.1.13 DUMP Subroutine . . . . . . . . . . . . . . 13-35
13.4.1.14 ERRSET Subroutine . . . . . . . . . . . . . 13-35
13.4.1.15 ERRSNS Subroutine . . . . . . . . . . . . . 13-37
13.4.1.16 EXIT Subroutine . . . . . . . . . . . . . . 13-38
13.4.1.17 FFUNIT Subroutine . . . . . . . . . . . . . 13-38
x
13.4.1.18 GTODA Subroutine . . . . . . . . . . . . . . 13-38
13.4.1.19 ILL Subroutine . . . . . . . . . . . . . . . 13-39
13.4.1.20 LEGAL Subroutine . . . . . . . . . . . . . . 13-39
13.4.1.21 MVBITS Subroutine . . . . . . . . . . . . . 13-40
13.4.1.22 OVERFL Subroutine . . . . . . . . . . . . . 13-40
13.4.1.23 PDUMP Subroutine . . . . . . . . . . . . . . 13-41
13.4.1.24 QUIETX Subroutine . . . . . . . . . . . . . 13-42
13.4.1.25 SAVFMT Subroutine . . . . . . . . . . . . . 13-42
13.4.1.26 SAVRAN Subroutine . . . . . . . . . . . . . 13-43
13.4.1.27 SETRAN Subroutine . . . . . . . . . . . . . 13-43
13.4.1.28 SORT Subroutine . . . . . . . . . . . . . . 13-44
13.4.1.29 SRTINI Subroutine . . . . . . . . . . . . . 13-44
13.4.1.30 TIME Subroutine . . . . . . . . . . . . . . 13-45
13.4.1.31 TOPMEM Subroutine . . . . . . . . . . . . . 13-46
13.4.1.32 TRACE Subroutine . . . . . . . . . . . . . . 13-46
13.4.2 User-Defined Subroutines . . . . . . . . . . . 13-48
13.4.2.1 SUBROUTINE Statement . . . . . . . . . . . . 13-49
13.4.2.2 CALL Statement . . . . . . . . . . . . . . . 13-50
13.4.2.3 Execution of a CALL Statement . . . . . . . 13-50
13.4.2.4 Actual Arguments for a Subroutine . . . . . 13-51
13.4.3 ENTRY Statement . . . . . . . . . . . . . . . 13-51
13.4.4 RETURN Statement . . . . . . . . . . . . . . . 13-53
13.4.5 Dummy and Actual Arguments . . . . . . . . . . 13-55
13.4.5.1 Length of Character Dummy and Actual
Arguments . . . . . . . . . . . . . . . . . 13-57
13.4.5.2 Character and Hollerith Constants as Actual
Arguments . . . . . . . . . . . . . . . . . 13-58
CHAPTER 14 BLOCK DATA SUBPROGRAMS
14.1 BLOCK DATA STATEMENT . . . . . . . . . . . . . . 14-1
CHAPTER 15 WRITING USER PROGRAMS
15.1 GENERAL PROGRAMMING CONSIDERATIONS . . . . . . . 15-1
15.1.1 Accuracy and Range of Double-Precision Numbers 15-1
15.1.2 Writing FORTRAN Programs for Use on Other
Computers . . . . . . . . . . . . . . . . . . 15-2
15.1.2.1 Remote Links . . . . . . . . . . . . . . . . 15-2
15.1.2.2 Reducing Network Overhead . . . . . . . . . 15-2
15.1.3 Using Floating-Point DO Loops . . . . . . . . 15-3
15.1.4 Computation of DO Loop Iterations . . . . . . 15-3
15.1.5 Subroutines - Programming Considerations . . . 15-3
15.1.6 Reordering of Computations . . . . . . . . . . 15-5
15.1.7 Dimensioning of Dummy Arrays . . . . . . . . . 15-6
15.2 FORTRAN GLOBAL OPTIMIZATION . . . . . . . . . . 15-7
15.2.1 Optimization Techniques . . . . . . . . . . . 15-7
15.2.1.1 Elimination of Redundant Computations . . . 15-8
15.2.1.2 Reduction of Operator Strength . . . . . . . 15-8
15.2.1.3 Removal of Constant Computation from Loops . 15-9
xi
15.2.1.4 Constant Folding and Propagation . . . . . . 15-10
15.2.1.5 Removal of Inaccessible Code . . . . . . . . 15-11
15.2.1.6 Global Register Allocation . . . . . . . . . 15-11
15.2.1.7 I/O Optimization . . . . . . . . . . . . . . 15-11
15.2.1.8 Uninitialized Variable Detection . . . . . . 15-11
15.2.1.9 Test Replacement . . . . . . . . . . . . . . 15-12
15.2.2 Programming Techniques for Effective
Optimization . . . . . . . . . . . . . . . . . 15-12
15.3 FUNCTION SIDE EFFECTS . . . . . . . . . . . . . 15-12
15.4 INTERACTING WITH NON-FORTRAN PROGRAMS AND FILES 15-13
15.4.1 Using The Sharable High-Segment FOROTS . . . . 15-13
15.4.2 Calling Sequences . . . . . . . . . . . . . . 15-13
15.4.3 Accumulator Usage . . . . . . . . . . . . . . 15-14
15.4.4 Argument Lists . . . . . . . . . . . . . . . . 15-15
15.4.5 Argument Types . . . . . . . . . . . . . . . . 15-17
15.4.6 Description of Arguments . . . . . . . . . . . 15-18
15.4.7 Interaction with COBOL . . . . . . . . . . . . 15-19
15.4.7.1 Calling FORTRAN Subprograms from COBOL
Programs . . . . . . . . . . . . . . . . . . 15-20
15.4.7.2 Calling COBOL Subroutines from FORTRAN
Programs . . . . . . . . . . . . . . . . . . 15-22
15.4.8 Interaction with BLISS-36 . . . . . . . . . . 15-22
15.4.8.1 Calling FORTRAN Subprograms From BLISS-36
Programs . . . . . . . . . . . . . . . . . . 15-22
15.4.8.2 Calling BLISS-36 Routines From FORTRAN . . . 15-23
15.4.9 LINK Overlay Facilities . . . . . . . . . . . 15-23
15.4.10 FOROTS and Overlay Memory Management . . . . . 15-25
15.4.11 Extended Addressing Memory Layout (TOPS-20
only) . . . . . . . . . . . . . . . . . . . . 15-27
15.5 USING INDEXED FILES (TOPS-20 ONLY) . . . . . . . 15-28
15.5.1 Creating an Indexed File . . . . . . . . . . . 15-29
15.5.2 Writing Indexed Files . . . . . . . . . . . . 15-31
15.5.2.1 Duplicate Values in Key Fields . . . . . . . 15-31
15.5.2.2 Preventing the Indexing of Alternate Key
Fields . . . . . . . . . . . . . . . . . . . 15-32
15.5.3 Reading Indexed Files . . . . . . . . . . . . 15-33
15.5.4 Updating Records . . . . . . . . . . . . . . . 15-34
15.5.5 Deleting Records . . . . . . . . . . . . . . . 15-35
15.5.6 Current Record and Next Record Pointers . . . 15-35
15.5.7 Exception Conditions . . . . . . . . . . . . . 15-36
CHAPTER 16 USING THE FORTRAN COMPILER
16.1 USING THE FORTRAN-10 COMPILER . . . . . . . . . 16-1
16.1.1 TOPS-10 COMPILE-Class Commands . . . . . . . . 16-1
16.1.2 RUNNING THE FORTRAN-10 COMPILER . . . . . . . 16-2
16.1.3 TOPS-10 Compiler Command Switches . . . . . . 16-3
16.2 USING THE FORTRAN-20 COMPILER . . . . . . . . . 16-5
16.2.1 TOPS-20 COMPILE-Class Commands . . . . . . . . 16-5
16.2.2 RUNNING THE FORTRAN-20 COMPILER . . . . . . . 16-6
16.2.3 TOPS-20 Compiler Commands Switches . . . . . 16-9
xii
16.3 THE /DEBUG SWITCH . . . . . . . . . . . . . . . 16-11
16.4 THE /NOWARN SWITCH . . . . . . . . . . . . . . . 16-15
16.5 THE /EXTEND SWITCH (TOPS-20 ONLY) . . . . . . . 16-16
16.5.1 /EXTEND and Applications with Large Arrays . . 16-17
16.5.2 /EXTEND and Applications with Large Executable
Code . . . . . . . . . . . . . . . . . . . . . 16-18
16.5.2.1 /EXTEND PSECT Placement . . . . . . . . . . 16-19
16.5.2.2 Building Large-Code Applications . . . . . . 16-19
16.5.3 Arguments to /EXTEND . . . . . . . . . . . . . 16-20
16.5.4 Linking With TWOSEG REL Files . . . . . . . . 16-22
16.6 THE /FLAG (/FLAG-NON-STANDARD) SWITCH . . . . . 16-22
16.7 READING A FORTRAN COMPILER LISTING . . . . . . . 16-23
16.7.1 Compiler-Generated Variables . . . . . . . . . 16-25
16.8 ERROR REPORTING . . . . . . . . . . . . . . . . 16-34
16.8.1 Fatal Errors and Warning Messages . . . . . . 16-34
16.8.2 Message Summary . . . . . . . . . . . . . . . 16-35
16.9 CREATING A SHARABLE HIGH SEGMENT FOR A FORTRAN
PROGRAM . . . . . . . . . . . . . . . . . . . . 16-36
CHAPTER 17 USING THE FORTRAN INTERACTIVE DEBUGGER (FORDDT)
17.1 INPUT FORMAT . . . . . . . . . . . . . . . . . . 17-2
17.1.1 Variables and Arrays . . . . . . . . . . . . . 17-3
17.1.2 Constant Conventions . . . . . . . . . . . . . 17-3
17.1.3 Statement Labels and Source Line Numbers . . . 17-4
17.2 FORDDT AND THE FORTRAN /DEBUG SWITCH . . . . . . 17-4
17.3 LOADING AND STARTING FORDDT . . . . . . . . . . 17-6
17.4 SCOPE OF NAME AND LABEL REFERENCES . . . . . . . 17-7
17.5 FORDDT COMMANDS . . . . . . . . . . . . . . . . 17-8
17.6 ENVIRONMENT CONTROL . . . . . . . . . . . . . . 17-19
17.7 FORTRAN /OPTIMIZE SWITCH . . . . . . . . . . . . 17-20
17.8 CALLING FORDDT . . . . . . . . . . . . . . . . . 17-20
17.9 FORDDT AND FORTRAN-20 EXTENDED ADDRESSING . . . 17-20
CHAPTER 18 USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
18.1 FEATURES OF FOROTS . . . . . . . . . . . . . . . 18-2
18.2 ERROR PROCESSING . . . . . . . . . . . . . . . . 18-3
18.3 INPUT/OUTPUT FACILITIES . . . . . . . . . . . . 18-3
18.3.1 Input/Output Channels Used By FOROTS (TOPS-10
Only) . . . . . . . . . . . . . . . . . . . . 18-3
18.3.2 File Access . . . . . . . . . . . . . . . . . 18-3
18.3.3 Closing Files After Non-standard Termination . 18-4
18.3.3.1 Sequential Access . . . . . . . . . . . . . 18-4
18.3.3.2 Direct (Random) Access Mode . . . . . . . . 18-5
18.4 ACCEPTABLE TYPES OF DATA FILES AND THEIR FORMATS 18-5
18.4.1 ASCII Data Files . . . . . . . . . . . . . . . 18-5
18.4.2 FORTRAN Binary Data Files . . . . . . . . . . 18-5
18.4.2.1 Format of Binary Files . . . . . . . . . . . 18-5
18.4.3 RMS Data Files (TOPS-20 only) . . . . . . . . 18-16
xiii
18.5 USING FOROTS . . . . . . . . . . . . . . . . . . 18-16
18.5.1 FOROTS Entry Points . . . . . . . . . . . . . 18-16
18.5.2 Calling Sequences . . . . . . . . . . . . . . 18-19
18.5.3 MACRO Calls for FOROTS Functions . . . . . . . 18-19
18.5.3.1 Sequential-Access Calling Sequences . . . 18-21
18.5.3.2 Internal File Calling Sequences . . . . . . 18-22
18.5.3.3 NAMELIST I/O, Sequential-Access Calling
Sequences . . . . . . . . . . . . . . . . . 18-23
18.5.3.4 Array Offsets and Factoring . . . . . . . . 18-24
18.5.3.5 I/O Statements, Direct-Access Calling
Sequences . . . . . . . . . . . . . . . . . 18-26
18.5.3.6 Default Devices Statements, Calling
Sequences . . . . . . . . . . . . . . . . . 18-27
18.5.3.7 Statements to Position Files . . . . . . . . 18-28
18.5.3.8 List-Directed Input/Output Statements . . . 18-28
18.5.3.9 Input/Output Data Lists . . . . . . . . . . 18-29
18.5.3.10 OPEN and CLOSE Statements, Calling Sequences 18-32
18.5.3.11 Memory Allocation Routines . . . . . . . . . 18-34
18.5.3.12 Channel Allocation and Deallocation Routines 18-35
18.6 FUNCTIONS TO FACILITATE OVERLAYS . . . . . . . . 18-37
18.7 LOGICAL/PHYSICAL DEVICE ASSIGNMENTS . . . . . . 18-43
18.8 FOROTS AND INQUIRE BY FILE STATEMENT . . . . . . 18-43
18.9 USEROPEN PROCEDURES . . . . . . . . . . . . . . 18-45
18.9.1 Example of a USEROPEN . . . . . . . . . . . . 18-46
18.9.2 RMS/FOROTS Data and Control Structures . . . . 18-47
CHAPTER 19 USING THE FORTRAN REAL-TIME SOFTWARE (TOPS-10 ONLY)
19.1 INTRODUCTION . . . . . . . . . . . . . . . . . . 19-1
19.2 USING FORRTF . . . . . . . . . . . . . . . . . . 19-2
19.2.1 Memory . . . . . . . . . . . . . . . . . . . . 19-2
19.2.2 Modes . . . . . . . . . . . . . . . . . . . . 19-2
19.2.3 Priority-Interrupt Levels . . . . . . . . . . 19-3
19.2.4 Masks . . . . . . . . . . . . . . . . . . . . 19-3
19.3 SUBROUTINES . . . . . . . . . . . . . . . . . . 19-3
19.3.1 LOCK . . . . . . . . . . . . . . . . . . . . . 19-3
19.3.2 RTINIT . . . . . . . . . . . . . . . . . . . . 19-3
19.3.3 CONECT . . . . . . . . . . . . . . . . . . . . 19-4
19.3.4 RTSTRT . . . . . . . . . . . . . . . . . . . . 19-5
19.3.5 BLKRW . . . . . . . . . . . . . . . . . . . . 19-5
19.3.6 RTREAD . . . . . . . . . . . . . . . . . . . . 19-6
19.3.7 RTWRIT . . . . . . . . . . . . . . . . . . . . 19-6
19.3.8 STATO . . . . . . . . . . . . . . . . . . . . 19-6
19.3.9 STATI . . . . . . . . . . . . . . . . . . . . 19-7
19.3.10 RTSLP . . . . . . . . . . . . . . . . . . . . 19-7
19.3.11 RTWAKE . . . . . . . . . . . . . . . . . . . . 19-7
19.3.12 DISMIS . . . . . . . . . . . . . . . . . . . . 19-8
19.3.13 DISCON . . . . . . . . . . . . . . . . . . . . 19-8
19.3.14 UNLOCK . . . . . . . . . . . . . . . . . . . . 19-8
19.3.15 Error Messages . . . . . . . . . . . . . . . . 19-8
xiv
APPENDIX A SUMMARY OF FORTRAN STATEMENTS
APPENDIX B ASCII-1968 CHARACTER CODE SET
APPENDIX C COMPILER MESSAGES
APPENDIX D FOROTS ERROR MESSAGES
D.1 ALPHABETICAL DESCRIPTION OF FOROTS MESSAGES . . D-12
APPENDIX E INTERACTIVE DEBUGGER (FORDDT) ERROR MESSAGES
APPENDIX F FORTRAN-SUPPLIED PLOTTER SUBROUTINES
F.1 PLOTS SUBROUTINE . . . . . . . . . . . . . . . . . F-2
F.2 AXIS SUBROUTINE . . . . . . . . . . . . . . . . . F-3
F.3 CAXIS SUBROUTINE . . . . . . . . . . . . . . . . . F-4
F.4 LINE SUBROUTINE . . . . . . . . . . . . . . . . . F-5
F.5 MKTBL SUBROUTINE . . . . . . . . . . . . . . . . . F-5
F.5.1 Character Tables . . . . . . . . . . . . . . . . F-6
F.5.1.1 Creating a Character Table . . . . . . . . . . F-6
F.5.1.2 Creating a Stroke Table . . . . . . . . . . . F-7
F.5.1.3 Sample Character Stroke Table . . . . . . . . F-8
F.5.1.4 FORTRAN- and User-Defined Character Sets . . F-10
F.6 NUMBER SUBROUTINE . . . . . . . . . . . . . . . F-10
F.7 PLOT SUBROUTINE . . . . . . . . . . . . . . . . F-11
F.8 SCALE SUBROUTINE . . . . . . . . . . . . . . . . F-12
F.9 SETABL SUBROUTINE . . . . . . . . . . . . . . . F-13
F.10 SYMBOL SUBROUTINE . . . . . . . . . . . . . . . F-14
F.11 WHERE SUBROUTINE . . . . . . . . . . . . . . . . F-14
FIGURES
2-1 Fields Within a FORTRAN Line . . . . . . . . . . . 2-3
4-1 A 3 x 3 x 2 Array . . . . . . . . . . . . . . . . 4-5
6-1 Ordering of FORTRAN Statements . . . . . . . . . . 6-4
7-1 Shared Storage using EQUIVALENCE Statement . . . 7-14
7-2 Equivalence of Substrings . . . . . . . . . . . 7-16
7-3 Equivalence of Character Arrays . . . . . . . . 7-18
7-4 Valid Equivalencing . . . . . . . . . . . . . . 7-20
7-5 Invalid Equivalencing . . . . . . . . . . . . . 7-21
9-1 Examples of Block IF Constructs . . . . . . . . . 9-8
10-1 Components of Data Transfer Statements . . . . . 10-10
11-1 TOPS-10 File Protection Number . . . . . . . . . 11-34
11-2 TOPS-20 Protection Number . . . . . . . . . . . 11-37
15-1 Run-time Memory Layout for Section Zero . . . . 15-26
xv
F-1 Plotter Character Table Entry . . . . . . . . . . F-7
F-2 Character Stroke Table Entry . . . . . . . . . . . F-7
F-3 Sample Character Stroke Table . . . . . . . . . . F-9
TABLES
2-1 FORTRAN Character Set . . . . . . . . . . . . . . 2-2
3-1 Comparison of Real, D-floating, and G-floating
Numbers . . . . . . . . . . . . . . . . . . . . . 3-4
4-1 Use of Symbolic Names . . . . . . . . . . . . . . 4-1
5-1 Arithmetic Operations and Operators . . . . . . . 5-2
5-2 Type of the Result Obtained from Mixed-Mode
Operations . . . . . . . . . . . . . . . . . . . . 5-4
5-3 Permitted Base/Exponent Type Combinations . . . . 5-5
5-4 Logical Operators . . . . . . . . . . . . . . . . 5-9
5-5 Logical Operations Truth Table . . . . . . . . . . 5-9
5-6 Relational Operators and Operations . . . . . . 5-12
5-7 Hierarchy of FORTRAN Operators . . . . . . . . . 5-16
8-1 Rules for Conversion in Mixed-Mode Assignments . . 8-3
10-1 FORTRAN I/O Statement Categories . . . . . . . . 10-2
10-2 Summary of Data Transfer Statement Forms . . . . 10-3
10-3 FORTRAN Logical Device Assignments . . . . . . . 10-15
10-4 Summary of READ Statement Forms . . . . . . . . 10-33
10-5 Summary of WRITE Statement Forms . . . . . . . . 10-42
10-6 Summary of REREAD Statement Forms . . . . . . . 10-52
10-7 Summary of ACCEPT Statement Forms . . . . . . . 10-55
10-8 Summary of TYPE Statement Forms . . . . . . . . 10-58
10-9 Summary of PRINT Statement Forms . . . . . . . . 10-61
10-10 Summary of PUNCH Statement Forms . . . . . . . . 10-63
10-11 Summary of Internal READ/WRITE and ENCODE/DECODE
Statement Forms . . . . . . . . . . . . . . . . 10-66
10-12 Summary of DELETE Statement Forms . . . . . . . 10-72
10-13 Summary of REWRITE Statement Forms . . . . . . . 10-74
10-14 Summary of UNLOCK Statement Forms . . . . . . . 10-76
11-1 Summary of OPEN Statement Specifiers and
Arguments . . . . . . . . . . . . . . . . . . . 11-5
11-2 DEVICE and MODE Cross-Table . . . . . . . . . . 11-30
11-3 TOPS-10 Protection Code Values . . . . . . . . . 11-35
11-4 TOPS-20 Protection Code Values . . . . . . . . . 11-37
11-5 Summary of CLOSE Statement Specifiers and
Arguments . . . . . . . . . . . . . . . . . . . 11-49
11-6 Summary of Device-Control Statements . . . . . . 11-70
12-1 Repeatable FORTRAN Edit Descriptors . . . . . . 12-10
12-2 Nonrepeatable FORTRAN Edit Descriptors . . . . . 12-12
12-3 Carriage-Control Specifiers . . . . . . . . . . 12-14
12-4 Record, Format List, and I/O List Interaction . 12-16
12-5 Default Field Widths for Numeric Edit
Descriptors . . . . . . . . . . . . . . . . . . 12-36
12-6 Effect of Data Magnitude on G-Format Output
Conversion . . . . . . . . . . . . . . . . . . . 12-41
13-1 FORTRAN Instrinsic Functions . . . . . . . . . . 13-5
xvi
13-2 FORTRAN-Supplied Subroutines . . . . . . . . . . 13-26
15-1 Argument Types and Types Codes . . . . . . . . . 15-17
15-2 Memory Allocations for /EXTEND and /NOEXTEND . . 15-27
16-1 FORTRAN-10 Compiler Switches . . . . . . . . . . 16-3
16-2 FORTRAN-20 Compiler Switches . . . . . . . . . . 16-9
16-3 Arguments to /DEBUG Switch . . . . . . . . . . . 16-12
16-4 Legal Dummy and Actual Argument Associations . . 16-15
16-5 Arguments to /NOWARN Switch . . . . . . . . . . 16-15
16-6 /EXTEND Default Memory Layout . . . . . . . . . 16-16
16-7 Arguments to /EXTEND Switch . . . . . . . . . . 16-20
16-8 Arguments to /FLAG Switch . . . . . . . . . . . 16-23
17-1 FORDDT Commands . . . . . . . . . . . . . . . . 17-1
18-1 FOROTS Entry Points . . . . . . . . . . . . . . 18-17
18-2 Function Numbers and Function Codes . . . . . . 18-38
19-1 Error Messages - Code Format and Full Message
Format . . . . . . . . . . . . . . . . . . . . . 19-10
D-1 FOROTS Error Codes . . . . . . . . . . . . . . . . D-3
xvii
PREFACE
The FORTRAN-10/20 Language Manual reflects the software as of Version
| 11 of the FORTRAN-10/20 compiler, the FORTRAN-10/20 Object Time System
(FOROTS), and the FORTRAN-10/20 debugging program (FORDDT).
This manual describes the FORTRAN language as implemented for the
TOPS-10 operating system (FORTRAN-10) and the TOPS-20 operating system
(FORTRAN-20). Any differences between FORTRAN-10 and FORTRAN-20 are
noted in this manual.
Since this is a reference manual, we assume that you have used FORTRAN
before. If you haven't, you should read one of the many introductory
FORTRAN texts.
CONVENTIONS
The following conventions are used throughout the manual:
Braces { } indicate that a choice must be made from one
of the enclosed lines.
Brackets [ ] indicate an optional feature.
Ellipsis ... or . indicate the omission of information from a
. programming example or that items in a
. command line can be optionally repeated.
Lowercase letters indicate variable information you supply in a
command string.
UPPERCASE LETTERS indicate fixed (or literal) information that
you must enter as shown in a command string.
b indicates a blank.
The standard for FORTRAN is the American National Standards Institute
xviii
(ANSI) FORTRAN, X3.9-1978 (also known as FORTRAN-77). FORTRAN-10/20
extensions and additions to ANSI FORTRAN are in blue print in this
manual.
xix
MANUALS REFERENCED
The following manuals are referenced from TOPS-10 publications:
o TOPS-10 Operating System Commands Manual
o SOS Reference Manual
o TOPS-10 Monitor Calls Manual
o TOPS-10 Hardware Reference Manual
o TOPS-10 LINK Reference Manual
o TOPS-10 SORT/MERGE User's Guide
o TOPS-10 FORTRAN Installation Guide
The following manuals are referenced from TOPS-20 publications:
o TOPS-20 Commands Reference Manual
o TOPS-20 EDIT Reference Manual
o TOPS-20 User's Guide
o TOPS-20 Monitor Calls Manual
o TOPS-20 Link Reference Manual
o TOPS-20 SORT/MERGE User's Guide
o TOPS-20 FORTRAN Installation Guide
|
| o TOPS-20 RMS User's Guide
|
| o RMS-20 Programmer's Reference Manual
The following TOPS-10/TOPS-20 manual are referenced:
|
| o FORTRAN-10/20 and VAX FORTRAN Compatibility Manual
o TOPS-10/20 FORTRAN Pocket Guide
o TOPS-10/TOPS-20 COBOL-74 Language Manual
o TOPS-10/20 BLISS Language Guide
o TOPS-10/20 Common Math Library Manual
xx
CHAPTER 1
INTRODUCTION
1.1 OVERVIEW
The FORTRAN language, as implemented on the TOPS-10 and TOPS-20
operating systems, is compatible with and encompasses the standard
described in "American National Standard FORTRAN, X3.9-1978" (referred
to as the FORTRAN-77 standard) at the full-language level.
FORTRAN-10/20 provides many extensions and additions to the FORTRAN-77
standard that greatly enhance the usefulness of FORTRAN and increase
its compatibility with FORTRAN languages implemented by other computer
manufacturers. The extensions and additions to the standard
FORTRAN-77 are printed in this manual in blue print.
A FORTRAN source program consists of a set of statements constructed
using the language elements and the syntax described in this manual.
A given FORTRAN statement performs any one of the following functions:
1. It causes operations such as multiplication, division, and
branching to be carried out.
2. It specifies the type and format of the data being processed.
3. It specifies the characteristics of the source program.
FORTRAN statements are composed of keywords (words that are recognized
by the compiler) used with elements of the language set: constants,
variables, and expressions. There are two basic types of FORTRAN
statements: executable and nonexecutable.
Executable statements specify the actions of the program;
nonexecutable statements describe the characteristics and arrangement
of data, editing information, statement functions, and the kind of
subprograms that may be included in the program. The compilation of
executable statements results in the creation of executable code in
the object program. Nonexecutable statements provide information only
to the compiler; they do not create executable code.
1-1
INTRODUCTION
1.2 MANUAL ORGANIZATION
This manual is divided into three parts: Language Elements,
Statements, and Language Usage. Sections 1.2.1 through 1.2.3 contain
general descriptions for each of these three parts. Section 1.2.4
contains a general description of the appendixes.
1.2.1 FORTRAN Language Elements (Part I)
Part I of this manual describes the fundamental elements of FORTRAN
programs, including (by chapter):
Chapter 2, CHARACTERS AND LINES, describes FORTRAN source program
characters and lines. The FORTRAN compiler interprets your
source program and translates it into machine code (executable
code).
Chapter 3, CONSTANTS, describes FORTRAN data types and constants.
FORTRAN enables you to manipulate information (data) in a variety
of ways. This chapter describes the techniques for defining
FORTRAN constants of various data types.
Chapter 4, SYMBOLIC NAMES, VARIABLES, AND ARRAYS, describes
symbolic names, variables, and arrays in FORTRAN. The symbolic
name is used in a variety of ways in a source program; this
chapter describes the conventions for using symbolic names to
define both variables and arrays.
Chapter 5, EXPRESSIONS, introduces and describes FORTRAN
operators. Expressions in FORTRAN are formed using variables,
constants, and operators.
1.2.2 FORTRAN Statements (Part II)
Part II of this manual describes all the statements in the FORTRAN
language. The following list describes (by chapter) the information
presented in Part II:
Chapter 6, EXECUTABLE AND NONEXECUTABLE STATEMENTS, defines the
term "FORTRAN Statement", and describes the "Compilation Control
Statements".
Chapter 7, SPECIFICATION AND DATA STATEMENTS, describes all the
statements within the category "Specification and Data
Statements". The specification statements enable you to
explicitly define the data types of variables used within your
program; the DATA statement enables you to create initially
defined constants within your program.
1-2
INTRODUCTION
Chapter 8, ASSIGNMENT STATEMENTS, describes all the statements
within the category "Assignment Statements". FORTRAN assignment
statements enable you to assign values to variables, and to
assign statement labels to symbolic names.
Chapter 9, CONTROL STATEMENTS, describes all the statements
within the category "Control Statements". The default execution
sequence of lines in a FORTRAN program is each line from
left-to-right, and all lines from top-to-bottom. You use the
FORTRAN control statements to alter the default execution
sequence, to stop or pause during program execution, or to mark
the end of an executable program.
Chapter 10, DATA TRANSFER STATEMENTS, describes the data transfer
category of "FORTRAN Input/Output (I/O) Statements". As the term
implies, a data transfer statement moves data from one place to
another.
Chapter 11, FILE-CONTROL AND DEVICE-CONTROL STATEMENTS, describes
file-control and device-control categories of "FORTRAN I/O
Statements". The file-control statements enable you to associate
a unit number with a file. Device-control statements enable you
to position a storage medium (for example, magnetic tape) on a
connected unit.
Chapter 12, FORMATTED DATA TRANSFERS, describes three types of
data formatting. During certain types of data transfer
operations, you must specify the format of the data being
transferred. FORTRAN provides three techniques for specifying
the format of data: FORMAT-Statement, List-Directed, and
NAMELIST-Statement formatting.
Chapter 13, FUNCTIONS AND SUBROUTINES, describes FORTRAN
functions and subprograms. Functions and subprograms provide a
technique for producing clear and concise FORTRAN programs.
FORTRAN-10/20 provides both predefined functions and subprograms,
and the statements for defining your own functions and
subprograms.
Chapter 14, BLOCK DATA SUBPROGRAMS, describes the block-data
subprogram. This type of subprogram enables you to define
initial values for variables in COMMON.
1.2.3 FORTRAN Language Usage (Part III)
Parts I and II of the manual contain complete descriptions of FORTRAN
elements and statements. Part III of the manual contains explanations
of how you use FORTRAN-10/20. The following usage topics are covered
in Part III:
1-3
INTRODUCTION
Chapter 15, WRITING USER PROGRAMS, presents some general
considerations that you should follow when you are creating
FORTRAN source programs. In addition, this chapter contains a
description of the FORTRAN optimizer.
Chapter 16, USING THE FORTRAN COMPILER, describes how to use the
FORTRAN compiler and contains descriptions on how to compile,
load, and execute a FORTRAN program. In addition, this chapter
contains descriptions of how to read a compiler-generated program
listing, and how to create a reentrant FORTRAN program. This
Chapter also describes how to use FORTRAN-20 extended addressing.
Chapter 17, USING THE FORTRAN INTERACTIVE DEBUGGER (FORDDT),
describes how to use the FORTRAN interactive debugging program
(FORDDT) to test and debug a running program. This chapter also
contains a brief explanation of how to debug a running FORTRAN
program using DDT, the system debugger.
Chapter 18, USING THE FORTRAN OBJECT-TIME SYSTEM (FOROTS),
describes the FORTRAN Object-Time System (FOROTS). This chapter
also contains descriptions of how you can use the FOROTS
software.
Chapter 19, USING THE FORTRAN REAL-TIME SOFTWARE (TOPS-10 ONLY),
describes how to use the FORTRAN real-time software. This
chapter is for TOPS-10 installations only.
1.2.4 APPENDIXES
The appendixes describe various useful information. The following
topics are covered in the appendixes:
Appendix A, SUMMARY OF FORTRAN STATEMENTS, summarizes the forms
of all FORTRAN statements and provides a section reference where
each statement is described in detail.
Appendix B, ASCII-1968 CHARACTER CODE SET, lists the character
code set defined in the X3.4-1968 version of the American
National Standard Code for Information Interchange (ASCII).
Appendix C, COMPILER MESSAGES, describes the FORTRAN compiler
messages.
Appendix D, FOROTS ERROR MESSAGES, describes the FOROTS error
messages.
Appendix E, FORDDT ERROR MESSAGES, describes the FORDDT error
messages.
Appendix F, FORTRAN-SUPPLIED PLOTTER SUBROUTINES, describes the
1-4
INTRODUCTION
FORTRAN-supplied plotter subroutines.
1-5
2-1
CHAPTER 2
CHARACTERS AND LINES
The basic elements of the FORTRAN source program are its characters
and lines. Characters are used to form statements, expressions, and
comments in FORTRAN source programs. Lines, and fields within lines,
are used to define the context in which characters are interpreted by
the FORTRAN compiler.
This chapter describes the relationships among source program
characters, lines, and fields within source program lines.
2.1 CHARACTER SET
Table 2-1 lists the digits, letters, and symbols recognized by
FORTRAN. The remainder of the ASCII-1968 character set is acceptable
within character or Hollerith constants or comment text, but these
characters cause fatal errors in other contexts.
NOTE
The complete ASCII character set is defined in the
X3.4-1968 version of the "American National Standard
Code for Information Interchange". A summary of the
standard ASCII set is also contained in Appendix B of
this manual.
NOTE
Lowercase alphabetic characters are treated as
upper-case outside the context of Hollerith or
character constants.
2-1
CHARACTERS AND LINES
Table 2-1: FORTRAN Character Set
Letters
Uppercase: A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
Lowercase: a b c d e f g h i j k l m n o p q r s t u v w x y z
Digits
0 1 2 3 4 5 6 7 8 9
Symbols
! Exclamation point , Comma
" Quotation Mark - Hyphen (Minus)
# Number Sign . Period (Decimal Point)
$ Dollar Sign / Slant (Slash)
& Ampersand : Colon
' Apostrophe ; Semicolon
( Left Parenthesis < Less Than
) Right Parenthesis = Equal To
* Asterisk > Greater Than
+ Plus ^ Circumflex
| _ Underscore
Line Termination Characters
Line Feed (LF), Form Feed (FF), Vertical Tab (VT)
Line Formatting Characters
Carriage Return (RET), Horizontal Tab (TAB), Blank
Note that horizontal tabs normally advance the character position
pointer to the next position that is an even multiple of 8. An
exception to this is the initial tab, which is defined as a tab that
either includes or starts in character position 6. (Refer to Section
2.3.1 for a description of initial and continuation line types.) Tabs
within character specifications count as one character, even though
2-2
CHARACTERS AND LINES
they may advance the character position as many as eight places.
2.2 STATEMENT DEFINITION AND FORMAT
Source program statements are divided into physical lines. A line is
defined as a string of adjacent character positions, terminated by the
first occurrence of a line termination character, regardless of
context. As shown in Figure 2-1, each source program line is divided
into four fields.
Figure 2-1: Fields Within a FORTRAN Line
2.2.1 Statement Label Field and Statement Numbers
You can place a number ranging from 1 to 99999 in the statement label
field of an initial line to identify the statement. Any source
program statement that is referenced by another statement must have a
statement number. Leading zeros and all blanks in the label field are
ignored; for example, the numbers 00105 and 105 are both accepted as
statement number 105.
You can assign the statement numbers in a source program in any order;
however, each statement number must be unique with respect to all
other statements in the program or subprogram.
A main program and a subprogram can contain identical statement
numbers. In this case, references to these numbers are understood to
mean the numbers in the same program unit in which the reference is
made. An example follows:
Assume that main module MAINMD and subprogram SUB1 both
contain statement number 105. A GO TO 105 statement, for
instance, in MAINMD will refer to statement 105 in MAINMD,
not to 105 in SUB1. A GO TO 105 in SUB1 will transfer
control to 105 in SUB1.
An initial tab may be used to skip all or part of the label field. If
an initial tab is encountered during compilation, FORTRAN-10/20
examines the character immediately following the tab to determine the
type of line being entered. If this character is one of the digits 1
2-3
CHARACTERS AND LINES
through 9, FORTRAN-10/20 considers the line as a continuation line and
uses the second character after the tab as the first character of the
statement field.
If the character following the tab is not one of the digits 1 through
9, FORTRAN-10/20 considers the line to be an initial line and the
character following the tab is considered to be the first character of
the statement field. The character following the initial tab is
considered to be in character position 6 for a continuation line, and
in character position 7 for an initial line.
2.2.2 Line Continuation Field
Any character of the FORTRAN character set (except a blank, a zero, or
an exclamation point) placed in the line continuation field (position
6) identifies the line as a continuation line (see Section 2.3.1).
Whenever you use an initial tab to skip all or part of the label field
of a continuation line, the next character you enter must be one of
the digits 1 through 9 to identify the line as a continuation line.
2.2.3 Statement Field
Any FORTRAN statement can appear in the statement field. Blanks
(spaces) and tabs do not affect compilation of the statement. Blanks
and tabs may be used freely in this field for appearance purposes,
with the exception of textual data given within either a character or
Hollerith specification, where blanks and tabs are significant
characters.
2.2.4 Remark Field
In lines consisting of 73 or more character positions, only the first
72 character positions are interpreted by FORTRAN. Note that tabs
generally occupy more than one character position, usually advancing
the cursor to the next character position that is an even multiple of
8. The exception is the tab in a label field, which advances the
cursor either to column 6 or 7, depending on the character following
the tab (see Section 2.2.1).
All other characters after character position 72 are treated as
remarks and do not affect compilation.
Note that remarks may also be added to a line in character positions 1
through 72, provided the text of the remark is preceded by the symbol
"!" (see Section 2.3.3).
2-4
CHARACTERS AND LINES
2.3 LINE TYPES
A line in a FORTRAN source program may be:
1. An initial line
2. A continuation line
3. A multi-statement line
4. A comment line
5. A debug line
6. A blank line
These lines are described in Sections 2.3.1 through 2.3.5.
2.3.1 Initial and Continuation Lines
| A FORTRAN statement may occupy the statement fields of up to 100
consecutive lines. The first line in a multi-line statement is
referred to as the initial line; the succeeding lines are referred to
as continuation lines. Initial lines may be assigned a statement
number and must have either a blank or a zero in character position 6.
An initial tab may be used to skip all or part of the label field. If
you use an initial tab for this purpose, you must immediately follow
it with a nonnumeric character; that is, the first character of the
statement field must be nonnumeric.
You cannot assign a statement label to a continuation line. Instead,
you identify a continuation line by placing a character from the
FORTRAN character set (except blank, zero, or exclamation point) in
character position 6 of that line. This position is the line
continuation field. The label field of a continuation line must be
blank.
Note that blank lines, comments, and debug lines that are treated like
comments (that is, debug lines that are not compiled with the rest of
the program) are legal continuation lines and do not terminate a
continuation sequence (see Section 2.3.4).
The following is an example of a 3-line FORTRAN FORMAT statement with
two continuation lines:
105 FORMAT (1X,'This example shows how continuation lines ',
2 'are used to accommodate FORTRAN statements that do not ',
3 'entirely fit on a single line.')
2-5
CHARACTERS AND LINES
In this example the characters 2 and 3 in position 6 identify those
lines as continuation lines.
2.3.2 Multi-Statement Lines
You may write more than one FORTRAN statement in the statement field
of one line. The rules for structuring a multi-statement line are:
1. Successive statements must be separated by a semicolon (;).
2. Only the first statement in the series can have a statement
number.
3. The last statement in a line is continued to the next line if
that next line is made a continuation line.
An example of a multi-statement line is:
450 DIST=RATE * TIME; TIME=TIME+0.05; CALL PRIME(TIME,DIST)
NOTE
If a statement sequence in a
multi-statement line consists of a
logical IF (see Section 9.2.2) followed
by any other executable statement, then
the statement following the IF will be
executed in all cases, even if the IF
expression evaluates as false.
2.3.3 Comment Lines and Remarks
Lines that contain descriptive text only are called comment lines.
Comment lines commonly identify and introduce a source program,
describe the purpose of a particular set of statements, and introduce
subprograms.
To structure a comment line:
1. You must place one of the characters C (or c), *, $, /, or !
in character position 1 of the line to identify it as a
comment line.
2. You place the text of the comment in the remainder of the
line.
2-6
CHARACTERS AND LINES
3. You may place comment lines anywhere in the source program,
including preceding a continuation line.
4. You may write a large comment as a sequence of any number of
lines; however, each line must carry the identifying
character (C (or c), *, $, /, or !) in its first character
position.
The following is an example of a comment that occupies more than one
line:
C SUBROUTINE - A12
C This subroutine formats
c and stores the results of
c the HEAT-TEST program
Comment lines are printed on all listings, but are otherwise ignored
by the compiler.
You may add a remark to any statement field, in character positions 7
through 72, provided the symbol ! precedes the text. For example, in
the line
IF(N.EQ.0)STOP ! Stop if card is blank
the text "Stop if card is blank" is identified as a remark by the
preceding ! symbol. The compiler ignores all characters from the
exclamation point to the end of the line. The characters following
the exclamation point, however, appear in the source program listing.
To be treated as a remark symbol, the exclamation point must not
appear in a Hollerith or character constant.
Note that characters appearing in character positions 73 and beyond
are automatically treated as remarks, so that you need not use the
symbol ! (see Section 2.2.4).
2.3.4 Debug Lines
As an aid in program debugging, a D (or d) in character position 1 of
any line causes the line to be interpreted as a comment line; that is,
not compiled with the rest of the program unless the /INCLUDE switch
is present in the compiler command string. (See Chapter 16 for a
description of the compiler switches.)
When the /INCLUDE switch is present in the compiler command string,
the D (or d) in character position 1 is treated as a blank so that the
remainder of the line is compiled as an ordinary (noncomment) line. A
debug line can have a label following the D (or d). Note that if the
debug statement is an initial line, all of its continuation lines must
contain a D (or d) in character position 1.
2-7
CHARACTERS AND LINES
2.3.5 Blank Lines
You may insert lines consisting of only blanks, tabs, or no characters
anywhere in a FORTRAN source program. Blank lines that contain
remarks only, are considered as blank lines. Blank lines are used for
formatting purposes only; they cause blank lines to appear in their
corresponding positions in source program listings; otherwise, they
are ignored by the compiler.
2.4 LINE-SEQUENCED SOURCE FILES
FORTRAN-10/20 accepts line-sequenced files as produced by
line-oriented text editors (for example, SOS on TOPS-10 or EDIT on
TOPS-20). These sequence numbers are used in place of the listing
line numbers normally generated by FORTRAN. The listing line numbers
are not the same as FORTRAN statement numbers.
2-8
CHAPTER 3
CONSTANTS
3.1 INTRODUCTION
Constants are quantities that do not change value during the execution
of the object program. The data types you can use for constants in
FORTRAN-10/20 source programs are:
1. Integer
2. Real
3. Double-precision
4. Complex
5. Character
6. Logical
7. Octal
8. Double-octal
9. Hollerith
10. Statement label
The use and format of each of these data types are discussed in
Sections 3.2 through 3.10.
3.2 INTEGER CONSTANTS
An integer constant is a string of one to eleven digits that
represents a whole decimal number (a number without a fractional
part). Integer constants must be within the range of -(2**35-1) to
(+2**35)-1 (-34359738367 to +34359738367). Positive integer constants
3-1
CONSTANTS
may optionally be signed; negative integer constants must always be
signed. You cannot use decimal points, commas, or other symbols in
integer constants (except for a preceding sign, + or -).
Examples of valid integer constants are:
345
+345
-345
Examples of invalid integer constants are:
+345. (use of decimal point)
3,450 (use of comma)
34.5 (use of decimal point; not a whole number)
3.3 REAL CONSTANTS
A real constant can have any of the following forms:
1. A basic real constant: a string of decimal digits followed
by a decimal point, followed optionally by a decimal
fraction, for example, 1557.42.
2. A basic real constant followed by a decimal integer exponent
written in E notation (exponential notation) form, for
example, 1559.E2 or 1559.e2. The number following the E (or
e) specifies a power of ten by which the basic real constant
will be multiplied.
3. An integer constant (no decimal point) followed by a decimal
integer exponent written in E notation, for example, 1559E2
or 1559e2.
Real constants may be of any size; however, each will be rounded to
fit the precision of 27 bits (7 to 9 decimal digits).
Precision for real constants is maintained to approximately eight
significant digits; the absolute precision depends upon the numbers
involved.
The exponent field of a real constant written in E notation cannot be
empty (blank); it must be either a zero or an integer constant. The
range of magnitude permitted a real constant is from approximately
1.47 * 10**(-39) to 1.70 * 10**(+38).
The following are examples of valid real constants:
-98.765
7.0E+0 (= 7.)
3-2
CONSTANTS
.7E-3 (= .0007)
5E+5 (= 500000.)
50115.
50.E1 (= 500.)
The following are examples of invalid real constants:
72.6E512 (exponent is too large)
.375E (exponent incorrectly written)
500 (no decimal point given)
3.4 DOUBLE-PRECISION CONSTANTS
Double-precision constants are similar to real constants written in E
notation form; the differences between these two constants are:
1. Double-precision constants, depending on their magnitude,
have precision from 16 to 18 places, rather than the 8-digit
precision obtained for real constants.
2. Each double-precision constant occupies two storage
locations.
3. The letter D (or d), instead of E, is used in
double-precision constants to identify a decimal exponent.
On KL model B systems, there are two forms of double-precision number
formats. If the /GFLOATING compiler switch is specified (see Chapter
16), the double-precision number format is called G-floating. If the
/DFLOATING compiler switch (the default) is specified (see Chapter
16), the double-precision number format is called D-floating. See
Section 3.4.1 for a comparison of the different double-precision
number formats.
On KS systems, only the D-floating double-precision number format is
provided.
You must use both the letter D and an exponent (including zero) in
writing a double-precision constant. The range of magnitude permitted
a double-precision constant is from approximately:
1.47 * 10**(-39) to 1.70 * 10**(+38) for D-floating
or
2.78 * 10**(-309) to 8.99 * 10**(+307) for G-floating
The following are examples of valid double-precision constants:
7.9D03 (= 7900.)
3-3
CONSTANTS
7.9D+03 (= 7900.)
7.9D-3 (= .0079)
79D03 (= 79000.)
79D0 (= 79.)
The following are examples of invalid double-precision constants:
7.9D999 (exponent is too large)
7.9E5 ("E" denotes single precision; "D" denotes double
precision)
3.4.1 Comparison of Real, D-floating, and G-floating
For KL model B systems, G-floating double-precision is provided as an
alternative double-precision number format. You must specify the
/GFLOATING compiler switch (see Chapter 16) to invoke the G-floating
double-precision format. If you specify the /DFLOATING compiler
switch (the default), the D-floating format is used. Table 3-1
summarizes the comparisons among real, D-floating, and G-floating.
Table 3-1: Comparison of Real, D-floating, and G-floating Numbers
Bits of Bits of Digits of
Exponent Mantissa Range Precision
Real 8 27 1.47 * 10**(-39) 8.1
to 1.70 * 10**(+38)
D-floating 8 62 1.47 * 10**(-39) 18.7
to 1.70 * 10**(+38)
G-floating 11 59 2.78 * 10**(-309) 17.8
to 8.99 * 10**(+307)
3.5 COMPLEX CONSTANTS
You can represent a complex constant by an ordered pair of integer,
real, or octal constants written within parentheses and separated by a
comma. For example, (.70712, -.70712) and (8.763E3, 2.297) are
complex constants.
In a complex constant, the first (leftmost) constant of the pair
represents the real part of the number; the second constant represents
the imaginary part of the number. Both the real and imaginary parts
of a complex constant can be signed.
3-4
CONSTANTS
The constants that represent the real and imaginary parts of a complex
constant occupy two consecutive storage locations in the object
program.
3.6 CHARACTER CONSTANTS
A character constant is a string of printable ASCII characters
enclosed by apostrophes. Both delimiting apostrophes must be present,
and the string must be at least one character in length. The compiler
accepts control characters in character constants with the following
exceptions:
Character Octal Value
^@ - NUL "0
^J - LF "12
^K - VT "13
^L - FF "14
^M - CR "15
NOTE
The CHAR function (see Chapter 13) can be used to
build variables that contain these control characters.
The value of a character constant is the string of characters between
the delimiting apostrophes. The value does not include the delimiting
apostrophes, but does include all spaces or tabs within the
apostrophes.
Within a character constant, the apostrophe character is represented
by two consecutive apostrophes (with no space or other character
between them).
The length of the character constant is the number of characters
between the apostrophes, except that two consecutive apostrophes count
as a single apostrophe.
Each character in the string has a character position that is numbered
consecutively starting at one. The number indicates the sequential
position of a character in a string, from left to right. There is one
character storage location for each character in the string.
If a character constant appears in a numeric context (for example, as
the expression on the right side of an arithmetic assignment
statement), it is considered a Hollerith constant (see Section 3.9).
Examples of valid character constants and their lengths are:
3-5
CONSTANTS
Length Value
'WHAT?' 5 WHAT?
'TODAYS''S DATE IS: ' 18 TODAY'S DATE IS:
'He said, "hello"' 16 He said, "hello"
'''' 1 '
Examples of invalid character constants are:
'HEADINGS (no trailing apostrophe)
'' (a character constant must contain at least
one character)
"Now or Never" (quotation marks cannot be used in place of
apostrophes)
3.7 OCTAL AND DOUBLE-OCTAL CONSTANTS
You may use octal numbers (radix 8) as constants in arithmetic
expressions, logical expressions, and data statements. Octal numbers
up to 12 digits in length are considered standard octal constants;
they are stored right-justified in one storage location. When
necessary, standard octal constants are padded with leading zeros to
fill their storage location.
If you specify more than 12 digits in an octal number, it is
considered a double-octal constant. Double-octal constants occupy two
storage locations and may contain up to 24 right-justified octal
digits; leading zeros are added to fill any unused digits.
If you assign a single-octal constant to a double-precision or complex
variable, it is stored right-justified in the high-order word of the
variable. The low-order portion of the variable is set to zero. If
you assign a double-octal constant to a double-precision or complex
variable, it is stored right-justified in the two words.
All octal constants must:
1. Be preceded by a double quote (") to identify the digits as
octal, for example, "777
2. Be signed if negative, but optionally signed if positive
3. Contain one or more of the digits 0 through 7, but not 8 or 9
The following are examples of valid octal constants:
3-6
CONSTANTS
"123456700007
+"12345 (optional sign)
-"7777
"-7777
The following are examples of invalid octal constants:
"12368 (contains an 8)
7777 (no identifying double quote)
When you use an octal constant as an operand in an expression, its
form (bit pattern) is not converted to accommodate it to the type of
any other operand. For example, the subexpression (A + "202400000000)
has as its result the sum of A with the floating point number 2.0;
while the subexpression (I + "202400000000) has as its result the sum
of I with a large integer.
You cannot use octal constants as stand-alone arguments for library
functions that require non-octal arguments. MIN0, for instance,
requires integer arguments and cannot accept octal arguments.
When you combine a double-octal constant in an expression with (or
assign it to) either an integer or real variable, only the contents of
the high order location (leftmost) are used.
3.8 LOGICAL CONSTANTS
The Boolean values of truth and falsehood are represented in FORTRAN
source programs as the logical constants .TRUE. and .FALSE.. Always
write logical constants enclosed by periods, as in the preceding
sentence.
You may use logical quantities in arithmetic and logical statements.
Only the sign of a numeric value used in a logical IF statement is
tested to determine if it is true (negative) or false (nonnegative).
3.9 HOLLERITH CONSTANTS
A Hollerith constant is a string of alphanumeric and/or special
characters preceded by nH (for example, nHstring). In the prefix nH,
the letter n represents a number that specifies the exact number of
characters (including blanks) that follow the letter H.
NOTE
If a character constant appears in a numeric context
it is considered a Hollerith constant (see Section
3.6).
3-7
CONSTANTS
The following are examples of Hollerith constants:
2HAB
14HLOAD TEST #124
6H#124-A
NOTE
A tab in a Hollerith constant is counted as one
character; for example, 3H AB.
You may enter Hollerith constants into DATA statements as a string of:
1. Up to ten 7-bit ASCII characters for complex or
double-precision type variables
2. Up to five 7-bit ASCII characters for all other type
variables
The 7-bit ASCII characters that comprise a Hollerith constant are
stored left-justified (starting in the first word of a
double-precision constant (the high-order word) or the real part of a
complex constant) with blanks placed in empty character positions.
Hollerith constants that occupy more than one variable are stored as
successive variables in the list. The following example illustrates
how the string of characters is stored in a six-element array called
A:
DIMENSION A(6)
DATA A/27HA string of many characters/
A(1) is set to 'A str'
A(2) is set to 'ing o'
A(3) is set to 'f man'
A(4) is set to 'y cha'
A(5) is set to 'racte'
A(6) is set to 'rs '
3.10 STATEMENT LABEL CONSTANTS
Statement labels are numeric identifiers that represent program
statement numbers.
You write statement label constants as strings of one to five decimal
digits, that are preceded by either an asterisk (*), a dollar sign
($), or an ampersand (&). For example, *11992, $11992, and &11992 are
all valid statement label constants. You use statement label
constants only in the argument list of CALL statements to identify the
number of the executable statement to return to in a multiple RETURN
statement (see Chapter 13).
3-8
CHAPTER 4
SYMBOLIC NAMES, VARIABLES, AND ARRAYS
4.1 SYMBOLIC NAMES
| Symbolic names consist of any alphanumeric combination of one to 31
| characters, the first of which must be a letter. The special
| characters dollar sign ($) and underscore (_) are allowed. If you use
| more than 31 characters in a symbolic name, the compiler prints a
| warning message and ignores all but the first 31 characters. The
compiler interprets lowercase letters in symbolic names as uppercase
letters.
The following are examples of legal symbolic names:
A12345
| IAMBIC_PENTAMETER
ABLE
C
The following are examples of illegal symbolic names:
.AMBIC (first character is not a letter)
8AB (first character is not a letter)
You use symbolic names to identify specific items of a FORTRAN source
program; Table 4-1 lists these items, together with an example of a
symbolic name and text reference for each.
Table 4-1: Use of Symbolic Names
For a Detailed
Symbolic Names Description
Can Identify For Example See Section
1. Variables PI, CONST, LIMIT 4.2
2. Arrays TAX 4.3
3. Array elements TAX(3,5) 4.3.1
4-1
SYMBOLIC NAMES, VARIABLES, AND ARRAYS
4. Substrings FOO(1:N) 4.4
5. Functions MYFUNC, VALFUN 13.2
6. Subroutines CALCSB, SUB2, LOOKUP 13.4
7. Intrinsic functions SIN, ATAN, COSH 13.1
8. PROGRAM Statement TEST 6.4.1
9. PARAMETER Statement V1,C2,K 7.8
10. COMMON block names DATAR, COMDAT 7.4
11. NAMELIST list DATA3 12.6
4.2 VARIABLES
A variable is a data storage location identified by a symbolic name; a
variable is not a constant, an array, or an array element. Variables
specify values that are assigned to them in such ways as assignment
statements (Chapter 8), DATA statements (Chapter 7), or at run time
through I/O data transfers (Chapter 10). Before you assign a value to
a variable, its value is undefined; and you should not reference it
except to assign a value to it.
The value you assign to a variable can be either a constant or the
result of a calculation that is performed during the execution of the
object program. For example, the statement IAB=5 assigns the constant
5 to the variable IAB. In the statement IAB=5+IB, however, the value
assigned IAB depends on the value of variable IB at the time the
statement is executed.
The type of a variable determines the interpretation of its contents.
Variables can be:
1. Integer
2. Real
3. Logical
4. Double-precision
5. Complex
6. Character
The type of a variable is determined either implicitly, by the first
letter of the variable name (described below), or explicitly, by
declaring the variable type in a type declaration statement (see
Chapter 7).
FORTRAN uses the following default conventions for variables whose
types are not explicitly declared:
4-2
SYMBOLIC NAMES, VARIABLES, AND ARRAYS
1. Variable names that begin with the letters I, J, K, L, M, or
N are integer variables.
2. Variable names that begin with any letter other than I, J, K,
L, M, or N are real variables.
NOTE
These default conventions can be altered by
use of the IMPLICIT statement, which is
described in Section 7.3.
The following are examples of determining the type of a variable
according to the preceding conventions:
Variable Beginning Letter Assumed Data Type
ITEMP I Integer
OTEMP O Real
KA123 K Integer
AABLE A Real
4.3 ARRAYS
An array is an ordered set of data identified by an array name. Array
names are symbolic names and must conform to the rules for writing
symbolic names (see Section 4.1).
Arrays are made up of smaller units of data called array elements. As
with variables, you may assign a value to an array element. Before
you assign a value to an array element it has an undefined value. You
should not reference an array element until you have assigned it a
value.
An array element is referenced by using the array name together with
some number of subscripts that describe the position of the element
within the array.
4.3.1 Array Element Subscripts
The general form of an array element name is AN (S1, S2,...Sn), where
AN is the array name and S1 through Sn represent 1 through n subscript
expressions. You may use any number of subscript quantities in an
element name; however, the number used must always equal the number of
dimensions (see Section 4.3.2) specified for the array.
A subscript can be any constant or expression (see Chapter 5), for
4-3
SYMBOLIC NAMES, VARIABLES, AND ARRAYS
example:
1. Subscript quantities may contain arithmetic expressions that
involve addition, subtraction, multiplication, division, and
exponentiation. For example, (A+B,C*5,D/2) and
(A**3,(B/4+C)*E,3) are valid subscripts.
2. Arithmetic expressions (see Chapter 5) used in array
subscripts may be of any type, but noninteger expressions
(including complex) are converted to integer when the
subscript is evaluated.
3. A subscript may contain function references (see Chapter 13).
For example, TABLE (SIN(A)*B,2,3) is a valid array element
identifier.
4. Subscripts may contain array element identifiers nested to
any level as subscripts. For example, in the subscript
(I(J(K(L))),A+B,C) the first subscript expression given is a
nested 3-level array reference.
Some examples of valid array elements are:
1. IAB(1,5,3)
2. ABLE(A)
3. TABLE1(10/C+K**2,A,B)
4. MAT(A,AB(2*L),.3*TAB(A,M+1,D),55)
4.3.2 Dimensioning Arrays
You must declare the size (number of elements) of an array to enable
FORTRAN to reserve the number of locations needed to store the array.
Arrays are stored as a series of sequential storage locations.
Arrays, however, are visualized and referenced as if they were single
or multi-dimensional, rectilinear matrices dimensioned on a row,
column, and plane basis. For example, Figure 4-1 represents a 3-row,
3-column, 2-plane array.
4-4
SYMBOLIC NAMES, VARIABLES, AND ARRAYS
Figure 4-1: A 3 x 3 x 2 Array
You specify the size of an array by an array declarator written as a
subscripted array name. In an array declarator each subscript
quantity is a dimension of the array and must be either an integer
expression, an integer variable, or an asterisk (*).
Only the upper bound in the last dimension declarator in a list of
dimension declarators can be an asterisk. An asterisk marks the
declarators as an assumed-size array declarator (see Section 7.1.2).
NOTE
Variable array dimensions are only allowed in
subprograms. See adjustable dimension statements,
Section 7.1.1.
For example, TABLE(I,J,K) and MATRIX(10,7,3,4) are valid array
declarators.
The total number of elements that comprise an array is the product of
the dimension quantities given in its array declarator. For example,
the array IAB dimensioned as IAB(2,3,4) has 24 elements (2 * 3 * 4 =
24).
You dimension arrays only in the specification statements DIMENSION,
COMMON, and type declaration (see Chapter 7). Subscripted array names
appearing in any of the these statements are array declarators;
subscripted array names appearing in any other statements are always
array element identifiers.
4-5
SYMBOLIC NAMES, VARIABLES, AND ARRAYS
In array declarators, the position of a given subscript quantity
determines the particular dimension of the array (for example, row,
column, or plane) that it represents. The first three subscript
positions specify the number of rows, columns, and planes that
comprise the named array; each following subscript given then
specifies a set comprised of n-number (value of the subscript) of the
previously defined sets. For example:
NOTE
FORTRAN-10/20 permits up to 127 dimensions in an array
declarator. (The FORTRAN-77 Standard allows a maximum
of 7 dimensions.)
4.3.3 Order of Stored Array Elements
The elements of an array are stored in ascending order. The value of
the first (leftmost) subscript varies between its minimum and maximum
values most rapidly. The value of the last (rightmost) subscript
increases to its maximum value least rapidly. For example, the
elements of the array dimensioned as I(2,3) are stored in the
following order:
4-6
SYMBOLIC NAMES, VARIABLES, AND ARRAYS
I(1,1) I(2,1) I(1,2) I(2,2) I(1,3) I(2,3)
In the following list, the elements of the three-dimensional array
(B(3,3,3)) are stored row by row from left to right and from top to
bottom.
Thus B(3,1,1) is stored before B(1,2,1), and so forth.
Character array elements are stored in successive character positions,
and do not necessarily start on a word boundary. Character array
elements are stored five characters per word (seven bits per
character), and the low order bit is never used, for example:
CHARACTER*3 A(4)
The array A will be stored in the following way:
where:
x means bits are not used. The value in bit 35 is zero.
4-7
SYMBOLIC NAMES, VARIABLES, AND ARRAYS
4.4 CHARACTER SUBSTRINGS
A character substring is a contiguous segment of a character variable
or character array element. A character substring is identified by a
substring name and can be assigned values and referenced.
A character substring reference has one of the following forms:
v([e1]:[e2])
or
a(s[,s]...) ([e1]:[e2])
where:
v is a character variable name.
a is a character array name.
s is a subscript expression.
e1 is an optional numeric expression that specifies the
leftmost character position of the substring.
e2 is an optional numeric expression that specifies the
rightmost character position of the substring.
Character positions within a character variable or array element are
numbered from left to right, beginning at 1. For example, LABEL(2:7)
specifies the substring beginning with the second character position
and ending with the seventh character position of the character
variable LABEL.
If the value of the numeric expression e1 or e2 is not of type
integer, FORTRAN converts it to an integer value by truncating any
fractional part before use.
The values of the numeric expression e1 and e2 must meet the following
conditions:
1 .LE. e1 .LE. e2 .LE. len
where:
len is the length of the character variable or array element.
If e1 is omitted, FORTRAN assumes that e1 is 1. If e2 is omitted,
FORTRAN assumes that e2 equals len.
For example, NAMES(1,3)(:7) specifies the substring starting with the
first character position and ending with the seventh character
4-8
SYMBOLIC NAMES, VARIABLES, AND ARRAYS
position of the character array element NAMES(1,3).
4-9
5-1
CHAPTER 5
EXPRESSIONS
5.1 ARITHMETIC EXPRESSIONS
An arithmetic expression is formed with arithmetic operands and
arithmetic operators. The evaluation of such an expression produces a
numeric value.
Arithmetic expressions may be either simple or compound. A simple
arithmetic expression consists of an operand that can be:
1. A numeric constant
2. A numeric variable
3. A numeric array element
4. An arithmetic function reference (see Chapter 13)
5. An arithmetic or logical expression written within
parentheses
Operands may be of integer, real, double-precision, complex, logical,
octal, double-octal, or Hollerith type.
The following are examples of valid simple arithmetic expressions:
105 (integer constant)
IAB (integer variable)
TABLE(3,4,5) (array element)
SIN (X) (function reference)
(A+B) (a parenthetical expression)
A compound arithmetic expression consists of two or more operands
combined by arithmetic operators. Table 5-1 lists the arithmetic
operations permitted in FORTRAN and the operator recognized for each
operation.
5-1
EXPRESSIONS
Table 5-1: Arithmetic Operations and Operators
Operation Binary Operator Example
Addition + A+B
Subtraction - A-B
Multiplication * A*B
Division / A/B
Exponentiation ** or A**B or AB
Operation Unary Operator Example
Identity + +A
Negation - -B
5.1.1 Rules for Writing Arithmetic Expressions
Observe the following rules in structuring arithmetic expressions:
1. The operands comprising an arithmetic expression can be of
different types. Tables 5-2 and 5-3 illustrate all permitted
combinations of data types and the type assigned to the
result of each.
NOTE
All combinations of numeric data types except
double-precision with complex are allowed in
FORTRAN.
2. If you specify two adjacent operators, and the second is a
minus or a plus, the second operator is considered a unary
operator and acts only on the term immediately following it.
Thus, in the example (A*X+B)*+C, the subexpression, *+C, is
interpreted as the binary operator * and the unary +.
You cannot, however, have two adjacent binary operators in an
expression. For example, the expression A*/B is not
permitted.
3. All operators must be included; no operation is implied. For
example, the expression A(B) does not specify multiplication,
although this is implied in standard algebraic notation. The
expression A*(B) is required to specify a multiplication of
5-2
EXPRESSIONS
the operands.
5-3
EXPRESSIONS
Table 5-2: Type of the Result Obtained from Mixed-Mode Operations
5-4
EXPRESSIONS
Table 5-3: Permitted Base/Exponent Type Combinations
Base Operand Exponent Operand
Double-
Integer Real Precision Complex
Integer Integer Real Double- Complex
Precision
5-5
EXPRESSIONS
Real Real Real Double- Complex
Precision
Double- Double- Double- Double-
Precision Precision Precision Precision (Illegal)
Complex Complex Complex (Illegal) Complex
5.1.2 Arithmetic Constant Expressions
An arithmetic constant expression is an arithmetic expression in which
each operand is one of the following:
1. A numeric constant
2. A symbolic name of a numeric constant
3. An arithmetic constant expression enclosed in parentheses
4. A call to the function ICHAR (see Chapter 13) where the
argument is a character constant expression
The exponentiation operator is not permitted unless the exponent is of
type integer. Note that variables, array elements, and function
references are not allowed.
Example:
5+6*(ICHAR('Z')-ICHAR('A')+1)*4.1**3
5.1.2.1 Integer Constant Expression - An integer constant expression
is an arithmetic constant expression in which each constant or
symbolic name of a constant is of type integer.
Example:
3+4**6+2
5.2 CHARACTER EXPRESSIONS
Character expressions consist of character operands and character
operators. The evaluation of a character expression yields a single
value of character data type.
5-6
EXPRESSIONS
A character operand can be any one of the following:
1. A character constant
2. A symbolic name of a character constant
3. A character variable
4. A character array element
5. A character substring
6. A character expression, optionally enclosed in parentheses
7. A character function reference
The only character operator is the concatenation operator (//).
A character expression has the form:
character operand [//character operand]...
The value of a character expression is a character string formed by
successive left-to-right concatenations of the value of the elements
of the character expression. The length of a character expression is
the sum of the lengths of the character elements. For example, the
value of the character expression 'AB'//'CDE' is 'ABCDE', which has a
length of 5.
Note that the expression:
A=A//B
has no effect on A, since the concatenation result is truncated to the
length of A.
Parentheses do not affect the value of a character expression. For
example, the following character expressions are equivalent:
('ABC'//'DE')//'F'
'ABC'//('DE'//'F')
'ABC'//'DE'//'F'
Each of these character expressions has the value 'ABCDEF'.
If a character element in a character expression contains spaces, the
spaces are included in the value of the character expression. For
example, 'ABC '//'D E'//'F' has a value of 'ABC D EF'.
5-7
EXPRESSIONS
5.2.1 Character Constant Expression
A character constant expression is a character expression in which
each operand is one of the following:
1. A character constant
2. The symbolic name of a character constant
3. A character constant expression enclosed in parentheses
4. A call to the function CHAR (see Chapter 13) where the
argument is an integer constant expression
Variables, array elements, substrings, and function references are not
allowed.
Example:
'HELLO'//CHAR(13)//CHAR(10)//'GOODBYE'
5.3 LOGICAL EXPRESSIONS
Logical expressions can be either simple or compound. Simple logical
expressions consist of a logical operand, which can be one of the
following:
1. A constant
2. A variable
3. An array element
4. A function reference (see Chapter 13)
5. An expression written within parentheses
Compound logical expressions consist of two or more logical or numeric
operands combined by logical operators. The evaluation of a logical
expression produces a truth value (type logical, true or false) as
determined by the resulting bit pattern.
Table 5-4 gives the logical operators permitted by FORTRAN and a
description of the operation each provides.
5-8
EXPRESSIONS
Table 5-4: Logical Operators
Operator Description
.AND. AND operator. Both of the logical operands combined by
this operator must be true to produce a true result.
.OR. Inclusive OR operator. If either or both of the logical
operands combined by .OR. are true, the result will be
true.
.NEQV. Exclusive OR operator (also .XOR.). If either but not
both of the logical operands combined by .NEQV. is
true, the result will be true.
.EQV. Equivalence operator. If the logical operands being
combined by .EQV. are both the same (both are true or
both are false), the result will be true.
.NOT. Complement operator. This operator specifies
complementation (inversion) of the item (operand or
expression) that it modifies. The original item, if
true by itself, becomes false, and vice versa.
Logical expressions are of the general form P .op. Q, where P and Q
are logical operands and .op. is any logical operator except ".NOT.".
The .NOT. operator complements the value of an operand; it must
appear immediately before the operand that it modifies, for example,
.NOT.P.
Table 5-5 is a truth table illustrating all possible logical
combinations of two logical operands (P and Q) and the result of each
combination.
Table 5-5: Logical Operations Truth Table
When P is And Q is: Then the Expression: Is:
True ----- .NOT. P False
False ----- .NOT. P True
True True P .AND. Q True
True False P .AND. Q False
5-9
EXPRESSIONS
False True P .AND. Q False
False False P .AND. Q False
True True P .OR. Q True
True False P .OR. Q True
False True P .OR. Q True
False False P .OR. Q False
True True P .NEQV. Q False
True False P .NEQV. Q True
False True P .NEQV. Q True
False False P .NEQV. Q False
True True P .EQV. Q True
True False P .EQV. Q False
False True P. EQV. Q False
False False P .EQV. Q True
For example, consider the following variables:
Variables Type
PHETT, RUN Real
I,J,K Integer
DP,D Double-Precision
L,A,B Logical
CPX,C Complex
Examples of valid logical expressions consisting of the preceding
variables are:
L.AND.B
(PHETT*I).NEQV.(DP+K)
L.AND.A.OR..NOT.(I-K)
Logical operations are performed on the full 36-bit binary
representation of the operands involved. However, when an operand of
5-10
EXPRESSIONS
a logical expression is double-precision or complex, only the first
word of a double-precision operand (the high-order word) or the real
part of the complex operand is used in the specified logical
operation.
The result of a logical operation is found by performing the specified
operation simultaneously for each of the corresponding bits in each
operand. For example, consider the expression A=C.OR.D, where C="456
and D="201. The operation performed by the processor and the result
is:
Word
Bits 0 1 24 25 26 27 28 29 30 31 32 33 34 35
Operand C 0 0 0 0 0 1 0 0 1 0 1 1 1 0
Operand D 0 0 0 0 0 0 1 0 0 0 0 0 0 1
Result A 0 0 0 0 0 1 1 0 1 0 1 1 1 1
Table 5-5 also illustrates all possible logical combinations of two
one-bit binary operands (P and Q) and gives the result of each
combination. Simply read 1 for true and 0 for false.
If a logical expression is used as an operand in an arithmetic
expression, its value is not converted to accommodate it to the type
of any other operand.
5.3.1 Logical Constant Expression
A logical constant expression is a logical expression in which each
operand is one of the following:
1. A logical constant
2. The symbolic name of a logical constant
3. A relational expression in which each operand is a constant
expression
4. A logical constant expression enclosed in parentheses
Variables, array elements, and function references are not allowed.
Example:
.NOT.(PARML1.NE.PARML2)
where PARML1 and PARML2 are specified in a PARAMETER statement (see
Section 7.8).
5-11
EXPRESSIONS
5.4 RELATIONAL EXPRESSIONS
Relational expressions consist of two arithmetic expressions or two
character expressions combined by a relational operator. The
relational operator allows you to test the relationship between two
arithmetic or two character expressions.
The result of a relational expression is always a logically true or
false value.
You can write relational operators either as a 2-letter mnemonic
enclosed within periods (for example, .GT.) or use the symbolic
equivalent, for example, >, instead of .GT.
Table 5-6 lists the mnemonic and symbolic forms of the FORTRAN-10/20
relational operators and specifies the type of test performed by each.
Table 5-6: Relational Operators and Operations
Operators Relation Tested
Mnemonic Symbolic
.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
Relational expressions are of the general form A .op. B, where A and B
represent arithmetic or character operands, and .op. is a relational
operator.
You can mix arithmetic operands of type integer, real, and
double-precision in relational expressions.
A relational expression cannot be used to compare the value of an
arithmetic expression with the value of a character expression.
However, you can compare a numeric expression to a character constant.
In this case, the character constant is considered to be a Hollerith
(see Section 3.9).
You can compare complex operands using only the operators .EQ. (==)
and .NE. (#). Complex quantities are equal if the corresponding
parts of both words are equal.
5-12
EXPRESSIONS
For example, assume the following variables:
Variables Type
PHETT, RON Real
I,J,K Integer
DP,D Double-Precision
L,A,B Logical
CPX,C Complex
CHR,RA Character
Examples of valid relational expressions consisting of the above
variables are:
(PHETT).GT.10
I == 5
C.EQ.CPX
CHR.LT.RA
Examples of invalid relational expressions consisting of the above
variables are:
(PHETT).GT 10 (closing period missing from operator)
C.GT.CPX (complex operands can only be compared by .EQ.
and .NE. operators)
RA.EQ.RON (you cannot compare arithmetic operands and
character operands)
Examples of valid expressions that use both logical and relational
operators to combine the preceding variables are:
(I.GT. 10).AND.(J.LE.K)
((I*RON).EQ.(I/J)).OR.L
(I.AND.K)#((PHETT).OR.(RON))
C#CPX.OR.RON
If a logical expression is used as an operand in an arithmetic
expression, its value is not converted to accommodate it to the type
of any other operand.
In character relational expressions "less than" means "precedes in the
ASCII collating sequence," and "greater than" means "follows in the
ASCII collating sequence", for example:
'AB'//'ZZZ' .LT. 'CCCCC'
This expression tests whether 'ABZZZ' is less than 'CCCCC'. Since
that relationship does exist, the value of the expression is true. If
5-13
EXPRESSIONS
the relationship stated does not exist, the value of the expression is
false.
If the two character expressions in a relational expression are not
the same length, the comparison is performed as if the shorter one is
padded on the right with spaces until the lengths are equal, for
example:
'ABC' .EQ. 'ABC '
'AB' .LT. 'C'
The first relational expression has a value of true even though the
lengths of the expressions are not equal, and the second has a value
of true even though 'AB' is longer than 'C'.
NOTE
The rule that character relationals extend the shorter
operand with spaces to match the length of the longer
operand has an interesting effect when the longer
string ends with characters in the range CHAR(0) to
CHAR(31) (ASCII control characters such as 'bell' and
line feed).
Since space is CHAR(32), the trailing spaces supplied
as filler by FORTRAN compare being greater than
trailing control characters. Thus, the string 'FOO'
is .GT. 'FOO^G' (FOO followed by a bell).
5.5 EVALUATION OF EXPRESSIONS
The following considerations determine the order of computation of a
FORTRAN expression:
1. The use of parentheses
2. An established hierarchy for the execution of arithmetic
relational, and logical operations
3. The location of operators within an expression
5.5.1 Parenthetical Subexpressions
In an expression, all subexpressions enclosed within parentheses are
evaluated first. When parenthetical subexpressions are nested (one
contained within another), the most deeply nested subexpression is
5-14
EXPRESSIONS
evaluated first; the next most deeply nested subexpression is
evaluated second; and so on, until the value of the final
parenthetical expression is computed.
When more than one operator is contained in a parenthetical
subexpression, the required computations are performed according to
the hierarchy assigned to operators by FORTRAN (see Section 5.5.2).
For example, the separate computations performed in evaluating the
expression A+B/((A/B)+C)-C are:
1. R1=A/B
2. R2=R1+C
3. R3=B/R2
4. R4=A+R3
5. R5=R4-C
where:
R1 through R5 represent the interim and final results of the
computations performed.
5.5.2 Hierarchy of Operators
The following hierarchy (order of execution) is assigned to the
classes of FORTRAN operators:
first, arithmetic operators
second, relational operators
third, logical operators
Table 5-7 specifies the precedence assigned to the individual
operators of the above classes.
With the exception of exponentiation and integer division, all
operations on expressions or subexpressions involving operators of
equal precedence are computed in any order that is algebraically
correct.
A subexpression of a given expression may be computed in any order.
For example, in the expression (F(X) + A*B), the function reference
may be computed either before or after A*B.
5-15
EXPRESSIONS
Table 5-7: Hierarchy of FORTRAN Operators
Class Level Symbol or Mnemonic
EXPONENTIAL First ** or ^
Second -(negation) and + (identity)
ARITHMETIC Third *,/
Fourth +,-
RELATIONAL Fifth .GT.,.GE.,.LT.,.LE.,.EQ.,.NE.
or
>,>=,<,<=,==,#
Sixth .NOT.
Seventh .AND.
LOGICAL Eighth .OR.
Ninth .EQV.,.NEQV.
Operations specifying integer division are evaluated from left to
right. For example, the expression I/J*K is evaluated as if it had
been written as (I/J)*K), but this left-to-right evaluation process
can be overridden by parentheses. I/J*K (evaluated as(I/J) *K) does
not equal I/(J*K).
When a series of exponentiation operations occurs in an expression, it
is evaluated in order from right to left. For example, the expression
A**2**B is evaluated in the following order:
first R1 = 2**B (intermediate result)
second R2 = A**R1 (final result).
As with other expressions, parentheses alter the evaluation of the
above expression. The expression (A**2)**B is evaluated in these two
steps:
first R1 = A**2 (intermediate result)
second R2 = R1**B (final result)
5.5.3 Mixed-Mode Expressions
Mixed-mode expressions are evaluated on a basis of
subexpression-by-subexpression, with the type of the results obtained
converted and combined with other results or terms according to the
conversion procedures described in Table 5-2.
For example, assume the following variables and data types:
5-16
EXPRESSIONS
Variables Type
D Double-Precision
X Real
I,J Integer
The mixed-mode expression D+X*(I/J) is evaluated in the following
manner:
1. R1 = I/J R1 is integer
2. R2 = X*R1 R1 is converted to type real and is multiplied by X
to produce R2
3. R3 = D+R2 R2 is converted to type double-precision and is
added to D to produce R3
where:
R1 and R2, and R3 represent the interim and final results
respectively of the computations performed.
5.5.4 Use of Logical Operands in Mixed-Mode Expressions
When you use logical operands in mixed-mode expressions, the value of
the logical operand is not converted in any way to accommodate it to
the type of the other operands in the expression. For example, in
L*R, where L is type logical and R is type real, the expression is
evaluated without converting L to type real.
5.6 CONSTANT EXPRESSIONS
A constant expression is an arithmetic constant expression (see
Section 5.1.2), a character constant expression (see Section 5.2.1),
or a logical constant expression (see Section 5.3.1).
5-17
6-1
CHAPTER 6
EXECUTABLE AND NONEXECUTABLE STATEMENTS
Each statement is classified as executable or nonexecutable.
Executable statements specify actions and form an execution sequence
in a program. Nonexecutable statements do the following:
1. Specify characteristics, arrangement, and initial values of
data
2. Contain editing information
3. Specify statement functions
4. Classify program units
5. Specify entry points within subprograms
Nonexecutable statements are not part of the execution sequence.
Nonexecutable statements may be labeled, but such statement labels
must not be used to control the execution sequence.
6.1 EXECUTABLE STATEMENTS
The following statements are classified as executable:
1. Arithmetic, logical, statement label (ASSIGN), and character
assignment statements
2. Unconditional GO TO, assigned GO TO, and computed GO TO
statements
3. Arithmetic IF, logical IF statements, and two-branch logical
IF statements, IF THEN, ELSE, and ELSE IF THEN statements
4. CONTINUE statement
6-1
EXECUTABLE AND NONEXECUTABLE STATEMENTS
5. STOP and PAUSE statements
6. DO and DO WHILE statements
|
| 7. READ, REREAD, WRITE, REWRITE, and PRINT statements
|
| 8. DELETE and UNLOCK statements
9. OPEN and CLOSE statements
10. REWIND, BACKSPACE, ENDFILE, BACKFILE, SKIPRECORD, SKIPFILE,
FIND and UNLOAD statements
11. CALL and RETURN statements
12. END, END IF, and END DO statements
13. DECODE and ENCODE statements
14. ACCEPT, PUNCH, and TYPE statements
15. INQUIRE statement
6.2 NONEXECUTABLE STATEMENTS
The following statements are classified as nonexecutable:
1. PROGRAM, FUNCTION, SUBROUTINE, ENTRY, and BLOCK DATA
statements
2. DIMENSION, COMMON, EQUIVALENCE, IMPLICIT, PARAMETER,
INTRINSIC, EXTERNAL, and SAVE statements
3. INTEGER, REAL, DOUBLE PRECISION, COMPLEX, LOGICAL, and
CHARACTER type-specification statements
4. DATA statement
5. FORMAT statement
6. Statement function statement
7. INCLUDE statement
8. NAMELIST statement
6-2
EXECUTABLE AND NONEXECUTABLE STATEMENTS
6.3 ORDERING OF FORTRAN STATEMENTS
The order in which you place FORTRAN statements in a program unit is
important. Certain types of statements must be processed before
others to guarantee that compilation takes place as you expect.
Figure 6-1 shows the required order of statements and comment lines
within a program unit. Horizontal lines indicate (from the top of the
diagram to the bottom) the order in which statements and comment lines
must appear in a program. For example, a PROGRAM statement must occur
before FORMAT statements. FORMAT statements, in turn, must occur
before an END statement.
Vertical lines in the diagram indicate how comment lines and
statements may be interspersed in the program. For example, PARAMETER
statements must be placed after all PROGRAM, FUNCTION, or SUBROUTINE
statements, and before all statement function and executable
statements. PARAMETER statements can be placed before, after, or
between all IMPLICIT and other specification statements. Comment
lines may be interspersed anywhere in a program.
Generally if FORTRAN encounters statements that are out of place, it
prints warning messages and continues compilation. In some cases,
however, out-of-place statements cause the compiler to terminate
compilation or generate unexpected results.
6-3
EXECUTABLE AND NONEXECUTABLE STATEMENTS
Figure 6-1: Ordering of FORTRAN Statements
NOTE
In FORTRAN-10/20, a DATA statement can precede a
PARAMETER statement or another specification
statement.
6-4
EXECUTABLE AND NONEXECUTABLE STATEMENTS
6.4 COMPILATION CONTROL STATEMENTS
You use compilation control statements to identify FORTRAN programs
and to specify their termination. Statements of this type do not
affect either the operations performed by the object program, or the
manner in which the object program is executed. The three compilation
control statements are:
1. PROGRAM statement
2. INCLUDE statement
3. END statement
The PROGRAM statement and the INCLUDE statement are described in the
following sections. The END statement is described in Section 9.8.
6.4.1 PROGRAM Statement
This statement allows you to give the main program a name other than
the compiler-assumed name "MAIN." The general form of a PROGRAM
statement is:
PROGRAM name
where:
name is a symbolic name that begins with an alphabetic
character and contains a maximum of six characters.
(See Section 4.1 for a description of symbolic names.)
The PROGRAM statement must be the first statement in a program unit.
(see Section 6.3 for a discussion of the ordering of FORTRAN
statements.)
6.4.2 INCLUDE Statement
This statement allows you to include code segments or external
declarations in a program unit without having them in the same file as
the primary program unit. When an INCLUDE statement is encountered
during compilation, the compiler replaces the INCLUDE statement with
the contents of the specified file. The general form of the INCLUDE
statement is:
INCLUDE 'filespec [/switch]'
where:
6-5
EXECUTABLE AND NONEXECUTABLE STATEMENTS
filespec is a TOPS-10 or TOPS-20 file specification (refer
to the TOPS-10 or TOPS-20 Operating System
Commands manual). The only restriction is that
under TOPS-10 you cannot specify subdirectory
information.
switch is one of the following optional switches:
/CREF indicates the included statements
are to be used to augment the
cross-reference listing (default).
/LIST indicates that the statement in the
specified file is to be listed in
the compilation source listing. A
number indicating the depth of
nesting of include files precedes
each statement listed (default).
/NOLIST indicates that the included
statements are not to be printed in
the compilation listing.
/NOCREF indicates that the included
statements are not to be used to
augment the cross-reference
listing.
The following rules govern the use of the INCLUDE statement:
1. The INCLUDEd file can contain any legal FORTRAN statement
except a statement that terminates the current program unit,
such as the END, PROGRAM, FUNCTION, SUBROUTINE, or BLOCK DATA
statements.
The INCLUDEd file can contain other INCLUDE statements. This
is called nesting INCLUDE statements. The number of nested
levels is restricted to 12.
2. The proper placement of the INCLUDE statement within a
program unit depends upon the types of statements to be
INCLUDEd. (See Section 6.3 for information on the ordering
of FORTRAN statements.)
3. The file to be INCLUDEd must be on disk.
Note that an asterisk (*) is appended to the line numbers of the
INCLUDEd statements on the compilation listing. The level of nesting
is indicated following the asterisk.
6-6
CHAPTER 7
SPECIFICATION AND DATA STATEMENTS
Specification statements are used to specify type characteristics,
storage allocation, and data arrangement. There are ten types of
specification statements:
1. DIMENSION
2. Statements that explicitly specify type, including INTEGER,
REAL, DOUBLE PRECISION, COMPLEX, LOGICAL, or CHARACTER
3. IMPLICIT
4. COMMON
5. EQUIVALENCE
6. EXTERNAL
7. INTRINSIC
8. PARAMETER
9. DATA
10. SAVE
Specification statements are nonexecutable and must conform to the
ordering guidelines described in Section 6.3.
7.1 DIMENSION STATEMENT
The DIMENSION statement provides FORTRAN with information needed to
identify and allocate the space required for arrays. You may specify
any number of subscripted array names as array declarators in a
DIMENSION statement. The general form of a DIMENSION statement is:
7-1
SPECIFICATION AND DATA STATEMENTS
DIMENSION a(d) [,a(d)...]
where:
each a(d) is an array declarator. An array declarator
provides the name and dimension(s) of an array.
An array declarator is written in the following
form:
a(d [,d...])
where:
a is the symbolic name of the array.
d is the array dimension declarator. The form of a dimension
declarator is as follows:
[ d1: ] d2
where:
d1 is an optional integer expression or integer
variable specifying the lower dimension bound.
The lower dimension bound is the first element in
that dimension of the array. If d1 is not
specified the default is 1.
d2 is an integer expression or integer variable that
specifies the upper dimension bound. The upper
dimension bound is the greatest element in that
dimension of the array. You must have at least
one d2 specification in each array declaration.
If both d1 and d2 are specified, d1 cannot have a
value greater than d2. The values d1 and d2 can,
however, be the same.
An asterisk (*) can also occur as an upper bound,
but only as the last dimension. An asterisk marks
the declarator as an assumed-size array declarator
(see Section 7.1.2).
NOTE
A dimension bound expression must not contain a
function or array element reference.
If the array is a dummy argument to a subprogram, then d1 and d2 can
be integer dummy arguments and d2 can be an asterisk; otherwise, they
7-2
SPECIFICATION AND DATA STATEMENTS
must be constants.
If the symbolic name of a constant or variable that appears in a
dimension bound expression is not of implicit default integer type
(see Section 4.2), it must be specified integer by an IMPLICIT
statement or a type-statement.
Examples:
DIMENSION EDGE (-1:1,4:8), NET (5,10,4), TABLE (567)
DIMENSION TABLE (IAB:J,K,M,10:20)
where:
IAB, J, K, and M are of type integer.
7.1.1 Adjustable Dimensions
When used within a subprogram, a declarator for an array that is a
dummy argument can use integer dummy arguments as dimension bounds.
The following rules govern the use of adjustable dimensions in a
subprogram:
1. The array name must be a dummy argument. Each variable that
is used as a dimension bound must be either a dummy argument
or in COMMON (see Section 7.4).
2. For multiple entry subprograms, if any variables that specify
dimension bounds are dummy arguments which do not occur in
the formal argument list of the entry point used, the value
of the variables as passed for a previous call are used.
However, this is only permitted if the subprogram has not
changed those dummy arguments. Futhermore, when overlays are
used, a SAVE statement that preserves the local variables of
the subprogram is needed.
3. If the value of an array dimension variable is altered within
the program, the dimensionality of the array is not affected.
4. The size of an array within a subprogram cannot exceed the
size of the original array, as defined in the calling
program.
Example 1:
SUBROUTINE SBR (ARRAY,M1,M2,M3,M4)
DIMENSION ARRAY(M1:M2,M3:M4)
DO 27 L=M3,M4
DO 27 K=M1,M2
ARRAY (K,L)=VALUE
7-3
SPECIFICATION AND DATA STATEMENTS
27 CONTINUE
END
In the example above, the dimensions of ARRAY will be re-specified
each time the subroutine SBR is entered.
Example 2:
SUBROUTINE SB1 (ARR1,M,N)
DIMENSION ARR1(M,N)
ARR1(M,N)=VALUE
ENTRY SB2(ARR1,M)
ENTRY SB3(ARR1,N)
ENTRY SB4(ARR1)
.
.
.
END
In the example above, the first call made to the subroutine must be
made to SB1 so that all of the dimension bounds have defined values.
If a call is made to SB1 with the values M=11 and N=13, a succeeding
call to SB2 will use the value N=13, but will give M a new value. If
a succeeding call is made to SB4, the last values passed through
entries SB1, SB2, or SB3 are used for M and N.
7.1.2 Assumed-size Arrays
An assumed-size array is a dummy array for which the upper bound of
the last dimension is specified as an asterisk(*), for example:
SUBROUTINE SUB(A,N)
DIMENSION A(1:N,1:*)
Since storage for array A is allocated in the calling routine, the
upper bound of the rightmost dimension of A does not affect the
subscript calculations or storage allocation for A.
Therefore, subroutine SUB can be written to handle arguments with any
rightmost dimension (the last subscript is never range checked for
being too large, even when the /DEBUG:BOUNDS compiler switch is
specified). Such a subroutine can declare assumed-size arrays.
The size of an assumed-size array, and the number of elements that can
be referenced, are determined as follows:
1. If the actual argument corresponding to the dummy array is a
noncharacter array name, the size of the dummy array is the
size of the actual-argument array.
7-4
SPECIFICATION AND DATA STATEMENTS
2. If the actual argument corresponding to the dummy argument is
a noncharacter array element name, with a subscript value of
s in an array of size a, the size of the dummy array is:
a+1-s.
3. If the actual argument is a character-array name,
character-array element name, or character-array element
substring name, and begins at character storage unit b of an
array with n character storage units, the size of the dummy
array is INT((n+1-b)/y). Where y is the length of an element
of the dummy array.
Because the actual size of an assumed-size array is not known, an
assumed-size array name cannot be used as:
1. An array name in the list of an I/O statement
2. A unit identifier for an internal file in an I/O statement
3. A format specifier in an I/O statement
4. A NAMELIST statement element
7.2 TYPE SPECIFICATION STATEMENTS
Type specification statements explicitly declare the data type of
variables, arrays, or function names. You can give an array name in a
type specification statement, either alone (unsubscripted) to declare
the type of all its elements, or with dimension bounds, to specify
both its type and dimensions.
There are two forms of type specification statements: numeric type
specification (see Section 7.2.1) and character type specification
(see Section 7.2.2).
7.2.1 Numeric Type Specification Statements
The general form of numeric type specification statements is:
type v[,v...]
where:
type can be any one of the following declarators:
1. INTEGER
7-5
SPECIFICATION AND DATA STATEMENTS
2. REAL
3. DOUBLE PRECISION
4. COMPLEX
5. LOGICAL
v is a variable, array, or function name to be declared
the specified type. The names listed must be separated
by commas and can appear in only one type statement
within a program unit.
Examples:
INTEGER A, B, TABLE, FUNC
REAL R, M, ARRAY(5:10,10:20,5)
If a name that is the same as an intrinsic FORTRAN function name
appears in a conflicting type statement, it is assumed that the name
refers to a user-defined routine, variable, or array of the given
type. If you place a generic FORTRAN function name in an explicit
type statement, it loses its generic properties.
NOTE
The data type size modifier, *n, is accepted by
FORTRAN-10/20 to be compatible with the type
statements used by other manufacturers. You may
append this size modifier to the declarators, causing
some to elicit messages warning users of the form of
the variable specified by FORTRAN-10/20:
Declarator Form of Variable Specified
INTEGER*2 Full word integer with warning message
INTEGER*4 Full word integer
LOGICAL*1 Full word logical with warning message
LOGICAL*2 Full word logical with warning message
LOGICAL*4 Full word logical
REAL*4 Full word real
REAL*8 Double-precision real
COMPLEX*8 Complex
COMPLEX*16 Complex with warning message
REAL*16 Double-precision real with warning message
COMPLEX*32 Complex with warning message
In addition, you can append the data
type size modifier to individual
variables, arrays, or function names.
7-6
SPECIFICATION AND DATA STATEMENTS
Its effect is to override, for the
particular element, the size modifier
(explicit or implicit) of the primary
type. For example,
REAL*4 A, B*8, C*8(10), D
A and D are single-precision (one word)
real, and B and C are double-precision
(two words for each element) real.
7.2.2 Character Type Specification Statements
The form of the character type specification statement is:
CHARACTER [*len[,]] v[*len] [,v[*len]]...
where:
v is one of the following:
o The name of a symbolic constant, variable, array, or
function subprogram
o An array declarator
len is the length of the character data item and is one of the
following:
o An unsigned, nonzero integer constant
o An integer constant expression enclosed in parentheses
and with a positive value
o An asterisk enclosed in parentheses
If you specify CHARACTER*len, len is the default length specification
for that list. If an item in that list does not have a length
specification, the item's length is len. But if an item does have a
length specification, it overrides the default length specified in
CHARACTER*len.
A length specification of asterisk (for example, CHARACTER*(*))
specifies that a dummy argument or function name assumes the length
specification of the corresponding actual argument or function
reference (see Chapter 13). A length specification of asterisk for
the symbolic name of a constant specifies that the symbolic constant
assumes the actual length of the constant that it represents.
If you do not specify a length, a length of one is assumed. Note that
7-7
SPECIFICATION AND DATA STATEMENTS
a length specification of zero is invalid. You can use a character
type declaration statement to define arrays by including array
declarators (see Section 4.3.2) in the list. If you specify both an
array declarator and a length, the array bounds precede the length,
the form is:
a[(d)][*len]
where:
a is an array name, and a(d) is an array declarator.
Examples of character type specification statements follow:
CHARACTER*32 SOCSEC(100)*9, NAMES(100)
The above statement specifies an array SOCSEC comprising one hundred
9-character elements, and an array NAMES comprising one hundred
32-character elements.
PARAMETER (LENGTH=4)
CHARACTER*(4+LENGTH) LAST, FIRST
The above statements specify two 8-character variables, LAST and
FIRST. (The PARAMETER statement is described in Section 7.8.)
SUBROUTINE S1(BUBBLE)
CHARACTER LETTER(26), BUBBLE*(*)
The above statements specify an array LETTER comprising twenty-six
1-character elements and a dummy argument, BUBBLE, which has a length
defined by the calling program.
CHARACTER*16 QUEST*(5*INT(A))
The above statement is invalid. The length specifier for QUEST is not
an integer constant expression.
7.3 IMPLICIT STATEMENTS
IMPLICIT statements declare the data type of variables and functions
according to the first letter of each symbolic name. The IMPLICIT
statement has two forms:
IMPLICIT type (a[,a]...)[,type (a[,a]...)]...
IMPLICIT NONE
As shown in the statement above, an IMPLICIT statement consists of one
or more type declarators separated by commas. Each type declarator
7-8
SPECIFICATION AND DATA STATEMENTS
has the form:
type (a[,a]...)
where:
type can be any one of the following declarators:
1. INTEGER
2. REAL
3. DOUBLE PRECISION
4. COMPLEX
5. LOGICAL
6. CHARACTER[*len]
a is an alphabetic specification in either of the general
forms: c or c1-c2, where c, c1, or c2 is an alphabetic
character. The latter form specifies a range of
letters, from c1 through c2, which must occur in
alphabetical order.
When you specify type as CHARACTER*len, len specifies the length for
character data type. Len is an unsigned, nonzero integer constant or
an integer constant expression enclosed in parentheses and with a
positive value. If you do not specify a length, a length of one is
assumed.
Each letter in a type declarator list specifies that each symbolic
name (not declared in an explicit type specification statement)
starting with that letter is assigned the data type named in the
declarator. For example, the statement:
IMPLICIT REAL (R,M,N,O)
declares that all names that begin with the letters R, M, N, or O are
type REAL names, unless declared otherwise in an explicit type
statement.
NOTE
Type declarations given in an explicit type
specification override those also given in an IMPLICIT
statement. IMPLICIT declarations do not affect
intrinsic functions. The length is also overridden
when a particular name appears in a CHARACTER or
CHARACTER FUNCTION statement (see Chapter 13).
7-9
SPECIFICATION AND DATA STATEMENTS
You may specify a range of letters within the alphabet by writing the
first and last letters of the desired range separated by a dash, for
example, A-E for A,B,C,D,E.
Thus, the statement:
IMPLICIT INTEGER (I,L-P)
declares that all symbolic names that begin with the letters
I,L,M,N,O, and P are of type INTEGER.
You may use more than one IMPLICIT statement, but they must appear
before any other declaration statement in the program unit. (See
Section 6.3 for a discussion on ordering FORTRAN statements.)
The same letter must not appear as a single letter, or be included in
a range of letters, more than once in all of the IMPLICIT statements
in a program unit.
You can use an IMPLICIT NONE statement to provide warning messages for
variables not explicitly declared, including variables implicitly
declared by other IMPLICIT statements. If you specify IMPLICIT NONE,
no other IMPLICIT statement should be included in the program unit.
7.4 COMMON STATEMENT
The COMMON statement enables you to establish storage that may be
shared by two or more programs and/or subprograms, and to name the
variables and arrays that are to occupy the common storage. The use
of common storage conserves storage and provides a means to reference
the same data in different subprograms without passing arguments.
COMMON statements have the following form:
COMMON [/cb/] nlist[[,]/[cb]/nlist]...
where:
cb is an optional common block name. (See Section 4.1 for
the rules for symbolic names.)
nlist is a list of variable names, array names, and array
declarators that are to occupy the common area. The
items specified for a common area (block) are ordered
within storage as they are listed in the COMMON
statement.
The items in nlist must be either all numeric data type or all
character data type. A common block cannot contain both numeric and
character data.
7-10
SPECIFICATION AND DATA STATEMENTS
A symbolic name can be used to identify each block. However, you can
omit the symbolic name for one block in a program unit. This
unlabeled block is called the blank common block.
The elements of a named common block can be assigned initial values by
DATA statements appearing in the BLOCK DATA subprograms (see Chapter
14). In standard-conforming programs, the elements of the blank
common block may not be assigned initial values. However,
FORTRAN-10/20 allows any common block elements to be defined in a DATA
statement in any program unit.
A given common block name may appear more than once in the same COMMON
statement, and in more than one COMMON statement within the same
program or subprogram.
When extended addressing is in effect, COMMON blocks reside in the
large data area by default. However, the /EXTEND:COMMON or
/EXTEND:NOCOMMON switches can be used to explicitly allocate COMMON
blocks in the large data area or small data area (see Section 16.5).
During compilation of a source program, FORTRAN strings together all
items listed for each common block in the order in which they appear
in the source program. For example:
COMMON X,Y,Z/ST1/A,B
COMMON/ST1/TST(3,4)/ST2/TAB(2,2)
COMMON/ST2/C,D,E//P,Q
COMMON W
has the same effect as the single statement:
COMMON X,Y,Z,P,Q,W/ST1/A,B,TST(3,4)/ST2/TAB(2,2),C,D,E
All elements specified for a common block are placed into one area.
Common block names must be unique with respect to all subroutine,
function, and entry point names.
NOTE
If you use overlays, you can use the SAVE statement to
retain the value of variables in a named common across
overlays (see Section 7.10). (Blank common is always
saved.)
For example:
Main Program Subprogram
7-11
SPECIFICATION AND DATA STATEMENTS
COMMON DELTA,LENGTH SUBROUTINE CALC
COMMON /COM1/KILOS,PRICE COMMON/COM1/N,A
. COMMON Z,KOUNT
. .
. .
CALL CALC .
.
.
.
The COMMON statements in the main program put DELTA and LENGTH into
the blank common block, and put KILOS and PRICE into a common block
named COM1.
The COMMON statements in the subroutine make Z correspond to DELTA in
the main program, KOUNT correspond to LENGTH, N correspond to KILOS,
and A correspond to PRICE.
To prevent conflict with other COMMON blocks, LINK requires that the
largest definition for each common block be loaded first.
7.4.1 Dimensioning Arrays in COMMON Statements
Array names with dimension bounds can be given in COMMON statements.
However, variables cannot be used as dimension bounds in a declarator
appearing in a COMMON statement; adjustable dimensioning is not
permitted in COMMON.
Each array name given in a COMMON statement must be dimensioned either
by the COMMON statement or by another dimensioning statement within
the program or subprogram that contains the COMMON statement, but not
both.
For examples,
COMMON /A/B(100), C(10,10)
COMMON X(5,15),Y(5)
7.4.2 Character Data in COMMON
Each character variable in a COMMON block is allocated to start at the
first available character position.
For example,
CHARACTER B*3,C*3,D(3)*2
COMMON B,C,D
7-12
SPECIFICATION AND DATA STATEMENTS
The COMMON block will be allocated in the following way:
where x means the bits are not used.
7.5 EQUIVALENCE STATEMENT
The EQUIVALENCE statement associates two or more variables with the
same storage location.
The format of the EQUIVALENCE statement is:
EQUIVALENCE(nlist) [,(nlist...)]
where:
nlist is a list of variable names, array elements, array
names, and character substring references separated by
commas and enclosed in parentheses. You must specify
two or more of these items in each list.
In an EQUIVALENCE statement, each expression in a subscript or a
substring reference must be an integer constant expression.
The EQUIVALENCE statement allocates all of the items in one
parenthesized list beginning at the same storage location. For
example, the statements:
EQUIVALENCE (A,B,C)
EQUIVALENCE (LOC,SHARE(3))
specify that the variables A, B, and C are to share the same storage
location, and that the variable LOC and the array element SHARE(3) are
to share the same location.
The relationship of equivalence is transitive. For example, the
following statements have the same effect:
EQUIVALENCE (A,B),(B,C)
EQUIVALENCE (A,B,C)
7-13
SPECIFICATION AND DATA STATEMENTS
The following EQUIVALENCE statement makes the first character of the
character variables KEY and STAR share the same storage location. The
character variable STAR is equivalent to the substring KEY (1:10):
CHARACTER KEY*16, STAR*10
EQUIVALENCE (KEY,STAR)
You can equivalence variables of different numeric data types.
Character variables must not be equivalenced to numeric variables.
For example, you can equivalence a real variable equivalent to a
complex variable. In this case, since each complex variable occupies
two words of storage, and each single-precision variable occupies one
word of storage, if you equivalence a real and a complex variable, the
real variable shares storage with the real part of the complex
variable. Figure 7-1 depicts the shared storage when a complex
variable is equivalenced with a real variable.
Figure 7-1: Shared Storage using EQUIVALENCE Statement
The EQUIVALENCE statement does not imply (or perform) any type
conversions. If you equivalence a real variable and an integer
variable, the data within the equivalenced location will be treated as
a real or integer number, depending on whether it is referenced by the
real or integer variable.
If you equivalence a real variable with a double-precision variable,
the data in the high-order word of the double-precision variable will
be used by the real variable. For positive D-floating
double-precision numbers (see Section 3.4), the high-order word is in
the same format as a single-precision number.
For G-floating double-precision numbers (KL model B only - see Section
7-14
SPECIFICATION AND DATA STATEMENTS
3.4), the high-order word is not in the format of a single-precision
number. Thus, equivalencing a real variable and a G-floating
double-precision variable will produce incorrect results.
Equivalencing a negative D-floating number and a real variable may not
produce correct results either, for example the number:
577000000000 000000000001 (the negative of 200777777777
777777777777, almost 1.0)
does not have a valid single-precision number in its high-order word.
If you equivalence an array and a variable, the array does not assume
any of the properties of the variable, and the variable does not
assume any of the properties of the array.
When you use an array element in EQUIVALENCE statements, it must have
either as many subscripts as dimensions of the array, or only one
subscript. In either case, the subscripts must be integer constants.
Note that the single subscript case treats the array as a
one-dimensional array of the given type.
The following example shows the effect of equivalencing a
1-dimensional and a 2-dimensional array:
DIMENSION A(3,2),B(6)
EQUIVALENCE (A(1,1),B(1))
or
EQUIVALENCE (A(1),B(1))
In this example, each array element of array A shares the same storage
area with an element of array B:
A(1,1) B(1)
A(2,1) B(2)
A(3,1) B(3)
A(1,2) B(4)
A(2,2) B(5)
A(3,2) B(6)
Specifying an array name without subscripts in an EQUIVALENCE
statement is the same as specifying the first element of the array.
When you make one character substring equivalent to another character
substring, the EQUIVALENCE statement also sets equivalences between
the other corresponding characters in the character strings, for
example,
CHARACTER NAME*16, ID*9
EQUIVALENCE (NAME(10:13), ID(2:5))
As a result of these statements, the character variables NAME and ID
7-15
SPECIFICATION AND DATA STATEMENTS
share space as illustrated in Figure 7-2.
Figure 7-2: Equivalence of Substrings
7-16
SPECIFICATION AND DATA STATEMENTS
The following statement also aligns the variables as shown in Figure
7-2:
EQUIVALENCE (NAME(9:9),ID(1:1))
If the character substring references are array elements, the
EQUIVALENCE statement sets equivalences between the other
corresponding characters in the complete arrays.
Character elements of arrays can overlap at any character position,
for example:
CHARACTER FIELDS(6)*4, STAR(5)*5
EQUIVALENCE (FIELDS(1) (2:4), STAR(2) (3:5))
As a result of these statements, the character arrays FIELDS and STAR
share storage space as shown in Figure 7-3.
7-17
SPECIFICATION AND DATA STATEMENTS
Figure 7-3: Equivalence of Character Arrays
7-18
SPECIFICATION AND DATA STATEMENTS
General EQUIVALENCE Restrictions:
1. You cannot cause two different elements of an array to become
equivalenced to each other. Thus, the following statement
sequence is prohibited because it specifies the same storage
location (B) for A(1) and A(2):
DIMENSION A(2)
EQUIVALENCE (A(1),B),(A(2),B)
2. An EQUIVALENCE statement must not specify that two
consecutive locations are nonconsecutive. For example, the
following statement sequence is prohibited because B(1) takes
two storage locations, the second of which would make A(2)
nonconsecutive to A(1):
INTEGER A(2)
DOUBLE PRECISION B(2)
EQUIVALENCE (A(1),B(1)), (A(2),B(2))
3. An EQUIVALENCE statement in a SUBROUTINE or FUNCTION
subprogram must not refer to an argument of the subprogram.
For example, the following statement sequence is prohibited:
SUBROUTINE A(B,C)
EQUIVALENCE (B,X)
4. You cannot cause two different substrings of the same
character variables or arrays to become equivalenced to each
other. For example, the following statement sequence is
prohibited because it specifies the same substring B(1:3) for
A(1:3) and A(2:4):
CHARACTER A(3)*4,B*4
EQUIVALENCE (A(1)(1:3),B(1:3)), (A(1)(2:4),B(1:3))
5. You also cannot use the EQUIVALENCE statement to assign
memory locations in a way that is inconsistent with the
normal linear storage of character variables and arrays. For
example, the following statement sequence is prohibited
because it would require the character variable B(2:2) to be
equivalent to both A(1)(2:2) and A(1)(1:1):
CHARACTER A(2)*10,B*10
EQUIVALENCE (A(1)(1:3),B(1:3)), (A(1)(4:6),B(5:7))
Restrictions on EQUIVALENCE and COMMON:
1. You cannot use the EQUIVALENCE statement to equivalence two
elements in different common blocks. Thus, the following
statement sequence is prohibited:
7-19
SPECIFICATION AND DATA STATEMENTS
COMMON /BLOCK1/A,B,F/BLOCK2/C,D,E
EQUIVALENCE (A,C)
2. You cannot set two quantities declared in a COMMON block to
be equivalent to one another. Thus, the following statement
sequence is prohibited:
COMMON A,B,C
EQUIVALENCE (A,C)
3. Quantities placed in a common area by means of an EQUIVALENCE
statement are permitted to extend the end of the common area
forward. For example, the statements:
COMMON/R/X,Y,Z
DIMENSION A(4)
EQUIVALENCE (A,Y)
cause the common block R to extend from Z to A(4) arranged as
shown in Figure 7-4.
Figure 7-4: Valid Equivalencing
4. You cannot use EQUIVALENCE statements that cause the start of
a common block to be extended backwards. For example, the
invalid sequence:
COMMON/R/X,Y,Z
DIMENSION A(4)
EQUIVALENCE(X,A(3))
would require A(1) and A(2) to extend the starting location
7-20
SPECIFICATION AND DATA STATEMENTS
of block R in a backwards direction as illustrated in Figure
7-5.
Figure 7-5: Invalid Equivalencing
7-21
SPECIFICATION AND DATA STATEMENTS
7.5.1 EQUIVALENCE and Extended Addressing
When extended addressing is in effect, and an EQUIVALENCE statement
causes a variable to be in COMMON, that variable resides in the same
psect as the rest of the COMMON block.
For variables not in COMMON, if you equivalence a large variable
(default 10,000 or more words) with other variables (including
scalars), all these variables will reside in the large data psect.
For example,
REAL A(20000),X
EQUIVALENCE (A(1),X)
causes variable X to be placed in the large data psect, since it is
equivalenced with a large array.
Conversely, if each equivalence variable is small (default less than
10,000 words), they will reside in the small data psect, even if the
total size of the equivalence class is over the small variable limit.
For example,
REAL A(8000),B(8000)
EQUIVALENCE (A(8000), B(1))
The arrays will reside in the small data psect, because each one is
smaller than 10,000 words.
See Sections 15.4.11 and 16.5 for more information on extended
addressing.
7.6 EXTERNAL STATEMENT
Any user subprogram name to be used as an argument to another
subprogram must appear in an EXTERNAL statement in the calling
subprogram. The EXTERNAL statement declares names to be subprogram
names to distinguish them from other variable or array names.
The subprograms mentioned in the EXTERNAL statement cannot be FORTRAN
intrinsic functions; they can be only user-supplied functions,
subroutines, or block data subprograms. (The INTRINSIC statement
discussed in Section 7.7 allows intrinsic function names to be used as
arguments.) The EXTERNAL statement has the following form:
EXTERNAL proc[,proc...]
where:
proc is the symbolic name of a user-supplied subprogram, the
name of a dummy argument associated with the name of a
7-22
SPECIFICATION AND DATA STATEMENTS
subprogram, or a block data subprogram.
The EXTERNAL statement declares each symbolic name included in it to
be the name of an external procedure, even if a name is the same as
that of an intrinsic function. For example, if SIN is specified in an
EXTERNAL statement (EXTERNAL SIN), all subsequent references to SIN
are to a user-supplied function name SIN, not to the intrinsic
function of the same name.
The name specified in an EXTERNAL statement can be used as an actual
argument to a subprogram, which can then use the corresponding dummy
argument in a function reference or a CALL statement.
NOTE
Note that a complete function reference used as an
argument, for instance, FUNC(B) in CALL SUBR
(A(FUNC(B),C)), represents a value, not a subprogram.
A complete function reference is not, therefore,
defined in an EXTERNAL statement.
The interpretation of the EXTERNAL statement described above is
different from that of earlier versions of FORTRAN-10/20. If the
/NOF77 compiler switch is specified (see Sections 16.1.3 and 16.2.3),
the subprogram names can be intrinsic functions.
For compatibility with previous versions of FORTRAN-10/20, the names
of external subprograms can be preceded by an asterisk (*) or an
ampersand (&) within an EXTERNAL statement. For example,
EXTERNAL *SIN, &COS
declares SIN and COS to be user subprograms. (If a prefixed name is
not an intrinsic function, then the prefix is ignored.)
Note that specifying an intrinsic function in an EXTERNAL statement
without a prefix (that is, EXTERNAL SIN) has no effect upon the usage
of the function name outside of actual argument lists. If the name
has generic properties, they are retained outside the actual argument
list. (The name has no generic properties within an argument list.)
The names declared in a program EXTERNAL statement are reserved
throughout the compilation of the program, and cannot be used in any
declarator statement other than a type statement.
7.7 INTRINSIC STATEMENT
The INTRINSIC statement allows you to use intrinsic function names as
arguments to subprograms. See Section 13.1 for further information on
intrinsic functions.
7-23
SPECIFICATION AND DATA STATEMENTS
The INTRINSIC statement has the form:
INTRINSIC fun[,fun]...
where:
fun is the symbolic name of an intrinsic function.
The INTRINSIC statement declares each symbolic name included in it to
be the name of an intrinsic procedure. This name can then be used as
an actual argument to a subprogram, which can use the corresponding
dummy argument in a function reference or a CALL statement.
The appearance of a generic function name in an INTRINSIC statement
does not cause that name to lose its generic property.
NOTE
You cannot use a generic-only name in an INTRINSIC
statement. The generic name must be the same as an
instrinic function name. For example,
INTRINSIC LOG
is illegal because there is no function named 'LOG'.
LOG is the generic name that selects between functions
such as ALOG, DLOG, or CLOG.
Only one appearance of a symbolic name is permitted in all of the
INTRINSIC statements of a program unit. Also, a symbolic name must
not appear in both an EXTERNAL and an INTRINSIC statement in a program
unit.
An example of the use of the EXTERNAL and INTRINSIC statements
follows:
Main Program
.
.
.
EXTERNAL CTN
INTRINSIC SIN, COS
.
.
.
CALL TRIG(ANGLE,SIN,SINE)
.
.
.
CALL TRIG(ANGLE,COS,COSINE)
7-24
SPECIFICATION AND DATA STATEMENTS
.
.
.
CALL TRIG(ANGLE,CTN,COTANT)
.
.
.
Subprograms
SUBROUTINE TRIG(X,F,Y)
Y = F(X)
RETURN
END
FUNCTION CTN(X)
CTN = COS(X)/SIN(X)
RETURN
END
In this example, when TRIG is called with a second argument of SIN or
COS, the function reference F(X) references the math library functions
SIN and COS; but when TRIG is called with a second argument of CTN,
F(X) references the user function CTN.
7.8 PARAMETER STATEMENT
The PARAMETER statement allows you to define constants symbolically
during compilation.
The general form of the PARAMETER Statement is:
PARAMETER (p=c[,p=c]...)
where:
p is a symbolic name.
c is a constant expression (except for expressions involving
multiplication, division, or exponentiation of complex
numbers). (See Chapter 3 for a description of FORTRAN
constants.)
The constant acquires the same data type as the symbolic name. If the
symbolic name is of type integer, real, double precision, or complex,
the corresponding expression (c) must be an arithmetic constant
expression (see Section 5.1.2). If the symbolic name is of type
character or logical, the corresponding expression (c) must be a
character constant expression (see Section 5.2.1) or a logical
7-25
SPECIFICATION AND DATA STATEMENTS
constant expression (see Section 5.3.1), respectively.
The data type of a symbolic name defined to be a constant is specified
by a type-statement or IMPLICIT statement preceding the defining
PARAMETER statement. Also, if the length specified for the symbolic
name of a character constant is not the default length of one, its
length must be specified by a type-statement or IMPLICIT statement
preceding the symbolic name of the constant.
NOTE
The form and the interpretation to the PARAMETER
statement described above are different from those of
the PARAMETER statement provided in earlier versions
of FORTRAN-10/20. The earlier version is described
below. This form and interpretation can still be
used, however a warning message will be issued. This
form of the PARAMETER statement is:
PARAMETER p=c[,p=c...]
The symbolic name acquires the same data type as the
constant.
During compilation, the symbolic names are replaced by their
associated constants, provided the following rules are observed:
1. Symbolic names may appear only where FORTRAN constants are
acceptable.
2. Symbolic name references must appear after the PARAMETER
statement definition.
3. Symbolic names must be unique with respect to all other names
in the program unit.
4. Symbolic names must not be redefined in subsequent PARAMETER
statements.
5. Symbolic names must not be used as part of another constant,
such as within a character constant or as the count for a
Hollerith constant.
6. Symbolic names must not be used as part of a format
specification.
7.9 DATA STATEMENT
DATA statements are used to supply the initial values of variables,
7-26
SPECIFICATION AND DATA STATEMENTS
arrays, array elements, substrings, and COMMON areas.
The form of the data statement is:
DATA nlist/clist/ [[,]nlist/clist/]...
where:
nlist identifies a set of items to be initialized.
clist contains the set of values to be assigned the items in
nlist.
For example, the statement:
DATA IA/5/,IB/10/,IC/15/
initializes variable IA to the value 5, variable IB to the value 10,
and variable IC to the value 15. The number of storage locations you
specify in the list of variables must be equal to the number of
storage locations you specify in its associated list of values. If
not, a warning message is output.
When the value list specifies more storage locations than the variable
list, the excess values are ignored. When the value list specifies
fewer storage locations than the variable list, the excess variables
are not initialized.
The nlist portion of each nlist/clist/ set can contain the names of
one or more variables, array names, array elements, character
substring names, or labeled COMMON variables. You may specify an
entire array (unsubscripted array name) or a portion of an array in a
DATA statement nlist as an implied DO loop construct. (See Section
10.4.9.2 for a description of implied DO loops.)
The form of an implied-DO list in a DATA statement is:
(dlist,i=n1,n2[,n3])
where:
dlist is a list of array element names, character substring
names, or implied-DO lists.
i is the name of an integer variable, called the loop
index variable.
n1,n2,n3 are integer expressions that can contain integer
constants and loop index variables.
For example, the statement:
7-27
SPECIFICATION AND DATA STATEMENTS
DATA (NARY(I),I=1,5)/1,2,3,4,5/
initializes the first five elements of array NARY as NARY(1)=1,
NARY(2)=2, NARY(3)=3, NARY(4)=4, and NARY(5)=5.
When you use an implied DO loop in a DATA statement, the loop index
variable must be of type INTEGER, and the Initial, Terminal, and
Increment parameters of the loop must be of type INTEGER.
In a DATA statement, references to an array element or substring must
be integer expressions in which all terms are either integer constants
or indices of embracing implied DO loops. These types of integer
expressions can include the exponentiation operator.
The clist portion of each nlist/clist/ set can contain one or more
numeric, logical, Hollerith, octal, hexadecimal, or character
constants. You may specify literal data as either a Hollerith
specification, for example, 5HABCDE, or a string enclosed in single
quotes, for example, 'Abcde'. Each ASCII data item is stored
left-justified and is padded with blanks if necessary.
When you assign the same value to more than one item in nlist, a
repeat specification may be used. The repeat specification has the
form:
n*d
where:
n is an integer that specifies how many times the value d is
to be used. For example, a clist specification of /3*20/
specifies that the value 20 is to be assigned to the first
three items named in the preceding list. The statement:
DATA M,N,L/3*20/
assigns the value 20 to the variables M, N, and L.
When the specified data type is not the same as that of the variable
to which it is assigned, FORTRAN converts the data item to the type of
the variable. The type conversion is performed using the rules given
for type conversion in arithmetic assignments. (See Table 8-1.)
Octal, logical, Hollerith, hexadecimal, and character constants are
not converted.
Sample Statement Result
DATA PRINT,I,O/'TEST',30,"77/,(TAB(J),J=1,30)/30*5/ The first 30
elements of
array TAB are
initialized to
5.0.
7-28
SPECIFICATION AND DATA STATEMENTS
DATA((A(I,J),I=1,5),J=1,6)/30*1.0/ No conversion
required.
DATA((A(I,J),I=5,10),J=6,15)/60*2.0/ No conversion
required.
When character variables are initialized, length conversions are made.
The conversion is based on the following rules:
1. If the constant contains fewer characters than the length of
the element in nlist, the rightmost character positions of
the element are initialized with spaces.
2. If the constant contains more characters than the length of
the element in nlist, the character constant is truncated to
the right.
Character constants and Hollerith constants can also be used to
initialize numeric variables. The character string is stored left
justified in the numeric variable. When the character string
specified is longer than one numeric variable can hold, the string is
stored left justified across as many variables as are needed to hold
it. If necessary, the last variable used is padded with blanks up to
its right boundary.
For character variables, each variable or array element must have
exactly one character constant in the data list.
For example, assuming that X, Y, and Z are single-precision, the
statement:
DATA X,Y,Z/'abcdefghijkl'/
causes:
X to be initialized to 'abcde'
Y to be initialized to 'fghij'
Z to be initialized to 'klbbb'
When a character string is to be stored in double-precision and/or
complex variables, and the specified string is only one word long, the
second word of the variable is padded with blanks.
For example, assuming that the variable C is complex, the statement:
DATA C/'ABCDE','FGHIJ'/
causes the first word of C to be initialized to 'ABCDE' and its second
word to be initialized to 'bbbbb'. The string 'FGHIJ' is ignored.
The first word contains the real part of the complex variable; the
second word contains the imaginary part.
7-29
SPECIFICATION AND DATA STATEMENTS
In addition, the following two forms of bit data constants are allowed
in DATA statements:
O'di...dn'
Z'hi...hn'
where di are octal digits and hi are hexadecimal digits with A-F
representing the decimal equivalent of 10-15. These constants are
right-justified. Note that you can also use the double quote (") form
of octal constants as described in Section 3.7.
7.10 SAVE STATEMENT
The SAVE statement retains the values stored in a variable, array, or
common block after execution of a RETURN or END statement in a
subprogram.
The SAVE statement has the following form:
SAVE [a[,a]...]
where:
a is a named common block name (preceded and followed by a
slash), a variable name, or an array name.
NOTE
Ordinarily, the values of all variables are retained
after execution of a RETURN or END statement.
However, when overlays are used, the SAVE statement
must be used to ensure retention of values.
An entity specified by a SAVE statement within a program unit does not
become undefined upon execution of a RETURN or END statement in that
unit. If the entity is in a common block, however, it may be
redefined in another program unit that references that common.
Procedure names, the names of variables and arrays in a common block,
and dummy argument names cannot be used in a SAVE statement.
A SAVE statement that does not explicitly contain a list is treated as
though it contained a list of all allowable items in the program unit
that contains the SAVE statement.
If a particular common block name is specified by a SAVE statement in
a subprogram of an executable program, it must be specified by a SAVE
statement in every subprogram in which that common block appears.
7-30
SPECIFICATION AND DATA STATEMENTS
NOTE
It is not necessary to use the SAVE statement to
retain the value of a blank common block; the
definition status of blank common is automatically
retained after a RETURN or END statement.
Also, when the SAVE statement is used, it is not
necessary to specify the LINK switch /OVERLAY:WRITABLE
when loading a program.
7-31
8-1
CHAPTER 8
ASSIGNMENT STATEMENTS
Assignment statements assign values to variables, array elements, or
character substrings. There are four kinds of assignment statements:
1. Arithmetic assignment statements (see Section 8.1)
2. Logical assignment statements (see Section 8.2)
3. Statement Label assignment (ASSIGN) statements (see Section
8.3)
4. Character assignment statements (see Section 8.4)
8.1 ARITHMETIC ASSIGNMENT STATEMENT
You use statements of this type to assign numeric values to numeric
variables or array elements. Arithmetic assignment statements have
the form:
v=e
where:
v is the name of the numeric variable or array element that is
to receive the specified value.
e is an arithmetic expression.
In assignment statements, the equal symbol (=) does not imply equality
as it would in algebraic expressions; it implies replacement. For
example, the expression v=e is interpreted as "the contents of the
location identified as v are to be replaced by the value of expression
e; the previous contents of v are lost."
When the type of the specified variable or array element name differs
8-1
ASSIGNMENT STATEMENTS
from that of its assigned value, FORTRAN converts the value to the
type of its assigned variable or array element. Table 8-1 describes
the type conversion operations performed by FORTRAN for each possible
combination of variable and value types.
8-2
ASSIGNMENT STATEMENTS
Table 8-1: Rules for Conversion in Mixed-Mode Assignments
Expression Variable Type (v)
Type (e)
REAL INTEGER COMPLEX DOUBLE- LOGICAL CHARACTER
PRECISION
Real D C R,I H,L D X
Integer F D R,F,I M D X
Complex R C,R D R,L R X
Double- O N H,I D H X
precision
Logical D D R,I H,L D X
Octal D D R,I H,L D X
Hollerith D% D% D& D& D% X
Character X X X X X D
Double- H H D# D H X
Octal*
Legend
D = Direct replacement
C = Conversion from real to integer with truncation, overflow is
possible
F = Conversion from integer to real with rounding
R = Real part only
I = Set imaginary part to 0
H = High-order only
L = Set low-order part to 0
M = Convert with no truncation and no rounding
N = Convert with rounding; truncation can occur and overflow is
8-3
ASSIGNMENT STATEMENTS
possible
O = Round to one word of precision, overflow is possible
X = Not allowed
Notes
* Octal numbers with 13 to 24 digits are termed double-octal.
Double-octals require two storage locations. They are stored
right-justified and are padded with zeros to fill the
locations.
& Use the first two words of the Hollerith constant. If the
Hollerith constant is only one word long, the second word is
padded with blanks.
% Use the first word of the Hollerith constant.
# To convert double-octal numbers to complex, the low-order octal
digits are assumed to be the imaginary part, and the high-order
digits are assumed to be the real part of the complex value.
8.2 LOGICAL ASSIGNMENT STATEMENTS
Statements of this type are used to assign values to variables and
array elements of type logical. Logical assignment statements have
the following form:
v=e
where:
v is the name of a variable or array element
e is a logical expression
For example, assuming that the variables L, F, M, and G are of type
logical, the following statements are valid:
Sample Statement Results
L=.TRUE. The contents of L are replaced by
logical truth.
F=.NOT.G The contents of F are replaced by
the complement of the contents of
G.
M=A.GT.T
or
8-4
ASSIGNMENT STATEMENTS
M=A>T If A is greater than T, the
contents of M are replaced by
logical truth; if A is less than or
equal to T, the contents of M are
replaced by logical false. This
can also be read: If A is greater
than T, then M is true, otherwise,
M is false.
L=((I.GT.H).AND.(J<=K)) The contents of L are replaced by
either the true or false resultant
of the expression.
8.3 ASSIGN (STATEMENT LABEL) ASSIGNMENT STATEMENT
The ASSIGN statement is used to assign a statement label constant (a 1
to 5 digit statement number) to a variable name. The form of the
ASSIGN statement is:
ASSIGN s TO i
where:
s is a statement number in the current program unit.
i is a variable name.
For example, the statement:
ASSIGN 2000 TO LABEL
specifies that the variable LABEL references the statement number
2000.
With the exception of complex, double-precision, or character, you can
use any type of variable in an ASSIGN statement.
Use the ASSIGN statement in conjunction with assigned GO TO control
statements (see Chapter 9), or as a format identifier in an I/O
statement (See Chapter 10). The ASSIGN statement sets up statement
label variables that are then referenced in subsequent GO TO control
statements, or in format specifiers in I/O statements. The following
sequence illustrates the use of the ASSIGN statement:
555 TAX=(A+B+C)*.05
.
.
.
ASSIGN 555 TO LABEL
.
8-5
ASSIGNMENT STATEMENTS
.
.
GO TO LABEL
8.4 CHARACTER ASSIGNMENT STATEMENT
The character assignment statement assigns the value of the character
expression on the right of the equal sign to the character variable,
array element, or substring on the left of the equal sign.
The form of the character assignment statement is:
v=e
where:
v is a character variable, array element, or substring.
e is a character expression.
If the length of the expression on the right side of the assignment is
greater than the length of the variable on the left side, the
character expression is truncated on the right.
If the length of the expression on the right side of the assignment is
less than the length of the variable on the left side, the character
expression is filled on the right with blanks.
FORTRAN-10/20 allows overlap between the character expression and the
character variable, array element, or substring. (That is, the
character positions defined in the character variable, array element,
or substring can be referenced in the character expression.) For
example, the following assignments are allowed:
CHARACTER *4 A,B
DATA A/'abcd'/,B/'efgh'/
A(1:3) = A(2:4)
B(2:4) = B(1:3)
After the above assignment statements, A is 'bcdd', and B is 'eefg'.
The expression must be of character data type. You cannot assign a
numeric value to a character variable, array element, or substring.
Note that assigning a value to a character substring does not affect
character positions in the character variable or array element not
included in the substring. If a character position outside of the
substring has a value previously assigned, it remains unchanged. If
the character position is undefined, it remains undefined.
8-6
ASSIGNMENT STATEMENTS
Examples of valid and invalid character assignment statements follow.
All variables and arrays in the examples are assumed to be of
character data type.
Valid
FILE = 'PROG2'
REVOL(1) = 'MAR'//'CIA'
LOCA(3:8) = 'PLANT5'
TEXT(I,J+1)(2:N-1) = NAME//X
Invalid
'ABC' = CHARS (the left side must be a character variable,
array element, or substring reference)
CHARS = 25 (expression on the right must be of character
data type)
8-7
9-1
CHAPTER 9
CONTROL STATEMENTS
FORTRAN object programs normally execute statement by statement in the
order in which they were presented to the compiler. The following
control statements, however, enable you to alter the normal sequence
of statement execution:
1. CALL (Section 13.4.2.2)
2. CONTINUE (Section 9.5)
3. DO (Section 9.3)
4. DO WHILE (Section 9.3.2)
5. ELSE (Section 9.2.4)
6. ELSE IF THEN (Section 9.2.4)
7. END (Section 9.8)
8. END DO (Section 9.4)
9. END IF (Section 9.2.4)
10. GO TO (Section 9.1)
11. IF (Section 9.2)
12. IF THEN (Section 9.2.4)
13. STOP (Section 9.6)
14. PAUSE (Section 9.7)
15. RETURN (Section 13.4.4)
The CALL and RETURN statements are described in Sections 13.4.2.2 and
13.4.4, respectively. The remaining statements are described in this
9-1
CONTROL STATEMENTS
chapter.
9.1 GO TO STATEMENTS
A GO TO statement causes the statement that it identifies to be
executed next, regardless of its position within the program.
There are three kinds of GO TO statements: Unconditional (see Section
9.1.1), Computed (see Section 9.1.2), and Assigned (see Section
9.1.3).
9.1.1 Unconditional GO TO Statements
An unconditional GO TO statement transfers program control to the
specified statement label.
The form of the unconditional GO TO statement is:
GO TO s
where:
s is a statement label of an executable statement.
For example:
GO TO 300
You can position an unconditional GO TO statement anywhere in the
source program, except as the terminating statement of a DO loop.
9.1.2 Computed GO TO Statements
The form of a computed GO TO statement is:
GO TO (s [,s]...)[,] e
where:
(s[,s]...) is a list of statement labels.
e is an integer expression.
You may include any number of statement labels in the list of a
computed GO TO statement. However, each statement label must appear
within the program unit containing the GO TO statement. The same
9-2
CONTROL STATEMENTS
statement label can appear more than once in the list.
The value of the expression must be an integer value (it will be
truncated if necessary) that is greater than 0 and less than or equal
to the number of statement labels given in the list. If the value of
the expression is not within this range, the next sequential statement
is executed.
When a computed GO TO statement is executed, the value of the
expression is computed first. The value of the expression specifies
the position of the label (within the given list of statement labels)
that identifies the statement to be executed next. For example, in
the statement sequence:
GO TO (20, 10, 5)K
CALL XRANGE(K)
the variable K acts as a switch, causing a transfer to statement 20 if
K=1, to statement 10 if K=2, or to statement 5 if K=3. The subprogram
XRANGE is called if K is less than 1 or greater than 3.
9.1.3 Assigned GO TO Statements
The form of an assigned GO TO statement is:
GO TO i [[,] (s [,s]...)]
where:
i is a variable name and the optional parenthesized list is a
list of statement labels. The statement labels specified
must appear within the program unit containing the GO TO
statement.
Assigned GO TO statements must be logically preceded by an ASSIGN
statement (see Section 8.3) that assigns a statement label value to
the variable i. The assigned GO TO statement transfers program
control to the label that has been ASSIGNed.
The statement label value assigned must appear within the same program
unit as the GO TO statement that uses that value. In statements with
a specified list, if i is not assigned one of the statement label
values given in the list, the next sequential statement is executed.
Examples:
ASSIGN 300 TO STAT1
GO TO STAT1
GO TO STAT1,(177,300,777)
9-3
CONTROL STATEMENTS
9.2 IF STATEMENTS
There are four kinds of IF statements: arithmetic (see Section
9.2.1), logical (see Section 9.2.2), logical two-branch (see Section
9.2.3), and block IF (see Section 9.2.4).
9.2.1 Arithmetic IF Statements
The form of the arithmetic IF statement is:
IF (e) s1, s2, s3
where:
e is an expression enclosed within parentheses and s1, s2, and
s3 are statement labels of three executable statements
appearing within the program unit containing the IF
statement. The expression e must not be of type complex.
The same statement label can appear more than once in the IF
statement.
This type of IF statement transfers control of the program to one of
the given statements according to the computed value of the given
expression. If the value of the expression is:
1. Less than 0, control is transferred to the statement
identified by label s1.
2. Equal to 0, control is transferred to the statement
identified by label s2.
3. Greater than 0, control is transferred to the statement
identified by label s3.
Examples:
IF(ETA)4, 7, 12 Transfers control to statement 4 if
ETA is negative, to statement 7 if
ETA is 0, and to statement 12 if
ETA is greater than 0.
IF(KAPPA-L(10))20, 14, 14 Transfers control to statement 20
if KAPPA is less than the 10th
element of array L and to statement
14 if KAPPA is greater than or
equal to the 10th element of array
L.
9-4
CONTROL STATEMENTS
9.2.2 Logical IF Statements
The form of the logical IF statement is:
IF (e) st
where:
e is any expression. The expression must not be of type
complex.
st is an executable statement.
If the value of the expression is true (negative), control is
transferred to the executable statement within the IF statement. If
the value of the expression is false (nonnegative), control is
transferred to the next sequential executable statement. The
statement you give in a logical IF statement may be any executable
statement except a DO statement, an END statement, or another logical
IF statement.
Examples:
IF(T.OR.S) X=Y+1 Performs an arithmetic
assignment operation if the
result of the IF is true.
IF(Z.GT.X(K)) CALL SWITCH(S,Y) Performs a subroutine call if
the result of the IF is true.
IF(K.EQ.INDEX) GO TO 15 Performs an unconditional
transfer if the result of the
IF is true.
9.2.3 Logical Two-Branch IF Statements
The format of a logical two-branch IF statement is:
IF (e) s1, s2
where:
e is any expression, and s1 and s2 are statement labels
appearing within the program unit containing the IF
statement. The expression must not be of type complex.
Logical two-branch IF statements transfer control to either statement
s1 or s2, depending on the computed value of the given expression. If
the value of the given logical expression is true (negative), control
is transferred to statement s1. If the value of the expression is
9-5
CONTROL STATEMENTS
false (nonnegative), control is transferred to statement s2.
Examples:
IF (LOG1) 10,20 Transfers control to statement 10
if LOG1 is true (negative);
otherwise transfers control to
statement 20.
IF (A.LT.B.AND.A.LT.C) 31,32 Transfers control to statement 31
if A is less than both B and C;
transfers control to statement 32
if A is greater than or equal to
either B or C.
9.2.4 Block IF Statements
Block IF statements conditionally execute blocks (or groups) of
statements. The four block IF statements are:
o IF THEN
o ELSE IF THEN
o ELSE
o END IF
These statements are used in block IF constructs. The block IF
construct has the following form, where the ELSE IF THEN and ELSE
statements are optional:
IF (e) THEN
block
ELSE IF (e) THEN
block
.
.
.
ELSE
block
END IF
where:
e is a logical expression.
9-6
CONTROL STATEMENTS
block is a sequence of zero or more complete FORTRAN statements.
This sequence is called a statement block.
Each block IF statement, except the END IF statement, has an
associated statement block. The statement block consists of all the
statements following the block IF statement up to (but not including)
the next block IF statement in the block IF construct. The statement
block is conditionally executed based on the values of logical
expressions in the preceding block IF statements. A statement block
can be empty.
The IF THEN statement begins a block IF construct. The block
following it is executed if the value of the logical expression in the
IF THEN statement is true. The first statement of the block cannot
directly follow the THEN on the same line. For example, the following
is illegal:
IF (T.LT.X) THEN T = X
The correct form is:
IF (T.LT.X) THEN
T = X
The ELSE statement specifies a statement block to be executed if no
preceding statement block in the block IF construct was executed. The
ELSE statement is optional.
The ELSE IF THEN statement is similar to the ELSE statement, except it
requires an additional condition for execution. The ELSE IF THEN
statement specifies a statement block to be executed if both the value
of the logical expression in the ELSE IF THEN statement is true, and
no preceding statement block in the block IF construct was executed.
A block IF construct can contain any number of ELSE IF THEN
statements. The ELSE IF THEN statement is optional.
The END IF statement terminates the block IF construct.
Figure 9-1 describes the flow of control for four examples of block IF
constructs.
9-7
CONTROL STATEMENTS
Figure 9-1: Examples of Block IF Constructs
After the last statement in a statement block is executed, control
passes to the next executable statement following the END IF
statement. Consequently, at most one statement block in a block IF
construct is executed each time the IF THEN statement is executed.
ELSE IF THEN and ELSE statements can have statement labels, but these
labels cannot be referenced. The END IF statement can have a
statement label to which control can be transferred, but only from
9-8
CONTROL STATEMENTS
within the block IF construct.
Section 9.2.4.1 describes restrictions on statements in a statement
block. Section 9.2.4.2 describes examples of block IF constructs.
Section 9.2.4.3 describes nested block IF constructs.
9.2.4.1 Statement Blocks - A statement block can contain any
executable FORTRAN statement except an END statement (see Section
9.8). You can transfer control out of a statement block, but you
cannot transfer control back into the block. Note that you cannot
transfer control from one statement block into another.
DO loops cannot overlap statement blocks. When a statement block
contains a DO statement (see Section 9.3), it must also contain the DO
loop's terminal statement or END DO statement. Conversely, if a block
IF construct appears within the range of a DO loop, the corresponding
END IF statement must also appear within the range of that DO loop.
9.2.4.2 Block IF Examples - The simplest block IF construct consists
of the IF THEN and END IF statements; this construct conditionally
executes one statement block.
Form Example
IF (e) THEN IF (LOWER.LE.UPPER) THEN
block MIDDLE=(LOWER+UPPER)/2
END IF END IF
The statement block consists of all the statements between the IF THEN
and END IF statements.
The IF THEN statement first evaluates the logical expression (e),
(LOWER.LE.UPPER). If the value of e is true, the statement block is
executed. If the value of e is false, control transfers to the next
executable statement after the END IF statement; the block is not
executed.
The following example contains a block IF construct with an ELSE IF
THEN statement:
Form Example
IF (e1) THEN IF (ITEM.LT.A(MIDDLE)) THEN
block1 UPPER=MIDDLE-1
ELSE IF (e2) THEN ELSE IF (ITEM.GT.A(MIDDLE)) THEN
block2 LOWER=MIDDLE+1
END IF END IF
Block1 consists of all statements between the IF THEN and the ELSE IF
9-9
CONTROL STATEMENTS
THEN statements; block2 consists of all the statements between the
ELSE IF THEN and the END IF statements.
If ITEM is less than A(MIDDLE), block1 is executed.
If ITEM is not less than A(MIDDLE), but ITEM is greater than
A(MIDDLE), block2 is executed.
If ITEM is not less than A(MIDDLE) and ITEM is not greater than
A(MIDDLE), neither block1 nor block2 is executed; control transfers
directly to the next executable statement after the END IF statement.
The following example contains a block IF construct with an ELSE
statement:
Form Example
IF (e) THEN IF (ITEM.GT.A(MIDDLE)) THEN
block1 LOWER=MIDDLE+1
ELSE ELSE
block2 SEARCH=MIDDLE
RETURN
END IF END IF
Block1 consists of all the statements between the IF THEN and the ELSE
statements; block2 consists of all the statements between the ELSE and
the END IF statements.
If ITEM is greater than A(MIDDLE), block1 is executed.
If ITEM is not greater than A(MIDDLE), block2 is executed.
9.2.4.3 Nested Block IF Constructs - A block IF construct can be
included in a statement block of another block IF construct. But the
nested block IF construct must be completely contained within a
statement block; it must not overlap statement blocks.
The following example contains a nested block IF construct.
Form Example
FUNCTION SEARCH(A,N,ITEM)
CHARACTER*(*) A(N),ITEM
INTEGER SEARCH,N,LOWER,MIDDLE,UPPER
LOWER=1
UPPER=N
IF (e) THEN IF(LOWER.LE.UPPER) THEN
MIDDLE=(LOWER+UPPER)/2
9-10
CONTROL STATEMENTS
IF (e) THEN 10 IF (ITEM.LT.A(MIDDLE)) THEN
blocka UPPER=MIDDLE-1
block1 ELSE IF (e) THEN ELSE IF (ITEM.GT.A(MIDDLE)) THEN
blockb LOWER=MIDDLE+1
ELSE ELSE
blockc SEARCH=MIDDLE
RETURN
END IF END IF
GOTO10
END IF END IF
20 SEARCH=0
RETURN
END
If LOWER is less than or equal to UPPER, block1 is executed. Block1
contains a nested block IF construct. If ITEM is less than A(MIDDLE),
blocka is executed. If ITEM is greater than A(MIDDLE) blockb is
executed. If ITEM is equal to A(MIDDLE), blockc is executed.
If LOWER is greater than UPPER, control is transferred to the first
executable statement after the last END IF statement. The nested IF
construct is not executed.
9.3 DO STATEMENT
The two types of DO statements are:
1. Indexed DO (DO statement)
2. Pretested indefinite DO (DO WHILE statement)
The indexed DO statement is described in Section 9.3.1, and the DO
WHILE statement is described in Section 9.3.2.
9.3.1 Indexed DO Statement
DO statements simplify the coding of iterative procedures; that is,
the statements in the DO statement range are executed repeatedly a
specified number of times.
The form of an indexed DO statement is:
9-11
CONTROL STATEMENTS
where:
s Terminal statement label s identifies the last statement of
the DO statement range. The statement must follow the DO
statement in the same program unit. If s is omitted, then
the loop must be terminated by an END DO statement (see
Section 9.4).
The terminal statement can be any executable statement other
than one of the following:
o Unconditional or assigned GO TO statement
o Arithmetic IF or logical two-branch IF statement
o Block IF, ELSE IF, ELSE, or END IF statement
o RETURN statement
o STOP statement
o END statement
o DO statement
If the terminal statement is a logical IF, it can contain any
executable statement except one of the following:
o DO statement
o Block IF, ELSE IF, ELSE, or END IF statement
o END statement
o Another logical IF statement
i Index variable i is an unsubscripted numeric variable whose
value is defined at the start of the DO statement operations.
The index variable must not be of type complex.
9-12
CONTROL STATEMENTS
The index variable is available for use throughout each
execution of the range of the DO statement, but altering its
value within the DO loop does not change the number of times
the DO loop will execute. The DO loop index variable is also
available for use in the program when:
a. Control is transferred outside the range of the DO loop
by a GO TO, IF, or RETURN statement located within the DO
range
b. Control is transferred outside the range of the DO loop
by an I/O statement with either or both the options END=
or ERR= (see Chapter 10)
c. A subprogram is executed from within the DO statement
range having the index variable as an argument or in
COMMON
e1 Initial parameter e1 assigns the index variable i its initial
value. This parameter can be any expression, but cannot be
of type complex.
e2 Terminal parameter e2 provides the value used to determine
how many repetitions of the DO statement range are performed.
This parameter can be any expression, but cannot be of type
complex.
e3 Increment parameter e3 specifies the value to be added to the
initial parameter (e1) on completion of each cycle of the DO
loop. The increment parameter is optional. If e3 and its
preceding comma are omitted, e3 is assumed to be equal to 1.
This parameter can be any expression, but cannot be of type
complex.
9.3.1.1 Executing an Indexed DO Statement - The indexing parameters
e1, e2 or e3 can be any expressions. Their values are calculated only
once, at the start of each DO loop operation, to determine the values
for the initial, terminal, and increment parameters. If necessary,
the initial, terminal, and increment parameters are converted, before
use, to the data type of the index variable.
The number of times that a DO loop will execute, called the iteration
count, is specified by the formula:
MAX(INT((e2-e1+e3)/e3),0)
If the iteration count is less than or equal to zero, the body of the
loop is not executed. The index variable retains its assigned value
(e1).
9-13
CONTROL STATEMENTS
NOTE
The interpretation of the iteration count described
above is different from that of earlier versions of
FORTRAN-10/20. If the /NOF77 compiler switch is
specified (see Sections 16.1.3 or 16.2.3), and the
iteration count is less than or equal to zero, the
body of the loop is executed once.
Since the iteration count is computed at the start of a DO loop
operation, changing the value of the loop index variable within the
loop cannot affect the number of times that the loop is executed.
At the start of a DO loop operation, the index value is set to the
value of the initial parameter (e1); and the iteration count is
established.
9.3.1.2 DO Iteration Control - At the end of each DO loop cycle, the
following steps are executed:
1. The value of the increment parameter (e3) is added to the
index variable.
2. The iteration count is decremented.
3. If the iteration count is greater than zero, control
transfers to the first executable statement after the DO
statement for another iteration of the loop.
4. If the iteration count is less than or equal to zero,
execution of the DO loop terminates.
Exit from a DO loop upon completion of the number of iterations
specified by the loop count is referred to as a normal exit. If no
other DO loop shares the terminal statement, or if this DO loop
statement is outermost, control passes to the first executable
statement after the terminal statement of the DO loop.
The final value of the index variable is the value determined by step
1.
NOTE
The interpretation of the index variable described
above is different from that of earlier versions of
FORTRAN-10/20. If the /NOF77 compiler switch is
specified (see Sections 16.1.3 or 16.2.3), the final
value of the index variable of the DO statement is
undefined after a normal loop exit.
Exit from a DO loop may also be accomplished by a transfer of control
9-14
CONTROL STATEMENTS
by a statement within the DO loop range to a statement outside the
range of the DO statement. This is called an extended range DO loop
(see Section 9.3.5).
When execution of a DO loop terminates, and other DO loops share its
terminal statement, control transfers outward to the next most
enclosing DO loop in the DO nesting structure (see Section 9.3.4).
Examples of DO Iteration Control:
DO 100 I = 1,10
100 J=I
After execution of these statements, I=11 and J=10. (If the /NOF77
switch is specified, I is undefined and J=10).
L=0
DO 200 K = 5,1
200 L=K
After execution of these statements, K=5 and L=0. (If the /NOF77
switch is specified, K is undefined and L=5).
9.3.2 DO WHILE Statement
The DO WHILE statement is similar to the DO statement described in
Section 9.3.1. Instead of executing a fixed number of iterations, the
DO WHILE statement executes for as long as a logical expression
contained in the statement continues to be true.
The form of the DO WHILE statement is:
DO [s[,]] WHILE (e)
where:
s is the label of an executable statement that must physically
follow in the same program unit.
e is a logical expression.
The DO WHILE statement tests the logical expression at the beginning
of each execution of the loop, including the first. If the value of
the expression is true, the statements in the body of the loop are
executed; if the expression is false, control transfers to the
statement following the loop.
If no label appears in a DO WHILE statement, the DO WHILE loop must be
terminated with an END DO statement (see Section 9.4).
The following example demonstrates the use of the DO WHILE statement:
9-15
CONTROL STATEMENTS
CHARACTER*132 LINE
I=1
LINE(132:) = 'X'
DO WHILE (LINE(I:I) .EQ. ' ')
I = I + 1
END DO
9.3.3 The Range of a DO Statement
The range of a DO statement is defined as the series of statements
that follows the DO statement, up to and including the specified
terminal statement or END DO statement.
If another DO statement appears within the range of a DO statement,
the range of that statement must be entirely contained within the
range of the first DO statement. More than one DO statement may have
the same labeled terminal statement but not unlabeled END DO
statement. (See Section 9.3.4, Nested DO Statements.)
If a DO statement appears within an IF block, ELSE IF block, or ELSE
block (see Section 9.2.4), the range of the DO statement must be
contained entirely within that block.
If a block IF statement appears within the range of a DO statement,
the corresponding END IF statement must also appear within the range
of the DO statement.
9.3.4 Nested DO Statements
One or more DO statements can be contained within the range of another
DO statement. This is called nesting. The following rules govern the
nesting of DO statements:
1. The number of nested levels (DO loop within DO loop) is
restricted to 79 DO loops.
2. The range of each nested DO statement must be entirely within
the range of the containing DO statement (such as, they
cannot overlap).
For example:
9-16
CONTROL STATEMENTS
3. More than one DO loop within a nest of labeled DO loops can
end on the same statement. When this occurs, the terminal
statement is considered to belong to the innermost DO
statement that ends on that statement. Only a statement that
occurs within the range of the innermost DO statement can use
the statement label of the shared terminal statement for
transfer of control.
For example:
Although all four DO loops share the same terminal statement,
the terminal statement "belongs" to the innermost DO loop.
4. Nested loops cannot share an unlabeled END DO statement.
Each unlabeled END DO terminates exactly one DO loop.
For example:
9-17
CONTROL STATEMENTS
9.3.5 Extended Range
By following certain rules, it is possible to transfer out of a DO
loop, perform a series of statements elsewhere in the program, and
then transfer back into the DO loop. The statements that are executed
after a transfer out of a DO loop and before a transfer back into the
same DO loop are collectively known as the "extended range." A DO loop
that permits transfer in and out of its range is called an extended
range DO loop.
NOTE
This feature makes the flow of a program difficult to
follow, does not conform to the FORTRAN-77 standard,
and is therefore discouraged.
The following rules govern the use of extended range DO loops:
1. The statement that causes the transfer out of the DO loop
must be contained within the most deeply nested DO (innermost
loop having the same terminal statement). This loop must
also contain the statement to which the extended range
returns.
2. A transfer into the range of a DO statement is permitted only
if the transfer is made from the extended range of that DO
statement.
3. The extended range of a DO statement must not contain another
DO statement.
9-18
CONTROL STATEMENTS
4. The extended range of a DO statement cannot change the index
variable or indexing parameters of the DO statement.
5. You can call a subprogram within an extended range.
The following example illustrates the use of an extended range DO
loop:
DIMENSION TABLE(10,5), VALUE(10)
LOGICAL LOGARR(10)
DO 1000 I= 1, 10 ! An extended range DO loop
IF (LOGARR(I)) GOTO 500 ! Test logical array item
I=K
CALL SUBROT(K) ! Invoke subroutine using
! current index value
DO 200 J= 1, 5 ! Nonextended range loop
TABLE(I,J) = 0
200 CONTINUE
GOTO 2000 ! Extended range invocation
500 VALUE(I) = GETVAL(K) ! Invoke function GETVAL with
! current index
1000 CONTINUE ! Terminal statement for outer
! loop
STOP
2000 TYPE 2100, I ! Extended range starts
2100 FORMAT(' I = ',I2)
LOGARR(I) = .TRUE.
GOTO 500 ! Extended range ends and
! returns
END
9.3.6 Permitted Transfer Operations
The following rules govern the transfer of program control from within
a DO statement range or the ranges of nested DO statements:
1. A transfer out of the range of any DO loop is permitted at
any time. When such a transfer occurs, the value of the
controlling DO loop's index variable is defined as the
current value.
2. A transfer into the range of a DO statement is permitted if
it is made from the extended range of the DO statement.
3. You can call a subprogram from within the range of any:
a. DO loop
b. nested DO loop
c. extended range loop (in which you leave the loop through
a GO TO, execute statements in the extended range, and
9-19
CONTROL STATEMENTS
return to the original loop)
The following examples illustrate the transfer operations permitted
from within the ranges of nested DO statements:
9.4 END DO STATEMENT
The END DO statement terminates the range of a DO or DO WHILE
statement. The END DO statement must be used to terminate a DO block
if the DO or DO WHILE statement defining the block does not contain a
terminal-statement label. The END DO statement may also be used as a
labeled terminal statement if the DO or DO WHILE statement does
contain a terminal-statement label.
The form of the END DO statement is:
END DO
9.5 CONTINUE STATEMENT
The form of the CONTINUE statement is:
CONTINUE
Execution of the CONTINUE statement has no effect. It may be used as
the terminating statement of a DO loop.
In the following example, the labeled CONTINUE statement provides a
legal termination for the range of the DO loop.
DIMENSION STOCK(100)
DO 20 I=1,100
STOCK(I)=0
CALL UPDATE (STOCK(I))
9-20
CONTROL STATEMENTS
IF(STOCK (I).EQ. 0) GO TO 30
20 CONTINUE
STOP
30 TYPE 35
35 FORMAT (' UPDATE ERROR')
END
9.6 STOP STATEMENT
Execution of the STOP statement causes program execution to be
terminated. A descriptive message may optionally be included in the
STOP statement to be output to your terminal immediately before
program execution is terminated.
The form of the STOP statement is:
STOP [n]
where:
n is an optional decimal integer constant of up to 6 digits,
or a character constant. The constant is printed at the
terminal when the STOP statement is executed.
You can have any number of characters in the character
constant. You can use continuation lines to accommodate
large character strings. The constant is printed without
leading zeroes, unless they are specified in the statement.
NOTE
The word STOP is not printed when the STOP statement
is executed unless the word STOP is included in the
statement as a character constant.
The following examples show the results of executing STOP statements
that contain a 6-digit decimal string and a character constant.
PROGRAM TEST
10 STOP 123456
END
EXECUTE STOP1.FOR
FORTRAN: STOP1
TEST
LINK: Loading
[LNKXCT TEST execution]
123456
CPU time 0.1 Elapsed time 0.3
9-21
CONTROL STATEMENTS
PROGRAM TEST
10 STOP 'The program has stopped'
END
EXECUTE STOP2.FOR
FORTRAN: STOP2
TEST
LINK: Loading
[LNKXCT TEST execution]
The program has stopped
CPU time 0.1 Elapsed time 0.3
9.7 PAUSE STATEMENT
Execution of a PAUSE statement suspends the execution of the object
program and gives you the option of continuing execution of the
program, exiting from the program, or beginning a TRACE operation.
The form of the PAUSE statement is:
PAUSE [n]
where:
n is an optional integer constant of up to 6 digits, or a
character constant. The constant is printed at the terminal
when the PAUSE statement is executed.
You can have any number of characters in the character
constant. You can use continuation lines to accommodate
large character strings. The constant is printed without
leading zeros, unless they are specified in the statement.
If execution of the program is resumed after a PAUSE, program control
continues as if a CONTINUE had been executed. Execution of the PAUSE
statement causes the word PAUSE, the optionally specified constant,
and the following prompt to be printed at the terminal:
Type G to Continue, X to Exit, T to Trace
The responses to this prompt are:
G continues program execution at the statement immediately
following the PAUSE statement.
X causes program termination.
T produces a trace back list at the terminal. This list
consists of invoked routine names and locations, plus the
location and module names of the callers of those routines.
Using this information you can track the active path of
9-22
CONTROL STATEMENTS
execution from the main program to the PAUSE trace routine.
(See Section 13.4.1.30 for a detailed description of this
feature.)
PROGRAM PTEST
PAUSE
PAUSE 234
PAUSE 'Character String'
END
EXECUTE PTEST.FOR
FORTRAN: PTEST
PTEST
LINK: Loading
[LNKXCT PTEST execution]
PAUSE
Type G to Continue, X to Exit, T to Trace.
G
PAUSE
234
Type G to Continue, X to Exit, T to Trace.
G
PAUSE
Character String
Type G to Continue, X to Exit, T to Trace.
X
CPU time 0.3 Elapsed time 18.8
9.8 END STATEMENT
This statement signals FORTRAN that the physical end of a program unit
has been reached. END is an executable statement. The general form
of an END statement is:
END
The following rules govern the use of the END statement:
1. This statement must be the last physical statement of a
source program unit (main program or subprogram).
2. When executed in a main program, the END statement has the
effect of a STOP statement; in a subprogram, END has the
effect of a RETURN statement.
3. An END statement may be labeled, but it must not be continued
(that is, it must appear only on an initial line).
9-23
10-1
CHAPTER 10
DATA TRANSFER STATEMENTS
FORTRAN I/O statements are divided into three categories by function,
as follows:
1. Data Transfer Statements - transfer data between memory and
files. The "files" can be devices such as TTY: or MTA:.
Internal files and ENCODE/DECODE statements are used for
memory-to-memory data transfers.
2. File Control Statements - associate and disassociate files
and FORTRAN logical unit numbers, and can specify
characteristics of such an association.
3. Device Control Statements - position files. For example,
using the device control statements you can position magnetic
tape to a particular file or record.
This chapter describes data transfer statements. Chapter 11 describes
file-control and device-control statements.
Table 10-1 lists the three categories of I/O statements, the
statements within each category, and the sections in which each I/O
statement is further described.
10-1
DATA TRANSFER STATEMENTS
Table 10-1: FORTRAN I/O Statement Categories
Table 10-2, on the tab-divider, summarizes all the data transfer
statement forms.
10-2
DATA TRANSFER STATEMENTS
Table 10-2: Summary of Data Transfer Statement Forms
10-3
DATA TRANSFER STATEMENTS
10-4
DATA TRANSFER STATEMENTS
10.1 DATA TRANSFER OPERATIONS
Data transfer statements are used to transfer data between memory and
files or between memory and memory. Data can be transferred
sequentially (sequential access) or randomly (direct access). The
areas in memory from which data is to be taken during output (write)
operations, and into which data is stored during input (read)
operations are specified by:
1. A list in the data transfer statement
2. A list defined by a NAMELIST statement
3. FORMAT specifications referenced in the data transfer
statement
The appearance and arrangement of transferred data can be specified
by:
1. Format specifications located in either a FORMAT statement or
an array (FORMAT-statement I/O)
2. The contents of an I/O list (list-directed I/O)
3. An I/O list defined in a NAMELIST statement (NAMELIST I/O)
These three methods are known collectively as formatted I/O.
In contrast to formatted I/O transfers, FORTRAN has several methods
for transferring data without regard for the type and arrangement of
the data being transferred. These methods are known collectively as
unformatted I/O. Unformatted I/O transfers are particularly useful
when you want the internal (memory) representation of the data being
transferred to be the same as the external (file) representation of
the data.
In addition, unformatted data transfers are generally faster than
formatted transfers. This is because unformatted data transfers do
not convert the data to or from its ASCII representation during the
transfer.
The following sections describe the types of access available, the
types of data transfers available, and the statements used for I/O
transfer operations.
10.2 DATA ACCESS
| There are three forms of access available - sequential, direct, and
| keyed. These forms are described in the following sections.
10-5
DATA TRANSFER STATEMENTS
10.2.1 Sequential Access
If the data access is sequential, the data records are transferred in
a serial fashion to or from the external data file. Each
sequential-access input statement transfers the next record(s) from
the accessed data file, such that data records are transferred in the
same order that they appear in the file.
10.2.2 Direct Access
If the data access is direct, the data records are transferred to or
from a file in any desired order, as specified by a record number in
the data transfer statement. (Section 10.4.4 describes specifying
records in data transfer statements.)
Direct-access transfers, however, can be made only to files residing
on disk that have been previously set up (using an OPEN statement) for
direct access. Direct-access files must contain identically sized
records that are accessed by a record number.
You must use the OPEN statement to establish direct access (see
Section 11.2). Execution of the OPEN statement must precede the first
data transfer statement for the specified logical unit.
|
|
|
| 10.2.3 Keyed Access (TOPS-20 RMS)
|
| If the data access is keyed, the data records are transferred to or
| from an indexed file as specified by character values or integer
| values called keys. The keys are defined as permanent attributes of
| the file when the file is created. Each READ statement contains the
| key that locates the record. The key value in the I/O statement is
| compared with index entries until the record is located.
|
| When you insert a new record, the values contained in the key fields
| of the record determine the record's placement in the file; you do not
| have to indicate a key.
|
| You can use keyed access only for RMS files with an indexed
| organization.
|
| Your program can mix keyed access and sequential access I/O statements
| on the same file. You can use keyed I/O statements to position the
| file to a particular record and then use sequential I/O statements to
| access records with increasing key values in the current
| key-of-reference.
10-6
DATA TRANSFER STATEMENTS
10.3 FORMATTED AND UNFORMATTED DATA TRANSFERS
The term "formatted data transfer" describes an intermediate step that
occurs during a data transfer. This intermediate step, which does not
occur in an unformatted data transfer, converts the data from its
internal (memory) representation to a different external (file)
representation. (Formatted data transfers are described in Section
10.3.1.)
An unformatted data transfer refers to the transfer of data with no
change to the data during the transfer. In an unformatted data
transfer, the internal (memory) representation of the data and the
external (file) representation of the data are the same. (Unformatted
data transfers are described in Section 10.3.2.)
10.3.1 Formatted Data Transfers
In a formatted data transfer, the internal and external format of the
data is controlled during the data transfer in one of three ways:
1. FORMAT-Statement Formatting - The data transfer statement
contains a statement number, a numeric array name, a
character expression, or an integer, real, or logical
variable as a format identifier.
The statement number references a line that contains a FORMAT
statement. The array name references an array that contains
a format specification. The value of the character
expression is a format specification. The integer, real, or
logical variable references a FORMAT statement number that
was assigned with an ASSIGN statement.
In the following example, the data transfer statement
contains a statement number of a FORMAT statement. The
FORMAT statement, in turn, contains edit descriptors that
control the formatting of the data during the transfer:
WRITE (22,101)X,J,Z
101 FORMAT (1X,F10.5,I5,F6.4)
See Section 10.4.5.1 for more information on FORMAT-statement
formatting.
2. List-Directed Formatting - The data transfer statement
contains an asterisk as the format identifier. The asterisk
signifies that the transfer is controlled by the data type of
the variables in the data transfer statement I/O list.
In the following example, the data transfer is controlled by
the I/O list items X, J, and Z:
10-7
DATA TRANSFER STATEMENTS
WRITE (22,*)X,J,Z
In this example, unless the data types of X, J, and Z have
been set explicitly to a type other than the default data
type, the transferred values of X and Z appear in
floating-point form, and the transferred value of J appears
in integer form.
See Section 10.4.5.2 for more information on list-directed
formatting.
3. NAMELIST-Statement Formatting - The data transfer statement
contains a NAMELIST name as the format identifier. This
NAMELIST name associates the data transfer statement with a
NAMELIST I/O list defined in the NAMELIST statement elsewhere
in the same program unit. Elements in the NAMELIST I/O list,
in turn, dictate the formatting of the data during the data
transfer.
In the following example, the data transfer is controlled by
the NAMELIST.
PROGRAM NAMLST
NAMELIST/VAR/X,Y,Z
READ(22,VAR)
WRITE(5,VAR)
END
See Section 10.4.5.3 for more information on NAMELIST-statement
formatting.
10.3.1.1 Internal Files - Internal files provide the capability to
perform formatted data transfers between character variables and the
elements of an I/O list. Their use with formatted sequential READ and
WRITE statements reduces the need to use the ENCODE and DECODE
statements for internal I/O (see Section 10.12).
An internal file consists of a character variable, a character array
element, a character array, or a character substring; a record in an
internal file consists of any of the above except a character array.
If an internal file is a character variable, array element, or
substring, that file comprises a single record whose length is the
same as the length of the variable, array element, or substring.
If an internal file is a character array, that file comprises a
sequence of records, with each record consisting of a single array
element. The sequence of records in an internal file is determined by
the order of subscript progression (see Section 4.3.2). Every record
of the file has the same length, which is the length of an array
10-8
DATA TRANSFER STATEMENTS
element in the array.
The character variable, array element, or substring that is the record
of the internal file becomes defined by writing the record. If the
number of characters written in a record is less than the length of
the record, the remaining portion of the record is left-justified and
filled with blanks.
A record in an internal file can be read only if the character
variable, array element, or substring comprising the record has been
defined (that is, a value has been assigned to the record). Prior to
data transfer, an internal file is always positioned at the beginning
of the first record.
10.3.2 Unformatted Data Transfers
Unformatted data is transferred in two forms on TOPS-20 (BINARY or
IMAGE), and three forms on TOPS-10 (BINARY, IMAGE, or DUMP). In an
explicit OPEN statement (Section 11.2.1), you can specify one of these
| forms as an argument to the MODE specifier. (Section 11.3.24
describes the MODE specifier and its arguments.)
On disk devices and CORE-DUMP tapes, numeric data items are
transferred directly as 36-bit words. Character data items are
transferred as 7-bit bytes. Numeric and character items can be
interpersed in the same I/O list. Numeric data items and, for BINARY
files, record markers (LSCWs) are always word-aligned (see Section
18.4.2). On INDUSTRY tapes, numeric data items should not be used.
Character data items are transferred one character per frame (see
| Section 11.3.37).
10.3.3 Unformatted Data Transfer to ASCII Devices
Unformatted data transfer can be done to and from ASCII devices (such
as line printer, plotter, or terminal). Character data is transferred
exactly as it appears in the input/output list, with no formatting or
carriage control.
The method for transferring numeric data items depends on the device.
For non-terminal devices (such as, line printer or plotter), numeric
data is treated as if it were packed (Hollerith) data,
left-justifited, five characters per word. For the terminal, the data
is treated as if it were right-justified, one character per word.
10-9
DATA TRANSFER STATEMENTS
10.4 DATA TRANSFER STATEMENT FORMS
Table 10-2, on the tab divider, summarizes the forms of all the
FORTRAN data transfer statements. Figure 10-1 shows the three major
components of data transfer statements.
Figure 10-1: Components of Data Transfer Statements
10-10
DATA TRANSFER STATEMENTS
10.4.1 Data Transfer Statement Names
In a data transfer statement, the statement name indicates whether the
operation is an input (read) or output (write) operation.
The FORTRAN data transfer statements described in this chapter are:
1. READ (see Section 10.5)
2. WRITE (see Section 10.6)
3. REREAD (see Section 10.7)
4. ACCEPT (see Section 10.8)
5. TYPE (see Section 10.9)
6. PRINT (see Section 10.10)
7. PUNCH (see Section 10.11)
8. ENCODE (see Section 10.12)
9. DECODE (see Section 10.12)
10. Internal READ (see Section 10.12)
11. Internal WRITE (see Section 10.12)
|
| 12. DELETE (see Section 10.13)
|
| 13. REWRITE (see Section 10.14)
|
| 14. UNLOCK (see Section 10.15)
10.4.2 Data Transfer Control-Information List
A control-information list is included in every data transfer
statement. Each control-information list (including those having an
implicit definition of device) can contain:
1. One unit specifier (see Section 10.4.3)
2. One format specifier (see Section 10.4.5)
3. One record specifier (see Section 10.4.4)
4. One I/O status specifier (see Section 10.4.8)
10-11
DATA TRANSFER STATEMENTS
5. One error specifier (see Section 10.4.7)
6. One end-of-file specifier (see Section 10.4.6)
|
| 7. One key-field-value specifier (see Section 10.4.9)
|
| 8. One key-of-reference specifier (see Section 10.4.10)
The following rules govern the placement and inclusion of items in a
control-information list:
1. If the keyword UNIT= is omitted from the unit specifier, the
unit specifier must be the first item in the
control-information list.
2. If the control-information list contains a format specifier
(FMT= or NML=), the statement is a formatted data transfer
statement. Otherwise, it is an unformatted data transfer
statement. The NML= keyword is used for NAMELIST formatting
only, although you can also use the FMT= keyword for NAMELIST
formatting.
If the keywords FMT= or NML= is omitted from the format
specifier, the format specifier must be the second item in
the control-information list, and the first item must be the
unit specifier without the keyword UNIT=.
3. If the control-information list contains a record specifier
(REC=), the statement is a direct-access data transfer
statement. Otherwise, it is a sequential-access data
transfer statement.
If the keyword REC= is omitted from the record specifier, the
unit specifier (without the keyword UNIT=) must appear first
in the control-information list, followed by a single quote
('), and then the record specifier.
4. A control-information list cannot contain both a record
specifier and an end-of-file specifier.
5. If the format specifier is an asterisk or a NAMELIST name, a
record specifier must not be included in the
control-information list.
6. A control-information list in an internal file or ENCODE or
DECODE statement must contain a format specifier other than
an asterisk or NAMELIST name, and must not contain a record
specifier.
|
| 7. If the control-information list contains a key-of-reference
| specifier (KEYID=), the statement must also contain a
| key-field-value specifier. If a key-field-value specifier is
10-12
DATA TRANSFER STATEMENTS
| present, KEYID= may be omitted; the current key-of-reference
| as specified by a previous KEYID= specifier is used (or the
| primary index if never set).
10.4.3 Unit References in Data Transfer Statements
The unit specifier is used to refer to a file or device. The form of
a unit specifier is:
UNIT = un
where:
un is a logical unit identifier or an internal file identifier.
A logical unit identifier (see Section 10.4.3.1) is used to refer to
an external file. An internal file identifier (see Section 10.4.3.2)
is used to refer to an internal file.
The keyword UNIT= is optional if the unit specifier is the first item
in the control-information list.
10.4.3.1 FORTRAN Logical Unit Identifier - The FORTRAN logical unit
identifier is associated with the file to or from which data is being
transferred. This identifier is an integer expression whose value is
in the range of 0 to 99, or an asterisk.
For example, the following WRITE statement contains the reference to
logical unit number 22 as the first item in the control-information
list:
WRITE (22,101)
Table 10-3 lists the default logical unit number assignments. Note
that logical unit number 22 identifies the file as DSK:FOR22.DAT.
Thus, the sample WRITE statement references a disk. The unit
identifier asterisk corresponds to the card reader for the READ
statement, and to the line printer for the WRITE statement.
The compiler automatically assigns default logical unit numbers for
the REREAD, READ, ACCEPT, PRINT, PUNCH, TYPE, and WRITE statements.
Default unit numbers are negative integers that cannot be accessed.
For example:
1. OPEN(UNIT=n) or READ/WRITE(UNIT=n) where n is a negative
integer is illegal.
10-13
DATA TRANSFER STATEMENTS
2. Assigning a negative decimal number to a device at command
level is illegal.
You can, however, from monitor command level, assign a
default device to another device. For example, using the
TOPS-20 DEFINE command (or TOPS-10 ASSIGN command), you can
assign LPT: (line printer) to DSK: (disk). If you do this,
then any I/O statements that reference the line printer
actually reference the disk.
You can optionally make the logical device assignments at runtime, or
you can use the default assignments contained by the FORTRAN Object
Time System (FOROTS). Table 10-3 lists the default logical device
assignments. You should specify the device explicitly in an OPEN
statement (see Section 11.2) if you wish to override the default
assignment.
10-14
DATA TRANSFER STATEMENTS
Table 10-3: FORTRAN Logical Device Assignments
10-15
DATA TRANSFER STATEMENTS
10.4.3.2 Internal File Identifier - The internal file identifier
specifies the internal file to be used. This identifier is the name
of a character variable, character array, character array element, or
character substring.
Example:
CHARACTER*132 LINE
WRITE(UNIT=LINE,FMT='(F)')3.14159
10.4.4 Record Number References In Data Transfer Statements
All direct-access data transfer statements must contain a record
specifier, which is used in the transfer to identify the number of the
record to be accessed.
The form of the record specifier in the control-information list is:
REC=rn
where:
rn is a positive integer expression that indicates the
record number.
When you use the REC=rn form to specify the record number, you can
place the record specifier anywhere in the control-information list.
An alternative way for including the record specifier is:
un'rn
where:
un is a positive integer constant, variable, or array
element that represents the logical unit number of the
device to or from which the data transfer is being
made. When you use this form for specifying the
logical unit number, you cannot use the UNIT= keyword.
' is an apostrophe delimiting the logical unit number
from the record number.
rn is a positive integer constant, variable, or array
element that represents the record number.
When you use the alternative form for specifying the record number,
you cannot use the keyword REC=.
10-16
DATA TRANSFER STATEMENTS
10.4.5 Format References in Data Transfer Statements
All formatted data transfer statements must contain a format specifier
in the control-information list. The general form of the format
specifier is:
FMT=f
or
NML= a NAMELIST name
where:
FMT= is the keyword used in the keyword form of the format
specifier. Using the keyword form of the format
specifier makes it positionally independent in the
control-information list.
NML= is the keyword that can be used instead of FMT= for
NAMELIST formatting. Either FMT= or NML= can be used
for NAMELIST formatting.
f is a format identifier. Depending on the type of
formatting chosen, f can be one of the following:
1. A statement number
2. A numeric array name
3. A character expression
4. An integer, real, or logical variable
5. An asterisk
6. A NAMELIST name
If you do not use the keyword form of the format specifier, you must
place the format specifier as the second item of the
control-information list (immediately following the logical unit
number specifier) (see Section 10.4.2).
Sections 10.4.5.1 through 10.4.5.3 describe all forms of the format
specifier.
10-17
DATA TRANSFER STATEMENTS
10.4.5.1 FORMAT-Statement Formatting - The FORMAT-statement format
specifier has the following form:
FMT=f
where:
FMT= is the optional keyword in the format specifier.
f is one of the following:
1. The statement number of a FORMAT statement
appearing in the same program unit as the data
transfer statement
2. The name of a numeric array
3. A character expression
4. An integer, real, or logical variable that has been
assigned a FORMAT statement number with an ASSIGN
statement (see Section 8.3)
(See Section 12.1 for more information on
FORMAT-statement formatting.)
The following examples show all forms of the FORMAT-statement format
specifier. In the first example, the format specifier (FMT=101)
references the FORMAT statement 101 in the same program unit.
PROGRAM TEST
I=67
P=90.8
WRITE (UNIT=22,FMT=101) I,P
101 FORMAT (1X,'FIRST VALUE IS: ',I,' SECOND VALUE IS: ',F)
END
In the second example, the same format list used in the first example
is stored in an 10-element array. Note that the word "FORMAT" is not
included in the array.
PROGRAM TESTB
DIMENSION MYARAY(10)
MYARAY(1)='(1X,'''
MYARAY(2)='FIRST'
MYARAY(3)=' VALU'
MYARAY(4)='E IS:'
MYARAY(5)=' '',I,'
MYARAY(6)=''' SEC'
MYARAY(7)='OND V'
10-18
DATA TRANSFER STATEMENTS
MYARAY(8)='ALUE '
MYARAY(9)='IS: '''
MYARAY(10)=',F)'
I=67
P=90.8
WRITE (UNIT=22,FMT=MYARAY)I,P
END
In the third example, the same format list used in the first two
examples is stored in a character expression.
PROGRAM TESTC
INTEGER I
REAL P
CHARACTER WORD1*5,WORD2*6
I=67
P=90.8
WORD1='FIRST'
WORD2='SECOND'
WRITE(UNIT=22,FMT='(1X,'''//WORD1//' VALUE IS: '',I,'' '//
1 WORD2//' VALUE IS: '',F)') I,P
END
In the fourth example, the format specifier (FMT=IFORMT) references a
variable that has been assigned a statement number.
PROGRAM TESTD
ASSIGN 101 TO IFORMT
I=67
P=90.8
WRITE (UNIT=22,FMT=IFORMT) I,P
101 FORMAT (1X,'FIRST VALUE IS: ',I, 'SECOND VALUE IS: ',F)
END
For more information on FORMAT-statement formatting, see Section 12.1.
10.4.5.2 List-Directed Formatting - In list-directed formatting, the
variables in the I/O list of the data transfer statement dictate the
formatting of the data during the transfer.
The form of the list-directed format specifier is:
FMT=*
where:
10-19
DATA TRANSFER STATEMENTS
FMT= is the optional keyword part of the format specifier.
Including this keyword in the format specification
makes the specification positionally independent in the
control-information list. If you omit the FMT=
keyword, the format specifier must be the second
specifier (the unit specifier must be first).
* is an asterisk that indicates that the formatting is
list-directed.
In the following example, the variables I and P are formatted by
list-directed formatting.
PROGRAM TESTLD
I=67
P=90.8
WRITE (UNIT=22,FMT=*) I,P
END
List-directed formatting is further described in Section 12.5.
10.4.5.3 NAMELIST-Statement Formatting - If the formatting is
NAMELIST, the format specifier in the control-information list
contains a reference to a NAMELIST name defined in a NAMELIST
statement in the same program unit. Since the NAMELIST name
definition contains an I/O list, a data transfer statement that
contains a NAMELIST name in the format specifier cannot also contain
an I/O list.
The form of the NAMELIST format specifier is:
FMT=name
or
NML=name
where:
FMT= is the optional keyword part of the format specifier.
Including the keyword in the format specification makes
it positionally independent in the control-information
list. If you do not include the keyword part of the
format specifier, you must place the format specifier
second (after the logical unit number specifier) in the
control-information list.
NML= is an alternative keyword that can be used in place of
FMT.
10-20
DATA TRANSFER STATEMENTS
name is the NAMELIST name. The NAMELIST name is defined in
a NAMELIST statement in the same program unit.
In the following example, the data transfer statement uses a NAMELIST
name in its format reference:
PROGRAM TESTNL
NAMELIST/MYIOLT/I,P
READ (UNIT=5,NML=MYIOLT)
WRITE (UNIT=5,FMT=MYIOLT)
END
The execution of this sample program is as follows:
EXECUTE TEST.FOR
LINK: Loading
[LNKXCT TESTNL execution]
$MYIOLT I=675,P=34.71$
$MYIOLT
I= 675, P= 34.71000
$END
CPU time 0.2 Elapsed time 32.0
For further information on the NAMELIST statement, see Section 12.7.
10.4.6 Optional End-of-File Transfer of Control (END=)
The optional end-of-file transfer specifier (END=) specifies a
statement number to which control passes if this statement attempts to
read past the last data record of a file.
If you include an ERR= specifier (Section 10.4.7) and no END=
specifier, control passes to the statement indicated in the ERR=
specifier whenever an end-of-file condition occurs. Note that an END=
specifier on any output statement and on an input statement of a
direct-access file is ignored.
If no END= specifier, IOSTAT= specifier, or ERR= specifier is included
in the data transfer statement, and an end-of-file condition is
encountered, an error message is displayed on the controlling
terminal, and program execution is terminated.
The form of the END specifier is:
END=s
where:
10-21
DATA TRANSFER STATEMENTS
END= is the keyword part of the END= specifier. The END=
portion of the END= specifier is required.
s is the statement number of an executable statement in
the current program unit.
In the following example, the end-of-file specifier causes a transfer
of control to statement 50 after the data transfer statement
encounters an end-of-file on unit 22.
PROGRAM TESTEN
READ (UNIT=22,FMT=30,END=50) A,B,C
30 FORMAT (F/F/F)
GO TO 100
50 WRITE (UNIT=5,FMT=75)
75 FORMAT (1X,'END-OF-FILE HAS BEEN ENCOUNTERED')
100 WRITE (UNIT=5,FMT=105)
105 FORMAT (1X,'EXECUTION HAS ENDED')
END
The following shows the sample program being executed and the
end-of-file branch being taken. In this example, the READ statement
reads from the default filename, FOR22.DAT. To demonstrate the
end-of-file branch, FOR22.DAT is an empty file. Thus, when the READ
statement attempts to read records from FOR22.DAT, an immediate
end-of-file condition is detected.
EXECUTE TEST.FOR
FORTRAN:TESTEN
TESTEN
LINK: Loading
[LNKXCT TESTEN execution]
END-OF-FILE HAS BEEN ENCOUNTERED
EXECUTION HAS ENDED
CPU time 0.2 Elapsed time 0.5
| When sequentially reading records from an RMS indexed file, the
| end-of-file branch, if specified, will be taken if the statement
| attempts to read past the last data record of the current index.
10.4.7 Optional Data Transfer Error Control (ERR=)
The optional error specifier (ERR=) enables you to specify a statement
to which control passes if an error occurs during the data transfer.
If an error occurs other than for end-of-file, the file is positioned
after the record containing the error.
10-22
DATA TRANSFER STATEMENTS
NOTE
If the program attempts to read from the same unit
after an ERR= branch occurs, the record following the
record containing the error will be read. To read a
record containing the error, the program must execute
either a REREAD statement (Section 10.7) or a
BACKSPACE (Section 11.8.4) followed by a READ
statement.
If no ERR= specifier or IOSTAT= specifier is present and an error
occurs during the data transfer, the program is aborted.
The form of the error specifier is:
ERR=s
where:
ERR= is the keyword portion of the error specifier.
s is the statement number of an executable statement in
the same program unit.
The following example shows the error specifier being used to pass
control to the statement at line 85 if an error occurs during the data
transfer.
PROGRAM TESTEN
READ (UNIT=22,FMT=30,END=50,ERR=85) A,B,C
30 FORMAT (F/F/F)
GO TO 100
50 WRITE (UNIT=5,FMT=75)
75 FORMAT (1X,'END-OF-FILE HAS BEEN ENCOUNTERED')
GO TO 100
85 WRITE (UNIT=5,FMT=86)
86 FORMAT (1X,'THE TRANSFER ENCOUNTERED AN ERROR')
100 WRITE (5,105)
105 FORMAT (' EXECUTION HAS ENDED')
END
TYPE FOR22.DAT
100.
200.
AAAA BBBB CCCC DDDD
EXECUTE TESTEN.FOR
FORTRAN: TESTEN
TESTEN
LINK: Loading
[LNKXCT TESTEN execution]
10-23
DATA TRANSFER STATEMENTS
THE TRANSFER ENCOUNTERED AN ERROR
EXECUTION HAS ENDED
CPU time 0.2 Elapsed time 2.8
In this example, the error branch is taken when the input routine
detects a nonnumeric data item while attempting to read a
floating-point number into variable C. If the file FOR22.DAT contains
more than three records, the next READ accesses record 4 in the file.
10.4.8 Optional Error Variable For Error Reporting (IOSTAT=)
The optional I/O status specifier enables you to designate an integer
variable which receives a value indicating the success or failure of
the data transfer.
When the data transfer statement is successfully executed, the
variable is assigned a value of zero. If an error occurs during the
data transfer, the variable is assigned a positive value indicating
which error occured (see Appendix D). In this case, if there is no
ERR= specifier, the program proceeds to the statement after the data
transfer statement.
If an end-of-file occurs during the data transfer, the variable is set
to -1. In this case, if there is no END= or ERR= specifier, the
program proceeds to the statement after the data transfer statement.
The form of the error variable specifier is:
IOSTAT=ios
where:
ios is an integer variable that is the I/O status
specifier.
The following example shows the I/O status specifier being used to
report the number of the error on default unit 5 if the error branch
is taken.
PROGRAM TESTEN
10 READ (UNIT=22,FMT=30,END=50,ERR=85,IOSTAT=J)A,B,C
30 FORMAT (F4.1/F4.1/F4.1)
WRITE (UNIT=5,FMT=40)A,B,C
40 FORMAT (1X,'THE VALUES ARE: ',3F6.1)
GO TO 100
50 WRITE (UNIT=5,FMT=75)
75 FORMAT (1X,'END-OF-FILE HAS BEEN ENCOUNTERED')
GO TO 100
85 WRITE (UNIT=5,FMT=86)J
86 FORMAT (1X,'THE TRANSFER ENCOUNTERED AN ERROR; STATUS: ',I5)
10-24
DATA TRANSFER STATEMENTS
IF(J.GT.0) GO TO 10
100 WRITE (5,105)
105 FORMAT (' EXECUTION HAS ENDED')
END
TYPE FOR22.DAT
100.
200.
AAAA BBBB CCCC DDDD
80.
90.
95.
EXECUTE TESTEN.FOR
FORTRAN: TESTEN
TESTEN
LINK: Loading
[LNKXCT TESTEN execution]
THE TRANSFER ENCOUNTERED AN ERROR; STATUS: 307
THE VALUES ARE: 80.0 90.0 95.0
EXECUTION HAS ENDED
CPU time 0.2 Elapsed time 1.5
In this example, the IOSTAT variable J is set when the first READ
detects a nonnumeric data item while trying to input the data for
variable C. In this case, the value of IOSTAT represents the
processor specific error number (the second value listed in the FOROTS
error messages in Section D.1), and indicates that an illegal
character has been detected in the data. After the error status has
been printed, the second READ successfully executes using records 4,
5, and 6 from the file.
|
|
|
| 10.4.9 Key-Field-Value Specifier (TOPS-20 RMS)
|
| The key-field-value specifier is used to specify the key field value
| of a record to be accessed in an indexed file. Indexed files are
| composed of records that have one or more fields in common; that is,
| the byte offset, type and length of the field(s) are the same in each
| record in any given indexed file.
|
| A key-field-value specifier has two components:
|
| o An expression, which specifies the key field value to be used
| in locating the record to be transferred
|
| o A match criterion, which specifies the selection conditions
|
| A key-field-value specifier has one of the following forms:
10-25
DATA TRANSFER STATEMENTS
| KEY=val
| KEYEQ=val
| KEYGE=val
| KEYGT=val
|
| where:
| val is a character expression or an integer expression.
| Character expressions must be used with character key
| fields, and integer expressions must be used with
| integer key fields.
|
| An integer expression in a key-field-value specifier cannot contain
| real or complex values.
|
| The match criterion specifies which key values in the record can match
| the expression. There are three possible criteria:
|
| o Equal - the key field value must be equal to the expression
| specified.
|
| o Greater - the key field value must be greater than the
| expression specified.
|
| o Greater than or equal - the key field value must be greater
| than or equal to the expression specified.
|
| The following parameters are used to establish the desired match
| criterion:
|
| KEY=val specifies an equal match
| KEYEQ=val specifies an equal match
| KEYGT=val specifies a greater than match
| KEYGE=val specifies a greater than or equal match
|
| For character expressions, the comparison is made according to the
| ASCII collating sequence. For integer expressions, the comparison is
| made according to the signed integer value.
|
| For character keys, either generic match or exact match can be used.
| A generic match compares only a specified number of leading characters
| in the key. The length of the search key determines how many
| characters are compared.
|
| For example, if the expression is 'ABCD' and the key field is 10
| characters long, then an equal match is obtained for the first record
| containing 'ABCD' as the first 4 bytes of the key field. The
| remaining six characters are arbitrary.
|
| An approximate-generic match occurs when approximate match (KEYGT or
| KEYGE) is selected in addition to generic match. In that case, only
| the leftmost characters are used for comparison. For example, if the
| expression is 'ABCD', the key field is five characters long, and a
10-26
DATA TRANSFER STATEMENTS
| greater-than match is selected, then the value 'ABCDA' does not match;
| 'ABCEx' does match.
|
|
|
| 10.4.9.1 Key Attributes - By default, FOROTS creates new indexed
| files with the "No duplicate" and "No change" attributes set for the
| primary index. Secondary indexes default to the duplicates and
| allowed changes. Thus, new records containing a primary key that,
| when written, produces a duplicate primary key in the index, cause an
| error message or the ERR= branch to be taken. Records updated with a
| REWRITE statement that results in a revised primary key, also produce
| an error.
|
| The default "No duplicate" attribute for primary key can be changed
| only in a USEROPEN routine (see Section 11.3.39). RMS requires that
| primary keys cannot be changed.
|
|
|
| 10.4.10 Key-of-Reference Specifier
|
| The key-of-reference specifier may optionally be included with a
| key-field-value specifier; it is used to specify the key field index
| that is to be searched for the specified key field value.
|
| The form of the key-of-reference specifier is:
|
| KEYID=kn
|
| where:
|
| kn is an integer expression, called the key-of-reference
| number, which designates the key field index to be searched.
|
| The key-of-reference number is an integer value in the range zero to
| the maximum key number defined for the file. A value of zero
| specifies the primary key, a value of one specifies the first
| alternate key, and so forth.
|
| If no key-of-reference number is given, it defaults to the last
| specification given in a keyed I/O statement for that logical unit, or
| the primary key-of-reference if never set.
10.4.11 Data Transfer Statement Input/Output Lists
The I/O list in an input or output statement contains the names of
variables, arrays, array elements, or character substrings. The I/O
list in an output statement can also contain expressions, function
references, or constants.
10-27
DATA TRANSFER STATEMENTS
An I/O list has the following form:
e[,e]...
where:
| e is a simple input or output item (see Section 10.4.11.1) or
| an implied DO list (see Section 10.4.11.2).
The I/O statement assigns values to, or transfers values from, the
list elements in the order in which they appear (from left to right).
10.4.11.1 Simple List Elements - A simple input list item can be one
of the following:
1. A variable name
2. An array element name
3. A character substring name
4. An array name
For example:
READ (5,10) J,K(3),CH(1:3)
A simple output list item can be one of the above, or it can be one of
the following:
1. A constant
2. A function reference
3. An expression
For example:
WRITE (5,10) J,K(3),(L+4)/2,CH(1:3)
An input list item cannot be an expression. However, it can contain
expressions as subscripts or substring bounds.
I/O list items can be of the following types:
1. Integer
2. Real
10-28
DATA TRANSFER STATEMENTS
3. Double-precision
4. Complex
5. Logical
6. Character
7. Octal
8. Double Octal
9. Hollerith
When you use an unsubscripted array name in an I/O list, an input
statement reads enough data to fill every element of the array; an
output statement writes all the values in the array. Data transfer
begins with the initial element of the array and proceeds in the order
of subscript progression, with the leftmost subscript varying most
rapidly from lower to upper bound. For example, the following defines
a two-dimensional array:
DIMENSION ARRAY(3,3)
If the name ARRAY with no subscripts appears in a READ statement, that
statement assigns values from the input record(s) to ARRAY(1,1),
ARRAY(2,1), ARRAY(3,1), ARRAY(1,2), and so on through ARRAY(3,3).
In an input statement, variables in the I/O list can be used in array
subscripts later in the list, for example:
READ (1,1250) J,K,ARRAY(J,K)
1250 FORMAT (I1,1X,I1,1X,F6.2)
The input record contains the following values:
1,3,721.73
When the READ statement is executed, the first input value is assigned
to J and the second to K, thereby establishing the actual subscript
values for ARRAY(J,K). Then the value 721.73 is assigned to
ARRAY(1,3). Variables that are to be used as subscripts in this way
must appear before (to the left of) their use as the array subscripts
in the I/O list.
10.4.11.2 Implied DO Lists - An implied DO list is an I/O list
element that functions as though it were part of an I/O statement
within a DO loop. Implied DO lists can be used to:
10-29
DATA TRANSFER STATEMENTS
1. Specify iteration of part of an I/O list
2. Transfer part of an array
3. Transfer array elements in a sequence different from the
order of subscript progression
As in explicit DO loops, zero-trip implied DO loops are possible (see
Section 9.3).
An implied DO list has the form:
(dlist,i=e1,e2[,e3])
where:
dlist is an I/O list. Dlist can also contain other
implied DO lists.
i is the index control variable that can represent a
subscript appearing in a preceding subscript list.
e1,e2,e3 are the indexing parameters that specify,
respectively, the initial, terminal, and increment
values that control the range of i. If e3 is
omitted (with its preceding comma), a value of 1
is assumed.
The variable i and the parameters e1, e2, and e3 have the same forms
and the same functions that they have in the DO statement (see Section
9.3). The list immediately preceding the DO loop control variable is
the range of the implied DO loop. Elements in that list can reference
the index, but they must not alter it. Some examples are:
WRITE (3,200) (A,B,C, I=1,3)
The statement in this example functions as though you had written:
WRITE (3,200) A,B,C,A,B,C,A,B,C
The following two statements are the same:
WRITE (3,200) (X(I),I=1,3)
WRITE (3,200) X(1),X(2),X(3)
Another example is:
WRITE (6) (I,(J,P(I),Q(I,J),J=1,L),I=1,M)
The I/O list in this example consists of an implied DO list containing
another implied DO list nested with it. The implied DO lists together
10-30
DATA TRANSFER STATEMENTS
write a total of (1+3*L) *M fields, varying values of J for each value
of I.
In a series of nested implied DO lists, the parentheses indicate the
nesting (see Section 9.3.4). Execution of the innermost list is
repeated most often. For example:
WRITE (6,150) ((FORM(K,L), L=1,10), K=1,10,2)
150 FORMAT (F10.2)
Because the inner DO loop is executed 10 times for each iteration of
the outer loop, the second subscript, L, advances from 1 through 10
for each increment of the first subscript. This is the reverse of the
order of subscript progression. In addition, K is incremented by 2,
so only the odd-numbered rows of the array are output.
The entire list of an implied DO list is transmitted before the
control variable is incremented, for example:
READ (5,999) (P(I), (Q(I,J), J=1,10), I=1,5)
In this example, P(1), Q(1,1), Q(1,2),...,Q(1,10) are read before I is
incremented to 2.
When processing multidimensional arrays, you can use a combination of
fixed subscripts and subscripts that vary according to an implied DO
list, for example:
READ (3,5555) (BOX(1,J), J=1,10)
This statement assigns input values to BOX(1,1) through BOX(1,10) and
then terminates without affecting any other element of the array.
The value of the control variable can also be output directly. For
example:
WRITE (6,1111) (I, I=1,20)
This statement simply outputs the integers 1 through 20.
READ
Statement
10-31
DATA TRANSFER STATEMENTS
10.5 READ STATEMENT
The READ statement transfers data from a file into memory. There are
two categories of READ statements: formatted (see Section 10.5.1) and
| unformatted (see Section 10.5.2). An indexed READ statement (see
| Section 10.5.3) applies only to RMS indexed files, and can be either
| formatted or unformatted.
| For RMS relative files that are accessed sequentially, RMS reads the
| next existing record, skipping any deleted or empty record cells.
| Relative files accessed randomly return a "?Record not found" error
| (or take the ERR= branch) for deleted or non-existent records.
Table 10-4 summarizes the various forms of the READ statement.
10-32
DATA TRANSFER STATEMENTS
Table 10-4: Summary of READ Statement Forms
10-33
DATA TRANSFER STATEMENTS
10.5.1 Formatted READ Transfers
A formatted READ transfer uses a READ statement that specifies that
the transferred data is edited during the transfer, such that the
external and internal representation of the data are different. The
three types of formatted READ statements are: FORMAT-statement,
list-directed, and NAMELIST-statement.
There are two types of access to the device from which the READ
statement transfers data. They are sequential and direct. If you
want to perform a direct-access formatted READ from a device, you must
use FORMAT-statement formatting. List-directed and NAMELIST
formatting can only be used with sequential-access formatted READ
statements.
10.5.1.1 Sequential FORMAT-Statement READ - This section describes
the sequential-access (FORMAT-statement) formatted READ statement.
This statement has the following forms:
READ (UNIT=un,FMT=f[,END=s][,ERR=s][,IOSTAT=ios])[iolist]
READ (un,FMT=f[,END=s][,ERR=s][,IOSTAT=ios])[iolist]
READ (un,f[,END=s][,ERR=s][,IOSTAT=ios])[iolist]
If an I/O list is included in these forms, it specifies that data is
transferred from logical unit un, formatted according to the
specification given by f, and transferred into the elements of the
specified I/O list.
If an I/O list is not included, the input record is skipped. (If the
FORMAT statement specifies slash editing, more than one record can be
skipped. H or apostrophe editing can cause data transfers to occur to
the FORMAT statement itself. See Section 12.4.)
The following example contains two READ statements: the first
contains an I/O list; the second does not:
READ (22,5) A,Z,J
5 FORMAT (2F10.2,I5)
READ (22,5)
END
In this example, the first READ statement reads one record from
logical unit 22, formats the data according to the FORMAT statement,
and assigns the values to the variables A, Z, and J. The second READ
statement skips one input record on logical unit 22.
The default unit forms of this READ statement operates in the same way
10-34
DATA TRANSFER STATEMENTS
as the first forms, except that data transfers reference the card
reader, which is the default logical unit for these forms.
The default unit forms of this statement are:
READ f[,iolist]
READ (UNIT=*,FMT=f[,END=s][,ERR=s][,IOSTAT=ios])[iolist]
10.5.1.2 Direct-Access FORMAT-Statement READ - This section describes
the direct-access (FORMAT-statement) formatted READ statement.
The forms of this statement are:
READ (UNIT=un,FMT=f,REC=rn[,ERR=s][,IOSTAT=ios])[iolist]
READ (un,FMT=f,REC=rn[,ERR=s][,IOSTAT=ios])[iolist]
READ (un,f,REC=rn[,ERR=s][,IOSTAT=ios])[iolist]
If an I/O list is included in these forms, the data specified by
record rn is transferred, according to the format specifications given
in f, into the elements of the I/O list. These forms can be used only
with disk files that have been opened by an OPEN statement that
specifies ACCESS='DIRECT', ACCESS='RANDOM', or ACCESS='RANDIN' (see
Section 11.3.1).
If the record specified by rn has not been written, an error results
(except for IMAGE mode files).
The following example shows this form of the READ statement.
OPEN(22,RECORDSIZE=25,ACCESS='DIRECT')
READ (22,5,REC=10)A,Z,J
5 FORMAT (2F10.2,I5)
END
In this example, the READ statement reads record 10 from logical unit
22, formats the data according to the FORMAT statement, and assigns
the values to variables A, Z, and J.
The alternative forms of this READ statement operate in the same way
as the first forms. The only difference between the forms is the way
in which the unit and record specifications are expressed.
The alternative forms for this statement are:
READ (un'rn,FMT=f[,ERR=s][,IOSTAT=ios])[iolist]
READ (un'rn,f[,ERR=s][,IOSTAT=ios])[iolist]
10-35
DATA TRANSFER STATEMENTS
In the alternative forms, the unit and record references do not
contain the keywords UNIT= and REC=. Instead the unit number is
specified first; a single quote (') is specified next; followed by a
record number, a comma, and finally the format reference.
10.5.1.3 Sequential List-Directed READ - This section describes the
sequential-access (list-directed) formatted READ statement.
This statement has the following forms:
READ (UNIT=un,FMT=*[,END=s][,ERR=s][,IOSTAT=ios])[iolist]
READ (un,FMT=*[,END=s][,ERR=s][,IOSTAT=ios])[iolist]
READ (un,*[,END=s][,ERR=s][,IOSTAT=ios])[iolist]
With these forms, the data is transferred from logical device un and
is formatted according to the data types of the elements of the I/O
list. If the I/O list is not included, a record is skipped.
The default unit forms of this statement are:
READ *[,iolist]
READ (UNIT=*,FMT=*[,END=s][,ERR=s][,IOSTAT=ios])[iolist]
With these forms, the data is transferred from the card reader (the
default device), and is formatted according to the data types of the
elements in the specified I/O list.
The following example shows this form of the READ statement:
CHARACTER*14 C
DOUBLE PRECISION T
COMPLEX D,E
LOGICAL L,M
READ (1,*) I,R,D,E,L,M,J,K,S,T,C,A,B
END
The external record to be read contains the following:
4 6.3 (3.4,4.2), (3,2 ) , T,F,,3*14.6 ,'ABC,DEF/GHI''JK'/
Upon execution of the program unit, the following values are assigned
to the I/O list elements:
I 4
R 6.3
D (3.4,4.2)
E (3.0,2.0)
10-36
DATA TRANSFER STATEMENTS
L .TRUE.
M .FALSE.
K 14
S 14.6
T 14.6D0
C ABC,DEF/GHI'JK
A, B, and J are unchanged.
10.5.1.4 Sequential NAMELIST-Statement READ - This section describes
the sequential-access (NAMELIST-statement) formatted READ statement.
This statement has the following forms:
READ (UNIT=un,FMT=name[,END=s][,ERR=s][,IOSTAT=ios])
READ (UNIT=un,NML=name[,END=s][,ERR=s][,IOSTAT=ios])
READ (un,FMT=name[,END=s][,ERR=s][,IOSTAT=ios])
READ (un,NML=name[,END=s][,ERR=s][,IOSTAT=ios])
READ (un,name[,END=s][,ERR=s][,IOSTAT=ios])
With these forms, the data is transferred from the specified unit into
the locations specified by the NAMELIST list. The formatting is
controlled by the implicit data types of the NAMELIST list items. We
suggest that you use the NAMELIST form of the READ statement to
transfer data from files created by the NAMELIST form of the WRITE
statement (Section 10.6.1.4).
The following example shows this form of the READ statement:
NAMELIST /DATA/A,Z,J
READ (22,DATA)
END
In this example, the NAMELIST statement associates the NAMELIST name
DATA with a list of three items. The corresponding READ statement
reads input data and assigns values to the specified namelist items.
10.5.2 Unformatted READ Transfers
Unformatted READ transfers move data from a specified file to
locations in memory. Unlike formatted READ transfers, unformatted
transfers do not involve any editing of the data.
The two types of unformatted data transfers enable you to access a
10-37
DATA TRANSFER STATEMENTS
specified file either sequentially or directly.
NOTE
The OPEN statement MODE specifier enables you to
specify in which form the unformatted data file exists
| (see Section 11.3.24). If you execute an unformatted
READ statement without having first specified the MODE
in an OPEN statement, the data file is assumed to be
BINARY. (For additional information on unformatted
data file forms, see Section 11.2.)
10.5.2.1 Sequential Unformatted READ - This section describes the
sequential-access unformatted READ statement.
This statement has the following forms:
READ (UNIT=un[,END=s][,ERR=s][,IOSTAT=ios])[iolist]
READ (un[,END=s][,ERR=s][,IOSTAT=ios])[iolist]
If the I/O list is present, the data is transferred as one logical
record from the specified logical unit. This type of read should only
be used to read files that have been created by unformatted WRITE
statements.
If you omit the I/O list portion of the statement, the statement skips
one logical record on input from the specified unit.
The following example shows this type of READ statement used both with
and without the I/O list:
READ (22)A,Z,J
READ (22)
END
In this example, the first READ statement reads one record from
logical unit 22 and assigns values to variables A, Z, and J. The
second READ statement skip one record from logical unit 22.
10.5.2.2 Direct-Access Unformatted READ - This section describes the
direct-access unformatted READ statement.
This statement has the following forms:
READ (UNIT=un,REC=rn[,ERR=s][,IOSTAT=ios])[iolist]
READ (un,REC=rn[,ERR=s][,IOSTAT=ios])[iolist]
10-38
DATA TRANSFER STATEMENTS
If an I/O list is included in these forms, the data, in the form of
one logical record, is transferred from the specified unit into the
elements of the I/O list. Only files that have been output by an
unformatted WRITE statement should be transferred by this form of the
READ statement. In addition, for FORTRAN binary files, if the record
specified by rn has not been written, an error results.
These forms can be used only with disk files that have been opened by
an OPEN statement that specifies ACCESS='DIRECT', ACCESS='RANDOM', or
ACCESS='RANDIN' (see Section 11.3.1).
The alternative form of this READ statement functions the same as the
first forms. The only difference between the forms is in the way that
the unit and record are specified.
The alternative form of this statement is:
READ (un'rn[,ERR=s][,IOSTAT=ios])[iolist]
In this form, the unit and record references do not contain the
keywords UNIT= and REC=. Instead the unit number is specified first;
a single quote (') is specified next; then the record number is
specified last.
The following example demonstrates the use of the unformatted READ
statement:
OPEN (22,ACCESS='DIRECT',RECORDSIZE=3)
READ (22,REC=10)A,Z,J
READ (22'12)B,X,K
END
In this example, the first READ statement reads record 10 from logical
unit 22 and assigns values to the variables A, Z, and J. The second
READ statement reads record 12 from logical unit 22 and assigns values
to the variables B, X, and K.
|
|
|
| 10.5.3 Indexed READ Transfers (TOPS-20)
|
| RMS indexed files can be read either sequentially or randomly by
| key-of-reference and key-field-value. The access mode is determined
| by the READ statement, and can be switched from one mode to the other
| in successive read statements.
|
| Keyed or random READ statements from an indexed file require the
| specification of a key relational value (match criterion), and
| optionally, a key-of-reference. Keyed or random READ statements can
| be formatted or unformatted.
10-39
DATA TRANSFER STATEMENTS
| 10.5.3.1 Sequential Indexed READ - Indexed files can be read
| sequentially on any index defined when the file is created. A
| sequential indexed read does not require any new syntax in the READ
| statement.
|
| Sequential reads retrieve successive records in an indexed file by
| ascending key value for a specific key of reference. The key of
| reference can be established by a prior keyed read (the key of
| reference remains unchanged until the next keyed read changes it), or
| defaults to the primary key of reference.
|
| A sequential read on a key of reference returns end-of-file when no
| records with a higher key value exist in that index.
|
|
|
| 10.5.3.2 Formatted Indexed READ - This section describes the
| formatted indexed READ statement.
|
| This statement has the following forms:
|
| READ (UNIT=un,FMT=f,key=val[,KEYID=kn][,ERR=s][,IOSTAT=ios])[iolist]
|
| READ (un,FMT=f,key=val[,KEYID=kn][,ERR=s][,IOSTAT=ios])[iolist]
|
| READ (un,f,key=val[,KEYID=kn][,ERR=s][,IOSTAT=ios])[iolist]
|
| where key= can be either KEY=, KEYEQ=, KEYGT=, or KEYGE=.
|
| The formatted indexed READ statement can be used only on indexed
| files. If the I/O list and format specifications specify that
| additional records are to be read, the statement reads those
| additional records sequentially using the current key-of-reference
| value.
|
| If the KEYID= keyword is omitted, the key-of-reference remains
| unchanged from the most recent specification. If the KEYID= keyword
| is omitted from the first keyed read, the key-of-reference is the
| primary key.
|
| If the specified key value is shorter than the key field referred to,
| the key value is matched against the leftmost characters of the
| appropriate key field until a match is found; the record supplying the
| match is then read.
|
| An example of the use of the formatted indexed READ statement is:
|
| READ (1,KAT(25),KEY='ABCD') A,B,C,D
|
| In this example, the READ statement retrieves a record with a key
| value of "ABCD' in the primary key, and then uses the format contained
| in the array item KAT(25) to read the first four fields from the
10-40
DATA TRANSFER STATEMENTS
| record into variables A,B,C, and D.
|
|
|
| 10.5.3.3 Unformatted Indexed READ - This section describes the
| unformatted indexed READ statement.
|
| This statement has the following forms:
|
| READ (UNIT=un,key=val[,KEYID=kn][,ERR=s][,IOSTAT=ios])[iolist]
|
| READ (un,key=val[,KEYID=kn][,ERR=s][,IOSTAT=ios])[iolist]
|
| where key= can be either KEY=, KEYEQ=, KEYGT=, or KEYGE=.
|
| The unformatted indexed READ statement can be used only on indexed
| files. If the number of the I/O list elements is less than the number
| of fields in the record being read, the unused fields in the record
| are discarded.
|
| If a specified key value is shorter than the key field referred to,
| the key value is matched against the leftmost characters of the
| appropriate key field until a match is found; the record supplying the
| match is then read.
|
| The following example demonstrates the use of the unformatted indexed
| READ statement:
|
| OPEN (UNIT=1,STATUS='OLD',
| 1 ACCESS='KEYED',ORGANIZATION='INDEXED'
| 2 FORM='UNFORMATTED',
| 3 KEY=(1:5,30:37,18:23))
|
| READ (1,KEY='SMITH') ALPHA, BETA
|
| In this example, the READ statement reads from the indexed file
| connected to logical unit 1 and retrieves the record with the value
| 'SMITH' in the primary key field (bytes 1 to 5). The first two fields
| of the record retrieved are placed in variables ALPHA and BETA,
| respectively.
|
| READ (1,KEYGE='XYZDEF',KEYID=2,ERR=99) IKEY
|
| In this example, the READ statement retrieves the first record having
| a value equal to or greater than 'XYZDEF' in the second alternate key
| field (bytes 18 to 23). This first field of that record is placed in
| the variable IKEY.
WRITE
10-41
DATA TRANSFER STATEMENTS
Statement
10.6 WRITE STATEMENT
WRITE statements transfer data from memory to a file. The various
forms of the WRITE statement enable it to be used in sequential,
append, and direct-access transfer modes for formatted, unformatted,
list-directed, and NAMELIST-controlled data transfers.
| WRITE statements cannot write to existing records in an indexed file.
| For statements that can perform this function in indexed files, see
| the REWRITE statement (Section 10.14).
Table 10-5 summarizes all forms of the WRITE statement.
Table 10-5: Summary of WRITE Statement Forms
10-42
DATA TRANSFER STATEMENTS
10-43
DATA TRANSFER STATEMENTS
10.6.1 Formatted WRITE Transfers
A formatted WRITE transfer uses a WRITE statement that specifies that
the transferred data is edited during the transfer, such that the
external and internal representations of the data are different. The
three types of formatted WRITE statements are: FORMAT-statement,
list-directed, and NAMELIST-statement.
There are two types of access to the device to which the WRITE
statement transfers data. They are sequential and direct. If you
want to perform a direct-access formatted WRITE to a device, you must
use FORMAT-statement formatting. List-directed and NAMELIST-statement
formatting can only be used for sequential-access formatted WRITE
statements.
10.6.1.1 Sequential FORMAT-Statement WRITE - This section describes
the sequential-access (FORMAT-statement) formatted WRITE statement.
This statement has the following forms:
WRITE (UNIT=un,FMT=f[,ERR=s][,IOSTAT=ios])[iolist]
WRITE (un,FMT=f[,ERR=s][,IOSTAT=ios])[iolist]
WRITE (un,f[,ERR=s][,IOSTAT=ios])[iolist]
If the I/O list is included in these forms, the data specified by the
elements of the I/O list are output to a file on logical unit un. The
output data is formatted in this file according to the FORMAT
specifications given in f.
A blank record is written if the I/O list is not specified, and one of
the following is true:
1. The FORMAT statement is empty.
2. No slash, H, or apostrophe editing descriptors occur alone.
3. No slash, H, or apostrophe editing descriptors precede the
first repeatable edit descriptors.
See Section 12.4.
The following example contains a sequential formatted WRITE that
contains an I/O list, and one that does not:
A=11.4
Z=13.9
J=5
WRITE (22,5)A,Z,J
10-44
DATA TRANSFER STATEMENTS
5 FORMAT (1X,2F10.2,I5)
WRITE (22,15)
15 FORMAT (' PAGE NO. 1')
END
The following is written to logical unit 22:
11.40 13.90 5
PAGE NO. 1
The default unit forms of this statement are:
WRITE f[,iolist]
WRITE (UNIT=*,FMT=f[,ERR=s][,IOSTAT=ios])[iolist]
If an I/O list is included in these forms, the data, specified by the
elements within the I/O list, are transferred to the default device
(line printer). The transferred data are formatted according to the
FORMAT specification given by f.
The following example shows both forms of this WRITE transfer:
A=11.4
Z=13.9
J=5
WRITE 5,A,Z,J
5 FORMAT (1X,2F10.2,I5)
WRITE 15
15 FORMAT (' PAGE NO. 1')
END
The following is written to the default device (line printer):
11.40 13.90 5
PAGE NO. 1
10.6.1.2 Direct-Access FORMAT-Statement WRITE - The direct-access
(FORMAT-statement) formatted WRITE statement is described in this
section.
This statement has the following forms:
WRITE(UNIT=un,FMT=f,REC=rn[,ERR=s][,IOSTAT=ios])[iolist]
WRITE(un,FMT=f,REC=rn[,ERR=s][,IOSTAT=ios])[iolist]
WRITE(un,f,REC=rn[,ERR=s][,IOSTAT=ios])[iolist]
10-45
DATA TRANSFER STATEMENTS
If you include an I/O list in these forms, the data in the I/O list is
written starting at record rn to a file on logical unit un. The
formatting is controlled by the FORMAT specifications given at f.
Only disk files that have been opened by an OPEN statement that
specifies ACCESS='DIRECT' or ACCESS='RANDOM' (see Section 11.3.1) can
| be accessed by a WRITE statement of this form. This form is not
| permitted for RMS indexed files.
If you omit the I/O list portion of this statement, at least one blank
record (specified by REC=rn) is written to logical unit un.
The following example shows a direct-access formatted WRITE statement
that contains an I/O list, and one that does not:
A=11.4
Z=13.9
J=5
OPEN(22,RECORDSIZE=25,ACCESS='RANDOM')
WRITE (22,5,REC=10)A,Z,J
5 FORMAT (2F10.2,I5)
WRITE (22,15,REC=11)
15 FORMAT (' PAGE NO. 1')
END
The following is written to logical unit 22:
11.40 13.90 5
PAGE NO. 1
The alternative forms of this WRITE statement operate the same way as
the first forms. The only difference between the forms is in the way
that the logical unit and the record number are expressed.
The alternative forms of this statement are:
WRITE (un'rn,FMT=f[,ERR=s][,IOSTAT=ios])[iolist]
WRITE (un'rn,f[,ERR=s][,IOSTAT=ios])[iolist]
In these forms, the unit and record references do not contain the
keywords UNIT= and REC=. Instead the unit number is specified first;
a single-quote (') is specified next, followed by a record number, a
comma, and finally the format reference.
10.6.1.3 Sequential List-Directed WRITE - This section describes the
sequential-access (list-directed) formatted WRITE statement.
This statement has the following forms:
10-46
DATA TRANSFER STATEMENTS
WRITE (UNIT=un,FMT=*[,ERR=s][,IOSTAT=ios])[iolist]
WRITE (un,FMT=*[,ERR=s][,IOSTAT=ios])[iolist]
WRITE (un,*[,ERR=s][,IOSTAT=ios])[iolist]
These forms of the WRITE statement specify that the data identified in
the I/O list is written to logical unit un. Because the transfer is
list-directed (FMT=*), the data is formatted according to the implicit
data types of the variables in the I/O list. If the I/O list is not
included, a blank record is written.
The default unit forms of this statement are:
WRITE *[,iolist]
WRITE (UNIT=*,FMT=*[,ERR=s][,IOSTAT=ios])[iolist]
The default unit forms function in the same way as the first forms,
except that the output is written to the default device (line
printer).
The following example shows the list-directed WRITE statement:
DIMENSION A(4)
DATA A/4*3,4/
WRITE (1,*) 'ARRAY VALUES FOLLOW'
WRITE (1,*) A,4
END
The following is written to logical unit 1:
ARRAY VALUES FOLLOW
4*3,400000, 4
10.6.1.4 Sequential NAMELIST-Statement WRITE - This section describes
the sequential-access (NAMELIST-statement) formatted WRITE statement.
This statement has the following forms:
WRITE (UNIT=un,FMT=name[,ERR=s][,IOSTAT=ios])
WRITE (UNIT=un,NML=name[,ERR=s][,IOSTAT=ios])
WRITE (un,FMT=name[,ERR=s][,IOSTAT=ios])
WRITE (un,NML=name[,ERR=s][,IOSTAT=ios])
WRITE (un,name[,ERR=s][,IOSTAT=ios])
10-47
DATA TRANSFER STATEMENTS
These forms of the WRITE statement transfer data defined in the
referenced NAMELIST statement (FMT=name or NML=name) to the file on
the logical unit specified by un.
The following example demonstrates the NAMELIST form of the WRITE
statement:
CHARACTER*19 NAME(2)
DATA NAME/2*' '/
REAL PITCH, ROLL, YAW, POSIT(3)
LOGICAL DIAGNO
INTEGER ITERAT
NAMELIST /PARAM/ NAME, PITCH, ROLL, YAW, POSIT, DIAGNO, ITERAT
ACCEPT (FMT=PARAM)
WRITE (UNIT=1,FMT=PARAM)
END
The input contains the following:
b$PARAM NAME(2)(10:)='HEISENBERG',
bPITCH=5.0, YAW=0.0, ROLL=5.0,
bDIAGNO=.TRUE.
bITERAT=10$END
The WRITE statement writes the following:
$PARAM
NAME= ' ', ' HEISENBERG', PITCH=
5.000000, ROLL= 5.000000, YAW= 0.0000000E+00, POSIT= 3*0.0000000E+00,
DIAGNO= T, ITERAT= 10
$END
10.6.2 Unformatted WRITE Transfers
Unformatted WRITE transfers move data from memory to a file. Unlike
formatted WRITE transfers, unformatted WRITE transfers do not involve
any editing of the data.
The two types of unformatted data transfers enable you to write to a
file either sequentially or directly.
NOTE
The MODE specifier of the OPEN statement enables you
to specify the type of unformatted data file you want
| to create (see Section 11.3.24). If you execute an
unformatted WRITE statement without having first
specified the MODE in an OPEN statement, the data file
is by default BINARY. For additional information on
10-48
DATA TRANSFER STATEMENTS
unformatted data file forms, see Section 11.2.
10.6.2.1 Sequential Unformatted WRITE - This section describes the
sequential-access unformatted WRITE statement.
This statement has the following forms:
WRITE (UNIT=un[,ERR=s][,IOSTAT=ios])[iolist]
WRITE (un[,ERR=s][,IOSTAT=ios])[iolist]
If the I/O list is present in these forms, the data is written as one
logical record to the file contained on the specified logical unit un.
If you omit the I/O list in this statement, the statement writes one
blank logical record to the file contained on the specified logical
unit un.
The following example shows this form of the WRITE statement with the
I/O list and without the I/O list:
WRITE (22)A,Z,K
WRITE (22)
END
In this example, the first WRITE statement writes a record to the file
connected to logical unit 22 containing the values of the variables A,
Z, and K. The second WRITE statement writes one blank record to the
file connected to logical unit 22.
10.6.2.2 Direct-Access Unformatted WRITE - This section describes the
direct-access unformatted WRITE statement.
This statement has the following forms:
WRITE (UNIT=un,REC=rn[,ERR=s][,IOSTAT=ios])[iolist]
WRITE (un,REC=rn[,ERR=s][,IOSTAT=ios])[iolist]
| These forms can be used only with non-indexed disk files which have
been opened by an OPEN statement that specifies ACCESS='DIRECT' or
ACCESS='RANDOM' (see Section 11.3.1). If an I/O list is included in
these forms, the data, in the form of one logical record, is
transferred from the memory to record rn of the file on the specified
logical unit.
If the I/O list is not specified, the statement outputs one logical
blank record.
10-49
DATA TRANSFER STATEMENTS
The following example shows this type of WRITE statement with an I/O
list and without an I/O list:
OPEN(22,ACCESS='DIRECT',RECORDSIZE=3)
WRITE (22,REC=10)A,Z,K
WRITE (22,REC=12)
In this example, the first WRITE statement writes the values of the
variables A, Z, and K to record 10 on logical unit 22. The second
WRITE statement writes one logical blank record to record 12 on
logical unit 22.
The alternative form of this type of WRITE statement operates in the
same way as the first forms. The difference between the forms is in
the way that the unit and the record are specified.
The alternative form of this statement is:
WRITE (un'rn[,ERR=s][,IOSTAT=ios])[iolist]
In this form, the unit and record references do not contain the
keywords UNIT= and REC=. Instead the unit number is specified first;
a single quote (') is specified next; then the record number is
specified last.
|
|
|
| 10.6.3 Writing to RMS Files (TOPS-20)
|
| WRITE statements to RMS files can be either formatted or unformatted.
|
| Records written to RMS files that have a RECORDSIZE value (see Section
| 11.3.33), cannot be larger than the size specified at file creation
| time. Formatted records that are shorter are padded by FOROTS to
| RECORDSIZE with the character specified in PADCHAR before being
| written. Unformatted records are padded with nulls. Records that are
| larger than the size specified at file creation are truncated with a
| warning.
|
| WRITE statements to indexed files are indistinguishable from normal
| sequential WRITE statements. WRITE statements to indexed files must
| not contain key-relational or key-of-reference data. RMS examines the
| record being written and determnines the position of the new record on
| the basis of the record's primary key. New records cannot be larger
| than the size specified at the file creation time; FOROTS pads shorter
| formatted records to RECORDSIZE with the character specified in
| PADCHAR (see Section 11.3.28).
|
| An indexed WRITE statement writes a new record; the REWRITE statement
| must be used to update an existing record. Each new record in an
| indexed file must contain a complete primary key. Alternate keys can
| be partially or completely absent. RMS does not make an entry for the
10-50
DATA TRANSFER STATEMENTS
| new record in the associated alternate indexes.
|
| When performing a formatted WRITE to an indexed file that contains
| integer key data types, the key is translated from internal binary
| form to external character form. A subsequent attempt to read the
| record using an integer key produces unpredictable results.
REREAD
Statement
10.7 REREAD STATEMENT
The REREAD statement causes the last record read from the last
sequential formatted READ or ACCEPT statement to again be accessed and
processed. You cannot use the REREAD feature until an input (READ)
transfer has been accomplished. You can use the REREAD statement only
for sequential-access formatted data transfers. The REREAD statement
can be used with both FORMAT-statement formatting and list-directed
formatting.
Once a record has been accessed by a formatted READ statement, the
record transferred can be reread as many times as desired. You can
use the same or a new format specification for each successive REREAD
statement.
Table 10-6 summarizes all the forms of the REREAD statement.
10-51
DATA TRANSFER STATEMENTS
Table 10-6: Summary of REREAD Statement Forms
10.7.1 Sequential FORMAT-Statement REREAD
This section describes the sequential-access (FORMAT-statement) REREAD
statement.
The first form of this statement is:
REREAD (FMT=f[,END=s][,ERR=s][,IOSTAT=ios])[iolist]
If the I/O list is specified in this form, the previous record is
transferred from the logical unit (specified in the previous formatted
READ statement) to the memory locations specified by the elements in
the I/O list. The transferred record is formatted according to the
FORMAT specifications given in f.
If you omit the I/O list from this statement, the input record is
skipped. (If the FORMAT statement specifies slash editing, more than
one record can be skipped. H or apostrophe editing can cause data
transfers to occur to the FORMAT statement itself. See Section 12.4.)
The second form of this REREAD statement operates in the same way as
the first form. The difference between the two forms is in the way
the FORMAT specifiers are expressed.
The second form of this statement is:
REREAD f[,iolist]
In this form, the keyword form of the FORMAT specifier (FMT=) is not
used in the FORMAT reference. Whenever you use the keyword form of
10-52
DATA TRANSFER STATEMENTS
this specifier, you must enclose the keyword list in parentheses.
The following example shows the formatted REREAD being used:
CHARACTER J*5
DIMENSION J(5)
1 READ (20,5)A,X,I
5 FORMAT (2F10.2,I5)
10 REREAD 15,J
15 FORMAT (5A5)
END
In the above sequence, statement 1 reads the two real variables A and
X, and the integer I. Statement 10 rereads the last record input from
unit 5 as a character string of 25 characters, five per word, and puts
five characters per element into the array J.
10.7.2 Sequential List-Directed REREAD
This section describes the sequential-access (list-directed) REREAD
statement.
The first form of this statement is:
REREAD (FMT=*[,END=s][,ERR=s][,IOSTAT=ios])[iolist]
In this form, the last record read by a formatted READ statement is
transferred from the logical unit (specified in the formatted READ
statement) into the memory locations identified by the elements of the
I/O list. Since the formatting is list-directed, the format of the
data is controlled by the data types of the elements in the I/O list.
If no I/O list is included, no data is transferred.
The second form of this statement operates in the same way as the
first form. The difference between the two forms is the way in which
the formatting is specified.
The second form of this statement is:
REREAD *[,iolist]
The following example shows the list-directed form of the REREAD
statement:
READ (20,*) A
REREAD *,B
END
In this example, the READ statement reads data from logical unit 20
into variable A. The REREAD statement rereads the data from logical
10-53
DATA TRANSFER STATEMENTS
unit 20 into variable B.
10-54
DATA TRANSFER STATEMENTS
ACCEPT
Statement
10.8 ACCEPT STATEMENT
The ACCEPT statement enables you to input data from your terminal into
memory. You can use the ACCEPT statement only for sequential-access
formatted data transfers. This statement can be used with both
FORMAT-statement and list-directed formatting.
Table 10-7 summarizes all forms of the ACCEPT statement.
Table 10-7: Summary of ACCEPT Statement Forms
10.8.1 Sequential FORMAT-Statement ACCEPT
This section describes the sequential-access (FORMAT-statement) ACCEPT
statement.
The first form of this statement is:
ACCEPT (FMT=f[,END=s][,ERR=s][,IOSTAT=ios])[iolist]
If you include the I/O list in this form, the data is taken from the
terminal and stored in the memory locations identified in the I/O
10-55
DATA TRANSFER STATEMENTS
list. The transferred data is formatted according to the FORMAT
specifications given in f.
If you omit the I/O list from this form, the input record is skipped.
(If the FORMAT statement specifies slash editing, more than one record
can be skipped. H or apostrophe editing can cause data transfers to
occur to the FORMAT statement itself. See Section 12.4.)
The second form of this statement operates in the same way as the
first form. The difference between the two forms is in how the FORMAT
reference is expressed.
The second form of this statement is:
ACCEPT f[,iolist]
In this form, the keyword portion of the FORMAT specifier (FMT=) is
omitted.
The following example shows both forms of the FORMAT-statement ACCEPT.
ACCEPT (FMT=35)A,Z,J
35 FORMAT (2F10.2,I5)
ACCEPT 15,B
15 FORMAT (F10.2)
END
In this example, the first ACCEPT statement accepts the values of the
variables A, Z, and J from the terminal in the form of FORMAT
statement 35. The second ACCEPT statement accepts the value of
variable B from the terminal in the form of FORMAT statement 15.
10.8.2 Sequential List-Directed ACCEPT
The list-directed ACCEPT statement transfers data entered from the
terminal into variables specified in the I/O list. The formatting of
the transferred data is controlled by the data types of the items in
the I/O list.
The first form of this statement is:
ACCEPT (FMT=*[,END=s][,ERR=s][,IOSTAT=ios])[iolist]
In this form, the data is transferred from the terminal into the
memory locations identified in the I/O list. Since the transfer is
list-directed, the data is formatted according to the data types of
the items in the I/O list. If no I/O list is included, a line is
skipped.
The second form of this statement operates in the same way as the
10-56
DATA TRANSFER STATEMENTS
first form. The difference in the two forms is in how the
list-directed formatting reference is specified.
The second form of this statement is:
ACCEPT *[,iolist]
In the following example, both forms of the list-directed ACCEPT
statement are used to take information, character-by-character, from
the terminal. This example additionally shows the list-directed TYPE
statement being used to print the ACCEPTed data at the terminal:
PROGRAM ACCTST
ACCEPT *,I,J,K
TYPE *,K,I,J
ACCEPT (FMT=*)G,H,F
TYPE *,H,F,G
END
EXECUTE ACCEPT.FOR
FORTRAN: ACCEPT
ACCTST
LINK: Loading
[LNKXCT ACCTST execution]
23456 9876 12
12, 23456, 9876
12.34 98.16 789.67
98.16000, 789.6700, 12.34000
CPU time 0.2 Elapsed time 40.4
TYPE
Statement
10.9 TYPE STATEMENT
The TYPE statement enables you to output data to your terminal. Use
the TYPE statement only for sequential-access formatted data
transfers. This statement can be used with both FORMAT-statement and
list-directed formatting.
Table 10-8 summarizes all the forms of the TYPE statement.
10-57
DATA TRANSFER STATEMENTS
Table 10-8: Summary of TYPE Statement Forms
10.9.1 Sequential FORMAT-Statement TYPE
This section describes the sequential-access (FORMAT-statement) TYPE
statement.
The first form of this statement is:
TYPE (FMT=f[,ERR=s][,IOSTAT=ios])[iolist]
If you include the I/O list in this form, the data is transferred from
the I/O list to your terminal. The transferred data is formatted
according to the FORMAT specifications given in f.
A blank record is written if the I/O list is not specified, and one of
the following is true:
1. The FORMAT statement is empty.
2. No slash, H, or apostrophe editing descriptors occur alone.
3. No slash, H, or apostrophe editing descriptors precede the
first repeatable edit descriptors.
(See Section 12.4 for more information on format editing).
The second form of this statement operates in the same way as the
first form. The difference between the two forms is in how the FORMAT
reference is expressed.
The second form of this statement is:
10-58
DATA TRANSFER STATEMENTS
TYPE f[,iolist]
In this form, the keyword portion of the FORMAT specifier (FMT=) is
omitted.
The following example shows both forms of the FORMAT-statement TYPE:
A=11.4
Z=13.9
J=5
K=10
TYPE (FMT=5)A,Z,J
5 FORMAT (1X,2F10.2,I5)
TYPE 15,K
15 FORMAT (1X,I10)
END
The following is typed on your terminal upon execution:
LINK: Loading
[LNKXCT TEST40 execution]
11.40 13.90 5
10
CPU time 0.22 Elapsed time 2.00
10.9.2 Sequential List-Directed TYPE
The list-directed TYPE statement transfers data from a program to the
terminal. The formatting of the transferred data is controlled by the
data types of the items in the I/O list.
The first form of this statement is:
TYPE(FMT=*[,ERR=s][,IOSTAT=ios])[iolist]
In this form, the data is transferred from the program to the
terminal. Since the transfer is list-directed, the data is formatted
according to the data types of the items in the I/O list. If no I/O
list is included, a blank record is written.
The second form of this statement operates in the same way as the
first form. The difference between the two forms is in how the
list-directed formatting reference is specified.
The second form of the statement is:
TYPE *[,iolist]
10-59
DATA TRANSFER STATEMENTS
The following example shows both forms of the list-directed TYPE
statement:
A=11.4
Z=13.9
J=5
K=10
TYPE (FMT=*),A,Z,J
TYPE *,K
END
The following is typed on the terminal upon execution:
LINK: Loading
[LNKXCT TEST41 execution]
11.40000, 13,90000, 5
10
CPU time 0.20 Elapsed time 0.87
10-60
DATA TRANSFER STATEMENTS
PRINT
Statement
10.10 PRINT STATEMENT
The PRINT statement transfers data from memory to the line printer.
You can use the PRINT statement only for sequential-access formatted
data transfers. This statement can be used with both FORMAT-statement
formatting and list-directed formatting.
Table 10-9 summarizes all forms of the PRINT statement.
Table 10-9: Summary of PRINT Statement Forms
10.10.1 Sequential FORMAT-Statement PRINT
This section describes the sequential-access (FORMAT-statement) PRINT
statement.
The first form of this statement is:
PRINT (FMT=f[,ERR=s][,IOSTAT=ios])[iolist]
If the I/O list is included in this form, the data identified by the
I/O list is transferred from memory to the line printer. The
10-61
DATA TRANSFER STATEMENTS
formatting of the transferred data is controlled by the FORMAT
specifications given in f.
A blank record is written if the I/O list is not specified, and one of
the following is true:
1. The FORMAT statement is empty.
2. No slash, H, or apostrophe editing descriptors occur alone.
3. No slash, H, or apostrophe editing descriptors precede the
first repeatable edit descriptor.
See Section 12.4.
The second form of this statement operates in the same way as the
first form. The difference between the two forms is in how the FORMAT
specifier is expressed.
The second form of this statement is:
PRINT f[,iolist]
The following example shows two PRINT statements; one with an I/O list
and one without:
A=7.6
B=12.5
C=20.9
PRINT 10
PRINT 20,A,B,C
10 FORMAT (' Beginning of test')
20 FORMAT (' Values are:',3F)
END
The following is printed to the line printer upon execution:
Beginning of test
Values are: 7.6000000 12.5000000 20.9000001
10.10.2 Sequential List-Directed PRINT
This section describes the sequential-access (list-directed) PRINT
statement.
The first form of this statement is:
PRINT (FMT=*[,ERR=s][,IOSTAT=ios])[iolist]
This form of the PRINT statement specifies that the data identified by
10-62
DATA TRANSFER STATEMENTS
the elements of the I/O list is output on the line printer. The data
is formatted according to the data types of the elements in the I/O
list. If no I/O list is included, a blank record is written.
The second form of the list-directed PRINT statement operates in the
same way as the first form. The difference between the two forms is
in the way that the formatting is expressed.
The second form of this statement is:
PRINT *[,iolist]
The following example shows the use of the list-directed PRINT
statement:
D=1
E=40
F=23.3
PRINT *,D,E,F
END
The following is printed to the line printer upon execution:
1.000000, 40.00000, 23.30000
PUNCH
Statement
10.11 PUNCH STATEMENT
The PUNCH statement transfers data from memory to the paper tape
punch. You can use the PUNCH statement only for sequential-access
formatted data transfers. This statement can be used with both
FORMAT-statement formatting and list-directed formatting.
Table 10-10 summarizes all forms of the PUNCH statement.
Table 10-10: Summary of PUNCH Statement Forms
10-63
DATA TRANSFER STATEMENTS
10.11.1 Sequential FORMAT-Statement PUNCH
This section describes the sequential-access (FORMAT-statement) PUNCH
statement.
The first form of this statement is:
PUNCH (FMT=f[,ERR=s][,IOSTAT=ios])[iolist]
If the I/O list is specified in this form, the data identified by the
items in the I/O list are transferred to the paper tape punch. The
formatting of the data is controlled by the FORMAT specifications
given in f.
A blank record is written if the I/O list is not specified, and one of
the following is true:
1. The FORMAT statement is empty.
2. No slash, H, or apostrophe editing descriptors occur alone.
3. No slash, H, or apostrophe editing descriptors precede the
first repeatable edit descriptor.
See Section 12.4.
The second form of this statement operates in the same way as the
first form. The difference between the two forms is in the way that
the format specification is referenced.
The second form of this statement is:
10-64
DATA TRANSFER STATEMENTS
PUNCH f[,iolist]
The following example shows the formatted PUNCH statement:
PUNCH 10,A,B,C
10 FORMAT (3F)
10.11.2 Sequential List-Directed PUNCH
This section describes the sequential-access (list-directed) PUNCH
statement.
The first form of this statement is:
PUNCH (FMT=*[,ERR=s][,IOSTAT=ios])[iolist]
This form of the PUNCH statement transfers the data identified by the
elements of the I/O list to the paper tape punch. Since the transfer
is list-directed, the formatting of the data is controlled by the data
types of the items within the I/O list. If no I/O list is included, a
blank record is written.
The second form of this statement operates in the same way as the
first form. The difference between the two forms is in the way that
the list-directed format reference is written.
The second form of this statement is:
PUNCH *[,iolist]
The following example shows the list-directed PUNCH statement:
PUNCH *,D,E,F
INTERNAL
FILES AND
ENCODE/DECODE
Statements
10.12 INTERNAL FILES AND ENCODE/DECODE STATEMENTS
Internal READ/WRITE statements and ENCODE/DECODE statements are used
for internal I/O.
10-65
DATA TRANSFER STATEMENTS
Table 10-11 summarizes all the forms of the internal READ/WRITE and
ENCODE/DECODE statements.
Table 10-11: Summary of Internal READ/WRITE and ENCODE/DECODE
Statement Forms
10.12.1 Internal READ and WRITE Statements
The internal READ statement transfers data from an internal file to
I/O list elements. The internal WRITE statement transfers data from
I/O list elements to an internal file. Internal READ and WRITE
statements are always formatted.
NOTE
The DECODE statement can be used as an alternative to
the internal READ statement, and the ENCODE statement
can be used as an alternative to the internal WRITE
statement. (See Section 10.3.1.1 for more information
on internal files.)
The internal READ statement has the following forms:
10-66
DATA TRANSFER STATEMENTS
READ (UNIT=un,FMT=f[,END=s][,ERR=s][,IOSTAT=ios])[iolist]
READ (un,FMT=f[,END=s][,ERR=s][,IOSTAT=ios])[iolist]
READ (un,f[,END=s][,ERR=s][,IOSTAT=ios])[iolist]
In the above forms, un is an internal file identifier (see Section
10.4.3.2).
If an I/O list is included in these forms, it specifies that data is
transferred from internal file identifier, un, formatted according to
the specification given by f, and transferred into the elements of the
specified I/O list.
If an I/O list is not included, the input record is skipped. (If the
FORMAT statement specifies slash editing, more than one record can be
skipped. Apostrophe or H editing can cause data transfers to occur to
the FORMAT statement itself. See Section 12.4.)
The following example demonstrates the use of the internal READ
statement:
CHARACTER*9 STRING
STRING = '3.14 6.02'
READ(STRING,10) PI, A
10 FORMAT(F4.2, 1X, F4.2)
WRITE(5,20) PI, A, PI+A
20 FORMAT(' PI=', F6.3, 5X, 'A=', F6.3, 5X, 'PI+A=', F6.3)
STOP
END
The READ statement in this example is an internal file read. It
extracts the two numbers that are encoded in the character variable
STRING, converts the numbers to floating point, and then stores them
into the two variables PI and A. The following is printed at the
terminal when the above program is executed:
EXECUTE IR.FOR
LINK: Loading
[LNKXCT IR execution]
PI= 3.140 A= 6.020 PI+A= 9.160
CPU time 0.19 Elapsed time 0.40
The internal WRITE statement has the following forms:
WRITE (UNIT=un,FMT=f[,ERR=s][,IOSTAT=ios])[iolist]
WRITE (un,FMT=f[,ERR=s][,IOSTAT=ios])[iolist]
WRITE (un,f[,ERR=s][,IOSTAT=ios])[iolist]
10-67
DATA TRANSFER STATEMENTS
If the I/O list is included in these forms, the data specified by the
elements of the I/O list are output to a file on internal file
identifier un. The output data is formatted in this file according to
the FORMAT specifications given in f.
A blank record is written if the I/O list is not specified, and one of
the following is true:
1. The FORMAT statement is empty.
2. No slash, H, or apostrophe editing descriptors occur alone.
3. No slash, H, or apostrophe editing descriptors preceded the
first repeatable edit descriptors.
See Section 12.4.
The following example demonstrates the use of the internal WRITE
statement:
CHARACTER*20 CHARS(3)
INTEGER PHNE(3)
PHNE(1) = 617
PHNE(2) = 481
PHNE(3) = 4054
WRITE(CHARS,10) (I, PHNE(I), I=1,3)
10 FORMAT( 'PHNE(', I1, ')=', I4)
WRITE(5,20) (I, CHARS(I), I=1,3)
20 FORMAT(' Record ', I1, ' of CHARS is "', A20, '"')
STOP
END
The first WRITE statement in the above program is an internal file
write. Since the character variable being written to is a three
element array, the internal file is a file of three records. When
this program is executed, the following is output to the terminal:
EXECUTE IW.FOR
LINK: Loading
[LNKXCT IW execution]
Record 1 of CHARS is "PHNE(1)= 617 "
Record 2 of CHARS is "PHNE(2)= 481 "
Record 3 of CHARS is "PHNE(3)=4054 "
CPU time 0.24 Elapsed time 0.82
10.12.2 ENCODE and DECODE Statements
The DECODE statement can be used as an alternative to an internal
10-68
DATA TRANSFER STATEMENTS
READ, and the ENCODE statement can be used as an alternative to the
internal WRITE.
The ENCODE statement transfers data from the variables of a specified
I/O list into a specified array. ENCODE operations are similar to
those performed by a WRITE statement.
The DECODE statement transfers data from a specified array into the
variables of an I/O list. DECODE operations are similar to those
performed by a READ statement.
ENCODE and DECODE statements have the following forms:
ENCODE (c,f,a[,ERR=s][,IOSTAT=ios])[iolist]
DECODE (c,f,a[,ERR=s][,IOSTAT=ios])[iolist]
where:
c specifies the number of characters in each internal
record of the array. This argument can be any integer
expression, and must be the first specification in the
statement.
NOTE
Five characters per word are stored in the
array without regard to the type of the array.
f specifies either a FORMAT-statement or a numeric array
that contains format specifications. This must be the
second specification.
a specifies the array, array element, variable, or
character substring reference that is to be used in the
transfer operations, and it must contain at least c
characters. More than one element of the array can be
used by the ENCODE/DECODE.
iolist specifies an I/O list of the standard form.
When multiple records are stored by ENCODE or read by DECODE, each new
record starts c characters after the previous record; no CR/LF
(carriage return/line feed) is inserted between records.
NOTE
If the array contains fewer characters than required
by the format and the I/O list, the variables
following the array in memory are used. If the
processing of the I/O list requires more characters in
a single record than are specified by the character
10-69
DATA TRANSFER STATEMENTS
count c, blanks are used.
The following example shows how the ENCODE and DECODE statements are
used:
DIMENSION B(4),A(2)
A(1)=300.45
A(2)=3.0
C='12345'
DO 2 J=1,2
ENCODE(16,10,B)J,A(J)
10 FORMAT(1X,'A(',I1,') = ', F8.2)
10-70
DATA TRANSFER STATEMENTS
5 TYPE 11,B
11 FORMAT(4A5)
2 CONTINUE
DECODE(5,12,C)B
12 FORMAT(3F1.0,1X,F1.0)
TYPE 13,B
13 FORMAT(4F5.2)
END
During the first iteration of the DO loop, the ENCODE statement has
transferred the contents of variable J and array element A(1) into
array B. The formatting of the data being transferred is specified by
the FORMAT statement at line 10.
After the first iteration of the DO loop, the contents of array B are:
B(1) = ' A(1)'
B(2) = ' = '
B(3) = '300.4'
B(4) = '5 '
The TYPE statement at line 5 types array B on the terminal during the
first iteration of the DO loop.
During the second iteration of the DO loop, the data is transferred
from variable J and array element A(2) into array B. After the second
iteration, the contents of array B are:
B(1) = ' A(2)'
B(2) = ' = '
B(3) = ' 3.0'
B(4) = '0 '
The TYPE statement at line 5 types array B on the terminal during the
second iteration of the DO loop.
The DECODE statement:
1. Extracts the digits 1, 2, and 3 from C
2. Converts them to floating-point values
3. Stores them in B(1), B(2), and B(3)
4. Skips the next character (the digit 4)
5. Extracts the digit 5 from C
10-71
DATA TRANSFER STATEMENTS
6. Converts it to a floating-point value
7. Stores the value in B(4)
The following shows what is printed at the terminal when the above
program is executed:
EXECUTE T.FOR
LINK: Loading
[LNKXCT T execution]
A(1) = 300.45
A(2) = 3.00
1.00 2.00 3.00 5.00
CPU time 0.1 Elapsed time 0.8
|
|
| DELETE (TOPS-20)
| Statement
|
|
|
|
|
| 10.13 DELETE STATEMENT (TOPS-20 RMS)
|
| The DELETE statement deletes records from RMS relative and indexed
| files. It logically removes the appropriate record from the specified
| file by locating the record and marking it as a deleted record. The
| position occupied by the deleted record becomes available so that a
| new record can be written into that position.
|
| The DELETE statement is illegal for RMS files with sequential
| organization, and for non-RMS files.
|
| Table 10-12 summarizes all forms of the DELETE statement.
|
|
| Table 10-12: Summary of DELETE Statement Forms
|
|
10-72
DATA TRANSFER STATEMENTS
| 10.13.1 Current-Record DELETE
|
| The current-record DELETE statement has the following forms:
|
| DELETE (UNIT=un[,ERR=s][,IOSTAT=ios])
|
| DELETE (un[,ERR=s][,IOSTAT=ios])
|
| This form of the DELETE statement deletes the last record from an
| indexed or sequentially-accessed relative file that has been
| successfully accessed by a previous READ or FIND statement. The
| current-record DELETE is the only form of the DELETE statement that is
| permitted for indexed files.
|
|
|
| 10.13.2 Direct-Access DELETE
|
| The direct-access DELETE statement has the following forms:
|
| DELETE (UNIT=un,REC=rn[,ERR=s][,IOSTAT=ios])
|
| DELETE (un,REC=rn[,ERR=s][,IOSTAT=ios])
|
| DELETE (un'rn[,ERR=s][,IOSTAT=ios])
|
| The direct-access DELETE is permitted only for direct-access RMS
| relative files. It deletes the record specified by rn. After a
| direct-access DELETE statement, any associate variable is set to the
| next record number.
|
| The alternative form of this type of DELETE statement (the last form
10-73
DATA TRANSFER STATEMENTS
| shown) operates in the same way as the first two forms. The
| difference between the forms is in the way that the unit and the
| record are specified. In this form, the unit and record references do
| not contain the keywords UNIT= and REC=. Instead the unit number is
| specified first; a single quote (') is specified next; then the record
| number is specified last.
|
|
|
|
| REWRITE (TOPS-20)
| Statement
|
|
|
|
|
| 10.14 REWRITE STATEMENT (TOPS-20 RMS)
|
| The REWRITE statement transfers data from internal storage to the
| current record (the record most recently accessed by a READ or FIND
| statement) of an RMS indexed or relative file. The REWRITE statement
| can be formatted or unformatted.
|
| Table 10-13 summarizes all forms of the REWRITE statement.
|
|
| Table 10-13: Summary of REWRITE Statement Forms
|
|
10-74
DATA TRANSFER STATEMENTS
| 10.14.1 Formatted REWRITE
|
| The formatted REWRITE statement has the following forms:
|
| REWRITE (UNIT=un,FMT=f[,ERR=s][,IOSTAT=ios]) [iolist]
|
| REWRITE (un,f[,ERR=s][,IOSTAT=ios]) [iolist]
|
| Note that a WRITE to an indexed file always writes a new record. If
| the primary key for the new record is changed, an error results.
| Records rewritten with the REWRITE statement cannot exceed the length
| of the record being updated, or an error results.
|
| An example of the use of a formatted REWRITE statement follows:
|
| REWRITE (1,10,ERR=99) NAME, AGE, BIRTH
| 10 FORMAT (A16,I2,A8)
|
| In this example, the REWRITE statement updates the current record
| contained in the indexed file connected to logical unit 3 with the
| values represented by NAME, AGE, and BIRTH.
|
|
|
| 10.14.2 Unformatted REWRITE Statement
|
| The unformatted REWRITE statement has the following forms:
|
| REWRITE (UNIT=un[,ERR][,IOSTAT=ios]) [iolist]
|
| REWRITE (un[,ERR][,IOSTAT=ios]) [iolist]
|
| The unformatted REWRITE statement retrieves binary values from
| internal storage and writes those values to an existing record in a
| RMS file with indexed or relative organization. The values are not
| translated.
|
|
|
|
| UNLOCK (TOPS-20)
| Statement
|
|
|
|
|
| 10.15 UNLOCK STATEMENT (TOPS-20)
|
| The UNLOCK statement unlocks a record in a RMS relative or indexed
| file locked by a previous READ or FIND statement, without performing
| any other I/O operations. If no record is locked, the operation has
10-75
DATA TRANSFER STATEMENTS
| no effect. This statement is illegal for RMS sequential and non-RMS
| files.
|
| Table 10-14 summarizes all forms of the UNLOCK statement.
|
|
| Table 10-14: Summary of UNLOCK Statement Forms
|
|
|
|
| UNLOCK (UNIT=un[,ERR=s][,IOSTAT=ios])
|
| UNLOCK (un[,ERR=s][,IOSTAT=ios])
|
| UNLOCK un
10-76
CHAPTER 11
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
11.1 FILE-CONTROL STATEMENTS
Prior to transferring any data using one of the forms of data transfer
statements, you can establish a connection between a logical unit and
a file by using the OPEN statement. After the completion of a data
transfer, you can terminate the connection between the logical unit
and the file before ending the program by using the CLOSE statement.
The OPEN statement enables you to explicitly connect a logical unit to
a file prior to the first data transfer, and also to specify a variety
of characteristics about the file and the data transfers.
After the last data transfer is completed, the CLOSE statement enables
you to explicitly disconnect the logical unit from the file and,
optionally, to specify a variety of characteristics about the CLOSE.
If you do not precede an I/O statement with an OPEN statement, FOROTS
automatically performs an "implicit OPEN" (see Section 11.2.1).
Similarly, if you do not specify a CLOSE statement to explicitly
disconnect a file from a logical unit, FOROTS performs an "implicit
CLOSE" (see Section 11.4.1) when your program terminates.
You need not specify the OPEN and CLOSE statements if the actions
performed by the implicit OPEN or CLOSE are satisfactory.
11-1
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
OPEN
Statement
11.2 OPEN STATEMENT
The OPEN statement is used to specify characteristics of a file that
you wish to read or write. An example of an OPEN statement is:
OPEN (UNIT=20,FILE='MYDATA.DAT')
The specifiers inside the parentheses give information about the file
and determine how the file is opened.
The UNIT specifier (in the example above, "UNIT=20") is required in an
OPEN statement. All other specifiers are optional, including the FILE
specifier in the example shown above. You can supply many other
optional specifiers (see Section 11.3 for a description of OPEN
statement specifiers). The order in which the specifiers appear does
not affect the execution of the OPEN statement.
By using the OPEN specifiers, you are able to define certain
characteristics of each data transfer, including:
1. The name of the data file
2. The type of access required
3. The data format of the file
4. The disposition of the data file
5. The data file record and block sizes
In addition, a DIALOG argument permits you to establish a dialog mode
of operation when the OPEN statement containing it is executed. In a
dialog mode, interactive terminal/program communication is
established, enabling the user to define or redefine the values of the
OPEN statement specifiers.
When a file is open for output (STATUS='NEW' or ACCESS='SEQOUT'), a
null file is created on the device specified by FILE= or DEVICE=, or
if none, the first structure in the job's search list.
An OPEN statement is referred to as a "deferred" OPEN statement if
both of the following are true:
11-2
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
o The OPEN statement specifies STATUS='UNKNOWN' (or does not
specify a STATUS value).
o The OPEN statement specifies ACCESS='SEQINOUT' or
'SEQUENTIAL' (or does not specify an ACCESS value).
The actual opening of the file is deferred until the first data
transfer statement (READ, WRITE, PRINT, PUNCH, or SKIPRECORD). The
actual opening of the file means the determination of the physical
device, and for TOPS-20, the generation number (if not explicitly
specified).
If the first data transfer statement is a READ or SKIPRECORD, the
first file that matches the file specification given in the OPEN
statement is opened. If no file exists that matches the file
specification given, a null file is created on the device specified by
FILE= or DEVICE=, or if none, the first structure in the job's search
list. The file is positioned as if a READ or SKIPRECORD statement had
been executed, and an end-of-file error will be generated (see END=,
Section 10.4.6).
If the first data transfer statement is a WRITE, PRINT, or PUNCH
statement, a new file (with a new generation on TOPS-20) will be
created on the device specified by FILE= or DEVICE=, or if none, the
first structure in the job's search list.
If the file specified in the OPEN statement does not exist, and either
a CLOSE statement is executed or the program runs to completion, a
null file is created on the device specified by FILE= or DEVICE=, or
if none, the first structure in the job's search list.
11.2.1 Implicit OPEN
When the OPEN statement has not been executed before a data transfer
that references the unit number, an implicit OPEN is performed.
An implicit OPEN has almost exactly the same effect as if you had put
an OPEN statement with the following format in the program just before
the data transfer statement:
OPEN (UNIT=un,STATUS='UNKNOWN',FORM=fm)
where:
un is the unit number specified in the data transfer
statement.
fm is 'UNFORMATTED' if the data transfer statement is an
unformatted READ or WRITE statement; otherwise fm is
'FORMATTED'.
11-3
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
In addition, if the data transfer statement has an ERR specifier, the
implicit OPEN has this same qualifier included. This is also true of
the IOSTAT specifier.
NOTE
The default for the BLANK specifier is different
depending on whether the OPEN is implicit or explicit
(see Section 11.3.3).
11.2.2 OPEN on a Connected Unit
If the OPEN statement contains a STATUS=OLD specifier (see Section
| 11.3.29), then its action depends on whether a file is already OPEN on
the unit, and whether the file specified by the OPEN is the same file
that is currently on the unit. If the file specified by the OPEN is
different from the OPEN file, the connected file is closed and the new
file is opened. If the file specified by the OPEN is the same as the
connected file, the file is not closed, and the file pointer is not
moved. This action is not affected by the /F66 compiler switch
(described in Chapter 16).
11.3 OPEN STATEMENT SPECIFIERS
All of the OPEN statement specifiers are optional, except the UNIT
specifier, which is required. Some specifiers have default values
that can depend on the unit number or the values of other specifiers.
Table 11-1 summarizes the specifiers in the OPEN statement and the
type of value required by each. A section number is provided to refer
to detailed descriptions of each specifier. The CLOSE statement
specifiers are summarized in Table 11-5.
11-4
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
Table 11-1: Summary of OPEN Statement Specifiers and Arguments
11-5
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
NOTE
For compatibility with previous versions of
FORTRAN-10/20, you can specify a numeric array name as
the value of each of the following specifiers:
DIALOG=
DIRECTORY
NAME
When a numeric array name is used, FOROTS assumes that
it contains a string of characters terminated by a
null character.
In addition, you can specify a numeric variable as the
value of the DEVICE and FILE specifiers. If the
variable is single precision, FOROTS assumes that it
contains 5 characters; if it is double precision,
FOROTS assumes that is contains 10 characters.
The use of numeric array names and numeric variables
in place of character variables is a nonstandard
feature.
11-6
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
ACCESS
Specifier
11.3.1 ACCESS Specifier
The ACCESS specifier describes the type of data transfer statements
allowed. Records within files can be accessed directly (randomly),
| sequentially, or by specified key (RMS).
The form of the ACCESS specifier is:
ACCESS = acc
where:
acc is a character expression having a value equal to one of
the following:
'SEQIN'
'SEQOUT'
'SEQINOUT'
'SEQUENTIAL'
'DIRECT'
'RANDOM'
'RANDIN'
'APPEND'
| 'KEYED'
ACCESS has a number of arguments, each of which specifies a method of
data access. SEQUENTIAL is the default access unless the device
(UNIT) opened is a read-only device, in which case the default is
SEQIN. If the device opened is a write-only device, the default
access is SEQOUT.
The arguments to the ACCESS specifier are:
SEQIN (Implies STATUS='OLD') The specified data file is
opened for read-only sequential access. When
ACCESS='SEQIN' is specified, it is equivalent to
specifying ACCESS='SEQUENTIAL' and READONLY (see
| Section 11.3.32).
SEQOUT The specified data file is opened for output and
sequential access. If the specified file already
exists, it is superseded (TOPS-10), or a new
generation is created (TOPS-20).
11-7
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
SEQUENTIAL The specified data file is opened for sequential
access. Records can be read from or written to the
file in sequential order. However, when a record is
written to the file, it becomes the last record of
the file. Any data following that record becomes
inaccessible.
Records can also be written to the file and then
read, as long as a device-positioning statement
(BACKSPACE or REWIND, Section 11.8) is used before
the READ statement.
SEQINOUT Same as SEQUENTIAL
DIRECT The specified data file may be read from and/or
written to in units of fixed-length records. The
record to be accessed next is specified in the data
transfer statement by a record number.
The relative position of each record is independent
of the previous READ or WRITE statement. The RECL
| specifier (see Section 11.3.33) is required for
random-access operations. You must specify a disk
device when the DIRECT argument is used.
RANDIN (Implies STATUS='OLD') The specified data file is
opened for read-only direct access. More than one
user can read the same file at the same time with
ACCESS='RANDIN'. When ACCESS='RANDIN' is specified,
it is equivalent to specifying ACCESS='RANDOM' and
| READONLY (see Section 11.3.32).
RANDOM Same as DIRECT
APPEND The specified file is opened for sequential
write-only access. APPEND is the same as SEQOUT
except that the file is positioned at its end after
the OPEN statement. Reading an APPEND mode file is
illegal. REWIND and BACKSPACE are illegal for files
opened with APPEND access.
| KEYED The specified data file is an RMS indexed file
| opened for either random keyed access or sequential
| access. The file is accessed by a specified key.
| Invokes RMS (as if ORGANIZATION='INDEXED' is
| specified).
ASSOCIATEVARIABLE
Specifier
11-8
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
11.3.2 ASSOCIATEVARIABLE Specifier
This specifier enables you to declare a variable whose value is the
number of the next record that will be read from or written to the
| file. For RMS files, this specifier is ignored unless
| ACCESS='DIRECT'.
For example, after the execution of an OPEN statement and prior to the
first data transfer, the associate variable is set to 1.
In a data transfer after the first record is transferred, the value of
the associate variable is 2.
The form of the ASSOCIATEVARIABLE specifier is:
ASSOCIATEVARIABLE= Integer variable or integer array element
If you are using the ASSOCIATEVARIABLE specifier in a program that
makes use of the LINK overlay facility, please read the paragraphs
that follow.
If the variable you specify as the ASSOCIATEVARIABLE is declared in a
FORTRAN subroutine, then that subroutine must be loaded in the root
link of the overlay structure. If the subroutine cannot be loaded in
the root link of the overlay structure, declare your ASSOCIATEVARIABLE
in a COMMON statement so that the ASSOCIATEVARIABLE will operate
properly.
The reasons for these steps are:
1. When the overlay facility is used to load FORTRAN modules,
the local variables in the modules are grouped with the
routine in which they are declared.
2. When FORTRAN subroutines are loaded by the overlay facility,
they are divided into sets called overlay links.
3. Only one overlay link, the one specified to be the root link,
is always resident in memory. The other overlay links are
read in memory as required.
Accessing a file opened with an ASSOCIATEVARIABLE changes the value of
the specified variable. If this variable is in a nonresident overlay
link when the access is made, program execution produces unpredictable
results. Moreover, this variable is reset to zero each time its
overlay link is removed from memory.
Only variables declared in routines loaded into the root link are
always resident. Variables declared in COMMON statements and those
declared in the main program are always resident and can always be
used as an associate variable.
11-9
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
NOTE
For more information on the LINK overlay facility, see
the LINK Programmer's Reference Manual, and Chapter 15
of this manual.
BLANK
Specifier
11.3.3 BLANK Specifier
The BLANK specifier applies only when reading formatted
(FORMAT-statement) numeric fields that have a field width specified.
BLANK enables you to specify how blanks in formatted numeric fields
are treated in a read transfer (either as zero or ignored).
The form of the BLANK specifier is:
BLANK = blnk
where:
blnk is a character expression having a value equal to either
'NULL' or 'ZERO'.
The arguments to the BLANK specifier are:
NULL specifies that all blank characters within numeric
formatted input fields are ignored. The exception is
that a field of all blanks has a value of zero.
ZERO specifies that all blanks are treated as zeros.
If an OPEN statement is executed and the BLANK specifier is not given,
the default is BLANK='NULL'.
If no explicit OPEN statement is executed before a data transfer on a
unit, the default is BLANK='ZERO' for all devices except terminals.
For terminals, the default is always BLANK='NULL' regardless of
whether or not the OPEN statement is given.
The BLANK specifier is overridden if a corresponding data transfer
statement references a format list that contains either the BN or BZ
descriptor. In this case, the BN or BZ descriptor in the format list
overrides the setting in the OPEN statement until the end of the
format list, or until the setting is changed within the format list.
11-10
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
(The BN or BZ descriptors are described in Section 12.4.9.)
Example:
OPEN(UNIT=1,DEVICE='DSK',FILE='FOO.DAT',BLANK='ZERO')
READ(1,10)K
10 FORMAT(I5)
CLOSE(UNIT=1)
OPEN(UNIT=1,DEVICE='DSK',FILE='FOO.DAT',BLANK='NULL')
READ(1,10)L
CLOSE(UNIT=1)
END
In the above example, if FOO.DAT contains 123bb, K has the value 12300
and L has the value 123.
BLOCKSIZE
Specifier
11.3.4 BLOCKSIZE Specifier
The BLOCKSIZE specifier enables you to specify a physical storage
block size for magnetic tape files.
NOTE
BLOCKSIZE specifies the physical record length, and
RECL(RECORDSIZE) specifies the logical record length.
The argument is an integer expression, and for CORE-DUMP tape format,
the value assigned represents the number of words in the physical
block. For INDUSTRY tape format, the value represents the number of
bytes in the physical block. (See the TAPEFORMAT specifier, Section
| 11.3.37.)
The form of the BLOCKSIZE specifier is:
BLOCKSIZE= Integer expression
BUFFERCOUNT
Specifier
11-11
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
11.3.5 BUFFERCOUNT Specifier
The BUFFERCOUNT specifier enables you to define the number of I/O
buffers used in the data transfer.
The BUFFERCOUNT is the number of pages used in disk transfers, and is
ignored for nondisk transfers.
| For RMS files, BUFFERCOUNT specifies the MBF (Multi-Buffer Count) for
| RMS internal buffering.
The form of the BUFFERCOUNT specifier is:
BUFFERCOUNT= Integer expression
If a BUFFERCOUNT is not specified, or is assigned a value of zero:
|
| o For non-RMS files, the buffercount is four pages.
|
| o For RMS files, the RMS default is used.
|
NOTE
If MODE='DUMP' is specified, BUFFERCOUNT is ignored.
The BUFFERCOUNT specifier does not affect the operation of the
program, but it can affect execution time and memory requirements.
For random I/O, the buffercount specifies the maximum number of
buffers which are in memory (not yet written to disk) during I/O
operations.
NOTE
For TOPS-20 extended addressing, all I/O buffers must
fit in FOROTS's section.
11-12
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
|
|
| BYTESIZE
| Specifier
|
|
|
|
|
| 11.3.6 BYTESIZE Specifier
|
| The BYTESIZE specifier determines the integer byte size for the file.
| For existing RMS files, this value must agree with the actual byte
| size of the file.
|
| The form of the BYTESIZE specifier is:
|
| BYTESIZE = Integer expression
|
| If no BYTESIZE is specified, FOROTS defaults to 7 for TOPS-10/20 files
| (defaults to 8 for VMS files). If BYTESIZE is specified for a remote
| VMS file, the bytesize must be 8. If BYTESIZE is specified when
| creating a new TOPS-20 RMS indexed file that has CHARACTER keys
| defined, the byte size must be 7.
CARRIAGECONTROL
Specifier
11.3.7 CARRIAGECONTROL Specifier
The CARRIAGECONTROL specifier enables you to decide how the first
character of each record encountered during an output data transfer
operation is treated. (Section 12.2.3 describes carriage-control
specifiers.)
The form of the CARRIAGECONTROL specifier is:
CARRIAGECONTROL = cc
where:
cc is a character expression having a value equal to one of
the following:
'FORTRAN'
'LIST'
11-13
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
'TRANSLATED'
'DEVICE'
| 'NONE'
The arguments to the CARRIAGECONTROL specifier are:
FORTRAN specifies that the FORTRAN data file attribute is
set in the file's access information, so that when
the file is printed, the first character of each
record is replaced with a carriage return and the
corresponding printer-control vertical motion
character(s) (see Table 12-3). The record
terminator at the end of the record will be
discarded.
LIST specifies that the first character is output with no
replacement.
| Since RMS sequential files do not have record
| terminators, when LIST is used, you cannot specify
| that a record should not have a CRLF added when it
| is printed. Thus, the dollar sign format edit
| descriptor, which eliminates the CRLF after a
| record, has no effect for RMS files with LIST
| specified.
TRANSLATED specifies that the first character of each record is
replaced with a carriage return and the
corresponding printer-control vertical motion
character(s) (see Table 12-3). No record terminator
is written at the end of the record.
Note that the last data record in the file has no
ending carriage return/line feed sequence unless a
blank record is written.
For fixed-length files, TRANSLATED is treated as
LIST.
| For RMS files, TRANSLATED is treated as FORTRAN.
DEVICE specifies that the first character will only be
replaced for a carriage-control device (such as LPT
or TTY).
The default value is CARRIAGECONTROL='DEVICE'.
NOTE
The line printer software assumes that the first
character of all data files is a carriage-control
character if the file has the extension .DAT or if the
/FILE:FORTRAN switch is specified.
11-14
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
|
|
| DEFAULTFILE (TOPS-20)
| Specifier
|
|
|
|
|
| 11.3.8 DEFAULTFILE Specifier (TOPS-20)
|
| The DEFAULTFILE specifier defines a default file specification string.
| If you do not specify either FILE or DEFAULTFILE, FORTRAN uses the
| default value FORnn.DAT, where nn is the unit number with leading
| zeros.
|
| The DEFAULTFILE specifier can be used in place of, or in addition to
| the FILE or NAME specifier. If DEFAULTFILE is used without FILE or
| NAME, it replaces the FILE or NAME specifier. If DEFAULTFILE is used
| with FILE or NAME, the DEFAULTFILE file specification is merged with
| the FILE or NAME value to form the full file specification.
|
| The form of the DEFAULTFILE specifier is:
|
| DEFAULTFILE = ce
|
| where:
|
| ce is a character expression that contains a default file
| name specification string.
|
| You can specify defaults for one or more of the following file
| specification components:
|
| o node (if the file specification contains a node name, RMS
| will be used to access the file)
|
| o device
|
| o directory
|
| o filename
|
| o filetype
|
| o file generation number
|
| o network attributes
|
| When you specify any of the above components in the FILE or NAME
| specifier, they override those values specified in DEFAULTFILE. Since
| FOROTS processes DEFAULTFILE, FILE, and NAME in that order, the
| components specified in NAME supercede all previous corresponding
11-15
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
| components.
DENSITY
Specifier
11.3.9 DENSITY Specifier
The DENSITY specifier is ignored except when used with magnetic tape;
it permits you to specify the tape density. If you do not specify a
tape density, FORTRAN assumes that you have set the density at monitor
level or that you are satisfied with the system default for the
device.
The form of the DENSITY specifier is:
DENSITY = dens
where:
dens is a character expression having a value equal to one of
the following:
'200'
'556'
'800'
'1600'
'6250'
'SYSTEM'
SYSTEM specifies that the density is the default density for the
magnetic tape device being used.
DEVICE
Specifier
11.3.10 DEVICE Specifier
The DEVICE specifier enables you to specify the name of the device
involved in the data transfer. A logical name always takes precedence
11-16
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
over a physical name. The DEVICE arguments can specify I/O devices
located at remote stations, as well as logical devices.
The form of the DEVICE specifier is:
DEVICE= Character expression
If you omit this option, the logical name un (where un is the decimal
unit number) is tried. If this is not successful, the standard
(default) device associated with the unit is used (see Table 10-3).
DIALOG
Specifier
11.3.11 DIALOG Specifier
The DIALOG specifier enables you to type in additional OPEN specifiers
when the OPEN statement is actually executed.
If the DIALOG specifier is found in an OPEN list, then each time the
OPEN statement is executed FOROTS suspends execution and prompts the
terminal with an asterisk.
The form of the DIALOG specifier is:
DIALOG
You can respond to the asterisk prompt by entering a file
specification, DIALOG switches (see below), or a file specification
followed by DIALOG switches. The file specification may be a full
file specification including the device, directory name, and so on.
NOTE
A DIALOG switch is any OPEN specifier (except DIALOG,
DIALOG=, UNIT, NAME, FILE, IOSTAT, or ERR) preceded by
a slash (/).
For example, when FOROTS enters DIALOG mode, you can type a string
such as:
*DSK:FOO.BAR/MODE:BINARY/ACCESS:DIRECT
11-17
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
DIALOG=
Specifier
11.3.12 DIALOG= Specifier
The DIALOG= specifier enables you to include all or a portion of the
OPEN specifiers in a character expression. The contents of the
character expression are interpreted as if you had given the DIALOG
specifier (see above); and, when the asterisk prompt was given, you
had typed in the same string as is contained in the character
expression, followed by a carriage return.
The form of the DIALOG= specifier is:
DIALOG= Character expression
Example:
OPEN(UNIT=1,DIALOG='DSK:FOO.BAR/ACCESS:SEQOUT/MODE:ASCII')
I=22
WRITE(1,100)I
100 FORMAT(I5)
END
DIRECTORY (TOPS-10)
Specifier
11.3.13 DIRECTORY Specifier (TOPS-10)
On TOPS-10, the DIRECTORY specifier is ignored except for disk files.
It specifies the location of the User File Directory (UFD) and,
optionally, the Sub File Directory (SFD), either of which can contain
the file specified in the OPEN statement.
The form of the DIRECTORY specifier is:
DIRECTORY= Character expression
The UFD is the directory in which a user's files are stored; the SFD
exists within the UFD. An SFD is often used to group files into
separate subdirectories.
11-18
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
The following is a sample of the UFD and SFD specification:
10,7,SFDA,SFDB
In the sample specification, 10,7 is the project-programmer number.
This is an adequate directory specification if the file is in the UFD
specified by 10,7. The SFDA and SFDB specify two levels of subfile
directories. The complete directory specification indicates that the
file is located in subfile directory SFDB. As indicated, the path to
SFDB is through the UFD 10,7 and through the SFD SFDA.
NOTE
Refer to the TOPS-10 Monitor Calls Manual for a
complete description of directories and multilevel
directory structures.
The following is an example of a character expression specification:
DIRECTORY='10,7,SFD1,SFD2,SFD3'
Project SubFile
Programmer Directory
Number Path
The following is an example of how to assemble a specification from
individual elements:
CHARACTER*10 PROJ,PROG,PATH1,PATH2
CHARACTER*1 COMM
PROJ= '10'
PROG= '7'
| PATH1= 'SFDA'
| PATH2= 'SFDB'
COMM= ','
OPEN(UNIT=1,DIRECTORY=PROJ//COMM//PROG//COMM//PATH1//COMM//PATH2)
The above specification is equivalent to the following character
expression:
'10,7,SFDA,SFDB'
DIRECTORY (TOPS-20)
Specifier
11-19
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
11.3.14 DIRECTORY Specifier (TOPS-20)
On TOPS-20, the DIRECTORY specifier is ignored except for disk files.
The DIRECTORY specifier enables you to define the path through the
directory structure to a file specified in the OPEN statement.
The form of the DIRECTORY specifier is:
DIRECTORY= Character expression
The argument to the DIRECTORY specifier is a character expression
whose elements comprise the directory path specification, for example:
OPEN(UNIT=22,DIRECTORY= 'GUEST')
!Looks for DSK:<GUEST>FOR22.DAT
or
CHARACTER*12 ID
ID= 'GUEST.CLASS3'
OPEN(UNIT=22,DIRECTORY=ID)
!Looks for DSK:<GUEST.CLASS3>FOR22.DAT
DISPOSE
Specifier
11.3.15 DISPOSE Specifier
The DISPOSE specifier enables you to specify an action to occur when
the file is closed.
The form of the DISPOSE specifier is:
DISPOSE = dis
where:
dis is a character expression having a value equal to one of
the following:
'KEEP'
'SAVE'
'DELETE'
'EXPUNGE'
'PRINT'
'LIST'
11-20
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
'PUNCH'
The DISPOSE specifier must have one of the following values:
KEEP Specifies that the file is to be left where the OPEN
statement specifies. DISPOSE='KEEP' is the default.
SAVE Same as KEEP.
DELETE Specifies on TOPS-10 that, if the device is either a
DECtape or disk, delete the file; otherwise, take no
action.
On TOPS-20, if the device involved is a disk, delete
the file; otherwise, take no action.
EXPUNGE On TOPS-10, same as DELETE. On TOPS-20, if the device
involved is a disk, expunge the file; otherwise, take
no action.
PRINT Specifies that the file will be printed and kept. The
file must be on disk.
LIST Specifies that the file will be printed and deleted.
The file must be on disk.
PUNCH Specifies that the file will be punched on the paper
tape punch and kept. The file must be on disk.
ERR
Specifier
11.3.16 ERR Specifier
The ERR specifier enables you to designate a statement number of an
executable statement, in the current program unit, to which control
passes if an error occurs during the execution of an I/O statement.
If an error occurs and no ERR specifier or IOSTAT specifier (see
| Section 11.3.20) is supplied, the program types an error message. If
the program is running under batch, it is aborted.
If the program is not running under batch, it enters DIALOG mode after
processing all of the other specifiers, as if you had supplied the
| DIALOG specifier (see Section 11.3.11). This is true regardless of
whether or not the OPEN statement was explicitly executed or implied
11-21
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
by the execution of the first data transfer statement for a unit.
The form of the ERR specifier is:
ERR= s
where:
s is the number of an executable statement to which program
control passes if an error occurs during the execution of
the statement that includes the ERR specifier.
The subroutine ERRSNS can be called to pinpoint the error. See
Appendix D for FOROTS error values returned by ERRSNS.
FILE
Specifier
11.3.17 FILE Specifier
The FILE specifier enables you to name the file involved in the data
transfer operation. You can specify a full file specification.
The form of the FILE specifier is:
FILE= Character expression
The value of the character expression is any legal TOPS-10 or TOPS-20
file specification. (See the TOPS-10 Operating System Commands Manual
or the TOPS-20 User's Guide.)
If you omit the period and extension, the extension .DAT is assumed.
If just the extension is omitted, a null extension is assumed. Thus,
if you want a filename without an extension, remember to use the
period.
If a filename is not specified, a default name is generated that has
the form:
FORxx.DAT
where:
xx is the FORTRAN logical unit number (decimal) or the logical
unit name for the default statements ACCEPT, PRINT, PUNCH,
READ, WRITE, or TYPE.
11-22
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
| 11.3.17.1 Remote File Specifications (TOPS-20) - A remote file
| specification is a file specification that contains a nodename and
| optionally, network access information in the following format:
|
| node::dev:<dir>file[.ext.gen;USERID:id;PASSWORD:pwd;ACCOUNT:act]
|
| USERID, PASSWORD, and ACCOUNT attributes may be optional depending on
| the default access privileges of the remote directory or file. DEVICE
| may be optional depending on the defaults in effect at the remote
| host. When the file specification is remote, RMS is used to access
| the file. For all remote access, RMS uses the default protection of
| the remote directory or system.
|
| NOTE
|
| FORTRAN supports remote file access only to other
| TOPS-20 and VMS systems. Note that logical names
| defined at the local host will not be expanded or
| interpreted by FORTRAN/RMS before transmission to the
| remote host.
|
FILESIZE
(INITIALIZE)
Specifier
(TOPS-10 only)
11.3.18 FILESIZE (INITIALIZE) Specifier (TOPS-10 Only)
The FILESIZE (or INITIALIZE) specifier is used for disk operations
only. It enables you to estimate the number of words that an output
file is going to contain.
The form of the FILESIZE specifier is:
FILESIZE= Integer expression
The value assigned as a FILESIZE argument can be a integer expression,
and is rounded up to the next higher block boundary (multiple of 128).
The value specified by FILESIZE= is used as an estimate only. The
effect of FILESIZE= is to help the monitor try to choose the best
place on the disk to put the file.
FORM
11-23
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
Specifier
11.3.19 FORM Specifier
The FORM specifier designates whether the records in a data transfer
operation are formatted or unformatted. You should not mix formatted
(character) and unformatted (binary) records in the same file.
The form of the FORM specifier is:
FORM = ft
where:
ft is a character expression having a value equal to
'FORMATTED' or 'UNFORMATTED'.
The arguments to the FORM specifier are:
FORMATTED specifies that the records being transferred
contain character (formatted) data.
UNFORMATTED specifies that the records being transferred
contain binary (unformatted) data.
If FORM is not specified and MODE is 'ASCII' or 'LINED', the default
value for FORM is 'FORMATTED'. Otherwise, if MODE is 'BINARY',
'IMAGE', or 'DUMP' (TOPS-10 only), the default value for FORM is
'UNFORMATTED'.
If both FORM and MODE are specified and they are incompatible, then
DIALOG mode is entered, and you are asked to correct the
incompatibility. In the following example, MODE='BINARY' and
FORM='FORMATTED' are specified in the same OPEN statement. As shown
below, when the program is executed, interactive DIALOG mode is
automatically entered to enable the user to correct the
incompatibility.
PROGRAM TRIMP
OPEN(UNIT=1,MODE='BINARY',FORM='FORMATTED')
WRITE(UNIT=1,FMT=101)
101 FORMAT(1X,'This is a test.')
END
EXECUTE TRIMP
LINK: Loading
[LNKXCT TRIMP execution]
?OPEN unit 1 DSK:FOR01.DAT at MAIN.+4 in TRIMP (PC 165)
?Incompatible attributes /MODE:BINARY /FORM:FORMATTED
11-24
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
[Enter correct file specs]
*/MODE:ASCII
CPU time 0.3 Elapsed time 11.4
TYPE FOR01.DAT
This is a test.
If neither FORM nor MODE is specified the default value for FORM
depends on the access. If the access is SEQUENTIAL (or is defaulted),
the default for FORM is FORMATTED. If the access is DIRECT or RANDOM,
the default for FORM is UNFORMATTED.
NOTE
For ASCII devices (line printer, plotter, terminal,
industry magnetic tape), the FORM= specifier has no
meaning and is ignored; both formatted and unformatted
data transfers are legal (see Section 10.3.3).
IOSTAT
Specifier
11.3.20 IOSTAT Specifier
The IOSTAT specifier identifies an integer variable that is used to
store the I/O status code during the execution of a statement.
The form of the IOSTAT specifier is:
IOSTAT= Integer variable or integer array element
If no error occurs during the execution of the statement, the defined
variable is set to zero.
If an error does occur during the execution of the statement, the
defined variable is assigned a positive integer value that corresponds
to the number of the FOROTS error that occurred (see Appendix D for
FOROTS error codes).
When an error occurs, no error message is typed; instead, the program
either continues at the ERR= statement number (if the ERR specifier is
included), or continues at the statement immediately following the
OPEN statement (if no ERR specifier is included).
|
|
11-25
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
| KEY (TOPS-20)
| Specifier
|
|
|
|
|
| 11.3.21 KEY Specifier (TOPS-20)
|
| The KEY specifier defines the keys used by RMS to access records in an
| indexed file.
|
| For new RMS indexed files the KEY specifier is mandatory. The
| presence of KEY= causes RMS to be invoked, whether or not
| ORGANIZATION= is specified. If the KEY specifier is present without
| the ORGANIZATION= being specified, ORGANIZATION= defaults to
| 'INDEXED'. If ORGANIZATION= and KEY= are both specified,
| ORGANIZATION= must be 'INDEXED', or an error occurs or the ERR= branch
| is taken.
|
| For existing RMS indexed files, the KEY specifier is optional; if
| given, it is ignored, although RMS does update the KEY XAB chain given
| by the user with the key information from the file. (See Chapter 18
| for more information on RMS data structures.)
|
| The form of the KEY specifier is:
|
| KEY = (kspec[,kspec]...)
|
| where:
|
| kspec has the form:
|
| e1:e2[:dt]
|
| where:
|
| e1 is an integer expression specifying the first byte
| position of the key.
|
| e2 is an integer expression specifying the last byte
| position of the key.
|
| dt is the optional data type of the key: either
| INTEGER or CHARACTER.
|
| The default data type of a key is CHARACTER. The position of a key
| specification in the list determines a key's key-of-reference number.
| This number is used in any subsequent I/O statement to specify the
| same key. The primary key is key-of-reference number 0, the first
| alternate key is key-of-reference number 1, and so forth.
|
| The key fields and key-of-reference numbers are permanent attributes
11-26
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
| of an indexed file and are established when the file is created. When
| an existing file is opened, key definitions and key-of-reference
| numbers are obtained from the file itself.
|
| The KEY specifier defines the access key for records in an indexed
| file. The key starts at position e1 in the record and has a length of
| e2-e1+1. The values of e1 and e2 must be such that:
|
| 1 .LE. (e1) .LE. (e2) .LE. record-length
| 1 .LE. (e2-e1+1) .LE. 255
|
| You must define at least one key for a new indexed file. This
| mandatory key is called the primary key of the file and usually has a
| unique value of each record (this is the default condition). You can
| also define other keys, called alternate keys. RMS allows up to 254
| alternate keys.
|
| When using keys of type INTEGER, RMS requires that key length e2-e1+1
| equals 4. INTEGER key lengths other than 4 generate an error.
LIMIT
Specifier
11.3.22 LIMIT Specifier
The LIMIT specifier designates the number of output units (such as
pages) for spooled print or punch requests, which result from using
| DISPOSE='PRINT', DISPOSE='PUNCH', or DISPOSE='LIST' (see Section
| 11.3.15).
The form of the LIMIT specifier is:
LIMIT= Integer expression
|
|
| MAXREC (TOPS-20)
| Specifier
|
|
11-27
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
| 11.3.23 MAXREC Specifier (TOPS-20)
|
| The MAXREC specifier defines the maximum number of records permitted
| in a direct access RMS file. If MAXREC is omitted, the maximum number
| is unlimited. If MAXREC is specified, RMS returns an error when a
| record number greater than the value specified is written to the file.
| This keyword is ignored for non-RMS files.
|
| The form of the MAXREC specifier is:
|
| MAXREC = Integer expression
MODE
Specifier
11.3.24 MODE Specifier
The MODE specifier defines the data mode of an external file or
record.
The form of the MODE specifier is:
MODE = mod
where:
mod is a character expression having a value equal to one of
the following:
'ASCII'
'LINED'
'BINARY'
'IMAGE'
'DUMP'
After a MODE has been assigned (either explicitly or by default), it
cannot be changed until the file is closed and then reopened.
The default value of MODE depends on the values of FORM and ACCESS.
If FORM is FORMATTED, then the default MODE is ASCII. If FORM is
UNFORMATTED, then the default MODE is BINARY. If ACCESS is SEQUENTIAL
and no FORM= is specified, then the default MODE is ASCII; if ACCESS
is DIRECT or RANDOM, and no FORM= is specified, then the default MODE
| is BINARY. (See Section 11.3.19 for details on FORM, and Section
11.3.1 for details on ACCESS.)
11-28
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
Character data is supported in formatted BINARY and IMAGE mode files;
it is not supported in DUMP mode files.
The possible values of MODE are:
ASCII Specifies the data to be 7-bit ASCII characters.
Records are terminated with a line feed, form feed, or
vertical tab.
LINED Takes effect on input only. For output, this mode
defaults to ASCII. LINED specifies the data to be
7-bit ASCII characters with optional line sequence
numbers. FORTRAN removes the line sequence numbers, if
present, before supplying the data to the user. (The
line sequence number can be obtained by using the
function LSNGET, see Section 13.3.1.)
Note that a page mark in a file containing line
sequence numbers is a separate record. FORTRAN removes
the blank sequence number, and the carriage return/form
feed sequence is read as a blank record.
| This value is ignored for RMS files.
BINARY specifies that data is formatted as a FORTRAN binary
data file. A BINARY file is composed of 36-bit words
(see Section 10.3.2). The first word of each record is
written by FOROTS and specifies the beginning of the
binary record; this 36-bit value is called a type 1
Logical Segment Control Word (LSCW).
Each binary record can contain one or more type 2
LSCWs. The type 2 LSCW, written by FOROTS under
certain conditions, is used to mark a record that spans
internal buffer boundaries.
A third FOROTS-written word, the type 3 LSCW, is always
written as the last 36-bit value in each BINARY record.
All data in a "BINARY" transfer remains equivalent in
its external form with its internal representation.
| For RMS files, specifying BINARY is equivalent to
| specifying IMAGE. RMS files do not contain LSCWs.
IMAGE Specifies an unformatted binary mode. Like the BINARY
form of unformatted transfers, IMAGE specifies that
data is transferred as 36-bit values, with the internal
and external representation of the data remaining the
same.
Unlike BINARY files, IMAGE files do not contain record
information (LSCWs); they contain only the data
11-29
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
transferred. IMAGE files can be backspaced if a record
size is specified.
DUMP Corresponds to TOPS-10 DUMP mode I/O. (See the TOPS-10
TOPS-10 Monitor Calls Manual.) Record size is ignored.
Character data cannot be written into or read from DUMP
mode files. Note that there is little or no
performance advantage to using DUMP, as FOROTS uses
DUMP mode internally for all disk files.
NOTE
For ASCII devices (line printer, plotter, terminal,
industry magnetic tape), the MODE= specifier has no
meaning and is ignored; both formatted and unformatted
data transfers are legal (see Section 10.3.3).
Table 11-2 summarizes the different MODE arguments that are supported
on different devices.
Table 11-2: DEVICE and MODE Cross-Table
NAME
Specifier
11.3.25 NAME Specifier
The NAME specifier is used to specify a full file specification. You
can use this specifier instead of the DEVICE, FILE, and/or DIRECTORY
specifiers.
The form of the NAME specifier is:
11-30
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
NAME= Character expression
Examples of the NAME specifier are:
(TOPS-10): NAME='DSK:FOO.BAR[10,34]'
(TOPS-20): NAME='PS:<SMITH>BILLING.DAT'
The NAME specifier can not be given in DIALOG mode. Also, the OPEN
statement cannot have both a DIALOG= specifier and a NAME specifier.
|
|
| NOSPANBLOCKS (TOPS-20)
| Specifier
|
|
|
|
|
| 11.3.26 NOSPANBLOCKS Specifier (TOPS-20)
|
| The NOSPANBLOCKS specifier enables you to specify that RMS records are
| not to cross disk block (page) boundaries. If any record exceeds the
| size of the physical block, an error occurs.
|
| The form of the NOSPANBLOCKS specifier is:
|
| NOSPANBLOCKS
|
| This specifier has no effect on non-RMS files or on RMS files other
| than new relative or sequential files.
|
|
| ORGANIZATION (TOPS-20)
| Specifier
|
|
|
|
|
| 11.3.27 ORGANIZATION Specifier (TOPS-20)
|
| The ORGANIZATION specifier determines the internal organization of an
| RMS file. This specifier invokes RMS (unless 'UNKNOWN' is specified).
|
| The form of the ORGANIZATION specifier is:
|
| ORGANIZATION = org
11-31
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
| where:
| org is a character expression having a value equal to one
| of the following:
|
| 'SEQUENTIAL'
| 'RELATIVE'
| 'INDEXED'
| 'UNKNOWN'
|
| For new files, the default file organization is SEQUENTIAL. For
| existing files, the value specified must be the same value as that of
| the existing file, or an error message is displayed or the ERR= branch
| is taken.
PADCHAR
Specifier
11.3.28 PADCHAR Specifier
The PADCHAR specifier is used only with formatted output data transfer
operations. PADCHAR enables you to specify a character that will be
used to pad fixed-length formatted records, on output only, to their
| specified record length (see the RECL(RECORDSIZE) specifier, Section
| 11.3.33).
The form for the PADCHAR specifier is:
PADCHAR= A character expression in which the first character is
used
The default pad character is space. The pad character is ignored if
fixed-length records are not being used (that is, if the
RECL(RECORDSIZE) specifier is absent), or if formatted I/O is not
being done.
NOTE
To specify a null character for the pad character, you
must use the function CHAR (see Chapter 13), since the
compiler does not allow null character constants, for
example:
OPEN (UNIT=1,PADCHAR=CHAR(0))
11-32
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
PARITY
Specifier
11.3.29 PARITY Specifier
The PARITY specifier is only used for magnetic tape operations. It
permits you to specify parity to be observed (odd or even) during the
transfer of data.
The form of the PARITY specifier is:
PARITY = par
where:
par is a character expression having a value equal to 'ODD' or
'EVEN'.
PROTECTION (TOPS-10)
Specifier
11.3.30 PROTECTION Specifier (TOPS-10)
This option specifies a protection code to be assigned to the data
file being transferred. The protection code is a 3-digit octal value
indicating the level of access to the file.
Each of the three numbers in the protection code has a specific
meaning. The number in the leftmost position designates the file
owner's protection; the middle number designates the project member's
protection; and the rightmost number designates the protection for all
others users on the system. The system default for the file
protection is assigned if a protection is not specified.
On TOPS-10, the form of the PROTECTION specifier is:
PROTECTION= Integer expression
Figure 11-1 illustrates the TOPS-10 3-digit octal file protection
code.
11-33
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
NOTE
When setting the protection code for a file open for
output, be sure not to set the protection such that
the file is protected against writing by the program;
if you should do this, the OPEN statement will fail.
To protect the file against writing by the owner, you
should give the PROTECTION specifier in the CLOSE
statement.
Figure 11-1: TOPS-10 File Protection Number
11-34
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
Table 11-3 lists all the possible values for each field of the
protection code. Refer to the TOPS-10 Monitor Calls Manual for more
information.
NOTE
The File Daemon referred to in Table
11-3 provides extended file protection.
The File Daemon allows any user to
specify who can and who cannot access
their files (if applicable). (Refer to
the TOPS-10 Operating System Commands
Manual.)
Table 11-3: TOPS-10 Protection Code Values
11-35
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
On TOPS-10, PROTECTION can be an integer expression. If the argument
is assigned a zero value or is not specified, the default protection
code established for the TOPS-10 installation is used.
PROTECTION (TOPS-20)
Specifier
11-36
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
11.3.31 PROTECTION Specifier (TOPS-20)
The PROTECTION specifier enables you to designate an octal protection
code for the file. The protection code is a 6-digit octal value that
designates the access to the file of the owner, group members, and
other system users.
On TOPS-20, the form of the PROTECTION specifier is:
PROTECTION= Integer expression
Figure 11-2 illustrates a TOPS-20 protection code.
Figure 11-2: TOPS-20 Protection Number
|
| NOTE
|
| This specifier is ignored for remote files. Instead,
| the default protection of the remote directory or
| system is used.
Table 11-4 lists the possible protection values and their meanings in
the TOPS-20 file protection code.
Table 11-4: TOPS-20 Protection Code Values
11-37
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
On TOPS-20, PROTECTION specifies a protection code to be assigned to
the data file being transferred. The protection code determines the
level of access that three classes of users have to the file.
PROTECTION takes an integer expression as an argument. If PROTECTION
is assigned a zero value or is not specified, the default protection
code established for your connected directory is used.
READONLY
Specifier
11.3.32 READONLY Specifier
| For local non-RMS files, the READONLY specifier is used to specify
| that the program will only read from the file. The accessing process
| can read but not write to the file. Output to the file is illegal and
will cause an error at execution time.
| For RMS or remote files, if the first process to access the file
| specifies READONLY, the file is open for read-only access by that
| process, as for non-RMS files. Any subsequent accessing process must
| specify READONLY to obtain any access to the file. If READONLY is not
| specified by the subsequent accessor, or if SHARED (see Section
| 11.3.35) is specified, access to the file is denied with a "?File is
| locked" error. Thus, the access-sharing capabilities of the file are
| determined by the first process to access the file.
The form of the READONLY specifier is:
READONLY
11-38
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
RECL
(RECORDSIZE)
Specifier
11.3.33 RECL (RECORDSIZE) Specifier
| For non-RMS files, the RECL (or RECORDSIZE) specifier enables you to
specify the number of characters or words in each record transferred.
RECL is required for all files opened for direct access
(ACCESS='DIRECT', 'RANDOM', or 'RANDIN'). (See Section 11.3.1.)
| For RMS files, RECL specifies the Maximum Record Size (MRS).
The form of the RECL specifier is:
RECL= Integer expression
| For non-RMS files:
o In an ASCII transfer (MODE='ASCII' or 'LINED'), the value
assigned to RECL specifies the number of characters in each
record.
For output to disk or CORE-DUMP tape files, in addition to
these characters, FOROTS adds a carriage return/line feed to
each record, followed by enough null characters to fill the
current word, so that records are word-aligned. RECL is
enforced on output by padding short records with the padding
character for formatted records. Long records are truncated.
o FORTRAN enforces a specified RECL for all input operations.
If the RECL specified in an OPEN statement is different from
the actual size of the records, FOROTS reads the number of
characters specified by RECL.
o For input to disk or CORE-DUMP tape files, specifying a
record size directs FOROTS to read records that are
word-aligned. The calculation of the actual recordsize is
the size specified, plus two for the carriage return/line
feed, plus the number of nulls necessary to word-align the
record.
o For INDUSTRY tapes, with RECORDTYPE='FIXED', RECL specifies
the exact number of characters in each record; there are no
terminators or padding characters. For INDUSTRY tapes with
RECORDTYPE='VARIABLE', RECL specifies the maximum record size
in the file, excluding the RCW.
11-39
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
When the record is read, regardless of the contents of the
record, it is interpreted as specified by the rules above;
there are RECL characters of data, and the rest are ignored.
No interpretation is done of the characters in the data part
of the record. These characters appear in the FOROTS line
buffer exactly as they appear in the file, including nulls
and control characters.
o In the case of MODE='LINED', the value of RECL excludes the
five characters and tab in each line-sequence number.
o In a binary transfer (MODE='BINARY', or 'IMAGE'), the value
assigned to RECL specifies the number of 36-bit words in each
record. For MODE='BINARY', the value in RECL excludes the
LSCWs written by FOROTS.
NOTE
If MODE='DUMP' is specified, RECL is ignored.
| For RMS files:
|
| o If the file contains fixed-length records, RECL specifies the
| size of each record.
|
| o If the file is a sequential file and contains variable-length
| records, RECL is optional and specifies the maximum length
| for each record. If no RECL has been specified, RMS does not
| perform maximum-length checking.
|
| o As with non-RMS files, if the records are formatted, the
| length is in bytes; if unformatted, in words.
|
| o If RECL is not specified, the MRS value specified when the
| file was created is used.
|
| o If RECL is specified for an existing file with fixed-length
| records or relative organization, and the value is different
| from the actual length of the records in the file, an error
| message is displayed, or the ERR= branch is taken.
|
| o If a program attempts to write a variable-length record that
| is longer than the non-zero MRS value specified when the file
| was created, an error is displayed or the ERR= branch is
| taken. Writing fixed-length records that exceed RECL
| produces a run-time warning, and the record is truncated to
| the specified size.
|
| o RECL is required when creating a new relative or indexed
| file, or when the RECORDTYPE is (or defaults to) FIXED.
|
| For local RMS files, RMS allows the following maximum record sizes for
11-40
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
| file/record formats:
|
| Organization Record format Maximum
|
| Sequential Fixed-length 262,143 bytes
| Sequential Variable-length 262,143 bytes
| Relative Fixed-length 262,143 bytes
| Relative Variable-length 262,143 bytes
| Indexed Fixed-length 3,579 words
| Indexed Variable-length 3,578 words
|
| For remote files, the maximum size for an RMS record transfer cannot
| exceed RMS's DAP buffer size. If the record exceeds this limit, a
| "?Record too big" error is displayed or the ERR= branch is taken.
RECORDTYPE
Specifier
11.3.34 RECORDTYPE Specifier
The RECORDTYPE specifier defines the format of the records in a file.
The form of the RECORDTYPE specifier is:
RECORDTYPE = rtype
where:
| rtype is a character expression having a value equal to one
| of the following:
|
| 'FIXED'
| 'STREAM'
| 'VARIABLE'
| 'UNKNOWN'
The possible values for RECORDTYPE are:
FIXED is not defined for 36-bit format (CORE-DUMP). For
INDUSTRY magnetic tape, this is the standard ANSI
"F" tape record format. Thus, the record data is
written with no terminators or carriage control
characters, one record directly after another, to
fill exactly fixed-length blocks. For this record
format, a RECORDSIZE must be specified in the OPEN
statement.
11-41
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
With this record format, all physical blocks on the
tape are the same size except for the last block,
which may be a short block.
STREAM For all tape formats, this record format specifies
that for formatted files, a standard stream record
terminator (CRLF) is placed at the end of each
record, and that a standard stream terminator is
expected on input to delimit records. For
unformatted files, the behavior is identical to that
of MODE='IMAGE'.
With this record format, all physical blocks on the
tape are the same size except for the last block,
which may be a short block.
For 36-bit mode (CORE-DUMP), the bytes in the last
36-bit word after the last character of data will be
nulls. For all tape formats, if a RECORDSIZE is
specified for a formatted file, the actual record
read or written consists of the data, CRLF, and the
number of nulls necessary to word-align the record.
VARIABLE is not defined for 36-bit tape format (CORE-DUMP).
For INDUSTRY magnetic tape, this is the standard
ANSI "D" tape record format. Thus, records are
variable in length, and the record data is written
with no terminators or carriage-control characters,
and preceded by a 4-byte record size (referred to as
the Record Control Word or RCW).
Blocks are variable length, not to exceed the block
length specified in the OPEN statement. If a
RECORDSIZE is specified in the OPEN statement, this
is the maximum number of bytes specified in the
4-byte RCW that precedes each record. The record
actually read or written is four characters less
than specified in the RCW.
| UNKNOWN If the record type cannot be determined.
|
| If no RECORDTYPE specifier is used, its value is UNKNOWN, and the
| default record types are the following:
|
| File Type Default Record Type
|
| Non-RMS files 'STREAM'
|
| RMS Relative and indexed files 'FIXED'
|
| All other RMS files 'VARIABLE'
11-42
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
| NOTE
|
| VMS FORTRAN may write special 'segmented' RMS
| sequential files with embedded record control bytes as
| part of the data for each RMS record in the file (VMS
| FORTRAN RECORDTYPE='SEGMENTED').
|
| These files can be read correctly only from VMS
| FORTRAN. Attempts to read these files from a remote
| TOPS-20 system using FORTRAN-10/20 V11 will return two
| bytes of control information as part of the data.
|
|
|
| SHARED
| Specifier
|
|
|
|
|
| 11.3.35 SHARED Specifier
|
| The SHARED specifier, for RMS and remote non-RMS files, specifies that
| the file is opened for write sharing: at least one program is writing
| a file and at least one other program is either reading or writing the
| same file. For write sharing to occur, all programs that access the
| file must specify SHARED. Attempts by a subsequent accessor to write
| a record that has already been locked results in a "?Record locked"
| error, or the ERR= branch is taken.
|
| The form of the SHARED specifier is:
|
| SHARED
|
| If neither READONLY nor SHARED is specified, the file is open for
| exclusive access; that is, the initial accessor can read and write to
| the file, but subsequent accessors are denied any access.
|
| This specifier is ignored for local non-RMS files.
STATUS
(TYPE)
Specifier
11-43
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
11.3.36 STATUS (TYPE) Specifier
The STATUS (or TYPE) specifier lets you specify whether or not the
file being opened must exist, or what to do with the opened file when
it is closed.
The form of the STATUS specifier is:
STATUS = sta
where:
sta is a character expression whose value is equal to one of
the following:
'EXPUNGE'
'OLD'
'NEW'
'SCRATCH'
'UNKNOWN'
'KEEP'
'DELETE'
The arguments to STATUS are:
EXPUNGE On TOPS-10, this specifies that the file is deleted
when it is closed. On TOPS-20, this specifies that the
file is deleted and expunged when it is closed.
NOTE
On TOPS-10, any delete also expunges a file
from storage. On TOPS-20, a DELETE operation
marks the file as deleted; an EXPUNGE operation
immediately erases the file from storage.
OLD Specifies that the file being opened must already
exist. If the file does not exist, an error results.
NEW On TOPS-10, STATUS='NEW' specifies that the file must
not exist. If the file does exist, an error results.
An error also occurs if you specify STATUS='NEW' with
ACCESS='SEQIN','SEQUENTIAL','SEQINOUT' (to a read-only
device), or 'RANDIN' (see Section 11.3.1).
On TOPS-20, the STATUS='NEW' specifier acts
differently, depending on what you have in the
directory before STATUS='NEW' is executed.
Also, the way you specify the file in the OPEN
statement which contains the STATUS='NEW' specifier
influences the way the STATUS='NEW' specifier operates.
11-44
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
The following list describes the ways that this
specifier can operate when used on TOPS-20.
1. If the file specified in the OPEN statement does
not currently exist in the directory, and no
generation number is specified, then the
STATUS='NEW' specifier creates the specified file
and gives it a generation number of 1.
2. If the file specified in the OPEN statement
contains a name, extension, and generation number
that does not exist, the specified file is used.
3. If the file specified in the OPEN or CLOSE
statement contains a name, extension, and
generation number that is exactly the same as an
existing file in your directory, then STATUS='NEW'
causes an error, and no file is created.
4. If you did not specify a generation number, but the
file specified has the same name and extension as
an existing file in your directory, then the file
with the same name and extension and the next
highest generation will be created.
SCRATCH Specifies that the file will be automatically deleted
when the file is closed. STATUS='SCRATCH' implies
DISPOSE='EXPUNGE'.
A SCRATCH file is always given a name by FOROTS. The
name of the file is inaccessible to the FORTRAN
program.
If STATUS='SCRATCH' is used, you must not specify FILE,
DIRECTORY, PROTECTION, or VERSION. If your program is
writing a file with STATUS='SCRATCH', and the file is
being written to disk, you can retain it by executing a
CLOSE statement that renames the file to a specified
name.
If a file is opened with STATUS='SCRATCH', the access
must be ACCESS='SEQUENTIAL' (or 'SEQINOUT') or
ACCESS='DIRECT' (or 'RANDOM') (see Section 11.3.1).
UNKNOWN Specifies that a file opened for an input operation
must exist. When a file is opened for output with
STATUS='UNKNOWN', if the file exists, it is superseded;
if it does not exist, it is created.
UNKNOWN is the default for STATUS. This value is used
unless you specify STATUS or unless the value of STATUS
is otherwise determined by the ACCESS specifier.
11-45
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
KEEP Specifies that the file is not deleted. Specifying
STATUS='KEEP' is equivalent to specifying
DISPOSE='SAVE' and STATUS='UNKNOWN'.
DELETE On TOPS-10, specifies that the file will be erased when
the file is closed.
On TOPS-20, specifies that the file will be deleted
when the file is closed. The file is erased when a
TOPS-20 EXPUNGE command is given. To undelete a
deleted file, use the TOPS-20 UNDELETE command.
TAPEFORMAT
Specifier
11.3.37 TAPEFORMAT SPECIFIER
The TAPEFORMAT specifier defines the physical format of the magnetic
tape.
The form of the TAPEFORMAT specifier is:
TAPEFORMAT = tmode
where:
tmode is a character expression having a value equal to
'CORE-DUMP' or 'INDUSTRY'.
The values for the TAPEFORMAT specifier are:
CORE-DUMP specifies the "DIGITAL-compatible" tape format, which
is 36-bits stored in five frames on a 9-track tape.
The SET TAPE RECORDSIZE (TOPS-20) or SET BLOCKSIZE
(TOPS-10) command is interpreted to be the number of
36-bit words in the magnetic tape blocks on the tape,
and is used if no BLOCKSIZE specifier is given in the
OPEN statement. If a BLOCKSIZE specifier is given in
the OPEN statement, it is interpreted to be the number
of 36-bit words for both formatted and unformatted
files.
INDUSTRY specifies characters are read or written in standard
industry tape format, one character per tape frame.
11-46
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
UNIT
Specifier
(Required)
11.3.38 UNIT Specifier (Required)
The UNIT specifier defines the FORTRAN logical unit number to be used.
FORTRAN devices are identified by assigned decimal numbers within the
range 0-99 (see Table 10-3). UNIT must be an integer expression.
The form of the UNIT specifier is:
UNIT= Integer expression
If the unit specifier is the first specifier given in the OPEN
statement, the keyword UNIT= is optional. For example the following
statement opens a file on unit 20:
OPEN (20,FILE='MYFILE')
NOTE
The FORTRAN standard logical unit assignments are
described in Section 10.4.3.1. Although the range of
logical unit numbers shown in Table 10-3 is 0-99, the
range of UNIT numbers is an installation-defined
parameter.
|
|
| USEROPEN (TOPS-20)
| Specifier
|
|
|
|
| 11.3.39 USEROPEN Specifier (TOPS-20)
|
| The USEROPEN specifier is used to specify the name of an optional
| user-supplied external function. This function can set various RMS
| parameters that FORTRAN otherwise defaults, and must perform the
| actual OPEN in place of FOROTS. This function is intended for use
| with RMS files only; a USEROPEN function used with a remote non-RMS
| file can produce indeterminate results.
11-47
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
| The form of the USEROPEN specifier is:
|
| USEROPEN = procedure-name
|
| where:
|
| procedure-name is the symbolic name of the USEROPEN function.
| The function name must be declared EXTERNAL.
|
| The function must perform both $OPEN and $CONNECT RMS service calls,
| returning AC0 non-zero on any non-recoverable failure. If AC0 is
| returned zero, FOROTS assumes the function has succeeded, and program
| execution continues. If AC0 is returned non-zero, FOROTS assumes the
| USEROPEN function has failed, and issues an error (or takes the ERR=
| branch) based on the STS and STV values returned by RMS to FOROTS.
|
| See Section 18.9 for more information on USEROPEN.
VERSION (TOPS-10)
Specifier
11.3.40 VERSION Specifier (TOPS-10)
Use the VERSION specifier for disk operations only; it enables you to
assign a 12-digit octal version number to an output file.
The form of the VERSION specifier is:
VERSION=Integer expression
11.4 CLOSE STATEMENT
The CLOSE statement disassociates an active file from a logical unit
and releases the memory occupied by I/O buffers and other unit-related
data. The CLOSE statement can also change some of the file
characteristics that were assigned during the OPEN, such as the name,
protection, directory, and disposition of the file.
Once a CLOSE statement has been executed, you must use another OPEN
statement (or implicit OPEN) to regain access to the closed file.
The form of the CLOSE statement is:
CLOSE (closelist)
11-48
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
where:
closelist is a list of CLOSE statement specifiers. This
list must contain the UNIT specifier (see Section
11.5.9) and can optionally contain other
specifiers.
11.4.1 Implicit CLOSE
An implicit CLOSE occurs when FOROTS automatically closes a logical
unit without execution of a CLOSE statement. This can happen when a
program terminates, or when you execute an OPEN for a unit that is
already connected to another file.
11.5 CLOSE STATEMENT SPECIFIERS
All of the CLOSE statement specifiers are optional, except the UNIT
specifier which is required. Some CLOSE statement specifiers have the
same formats as the corresponding specifiers in the OPEN statement.
Table 11-5 summarizes the specifiers in the CLOSE statement, and the
type of value required by each. A section number is provided to refer
to detailed descriptions of each specifier.
Table 11-5: Summary of CLOSE Statement Specifiers and Arguments
11-49
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
NOTE
For compatibility with previous versions of
FORTRAN-10/20, you can specify a numeric array name as
the value of each of the following specifiers:
DIALOG=
DIRECTORY
NAME
When a numeric array name is used, FOROTS assumes that
it contains a string of characters terminated by a
null character.
In addition, you can specify a numeric variable as the
value of the DEVICE and FILE specifiers. If the
variable is single precision, FOROTS assumes that it
contains 5 characters; if it is double precision,
FOROTS assumes that is contains 10 characters.
The use of numeric array names and numeric variables
in place of character variables is a nonstandard
feature.
DEVICE, DIRECTORY,
FILE, NAME, and
PROTECTION
11-50
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
Specifiers
11.5.1 DEVICE, DIRECTORY, FILE, NAME, and PROTECTION Specifiers
The CLOSE statement file identification specifiers can be used when
you want to rename the output file when it is closed. Their formats
are the same as the corresponding specifiers in the OPEN statement.
If any of these specifiers are given in the CLOSE statement, the file
is renamed when it is closed. If some, but not all of the file
identification parameters are specified on a CLOSE statement, only the
specified parameters are changed when the file is renamed.
Example:
OPEN(20,ACCESS='SEQOUT',FILE='FOO.BAR')
.
.
.
CLOSE(20,FILE='NEWFIL')
The above sequence renames the output file to DKSB:NEWFIL.BAR.
Refer to the following sections under the OPEN statement:
| FILE - see Section 11.3.17
| NAME - see Section 11.3.25
| DEVICE - see Section 11.3.8
| DIRECTORY (TOPS-10) - see Section 11.3.13
| DIRECTORY (TOPS-20) - see Section 11.3.14
| PROTECTION (TOPS-10) - see Section 11.3.30
| PROTECTION (TOPS-20) - see Section 11.3.31
DIALOG
Specifier
11.5.2 DIALOG Specifier
The DIALOG specifier enables you to type in additional CLOSE
specifiers when the CLOSE statement is actually executed.
If the DIALOG specifier is found in the CLOSE list, then each time the
CLOSE statement is executed, FOROTS suspends execution and prompts the
11-51
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
terminal with an asterisk.
The form of the DIALOG specifier is:
DIALOG
You can respond to the asterisk prompt by entering a file
specification, DIALOG switches (see below), or a file specification
followed by DIALOG switches. The file specification can be a full
file specification including the device, directory name, and so on.
If you enter a file specification that is different from the file
specification currently assigned to the file, FOROTS RENAMEs the file
after it is closed to the new name.
NOTE
A DIALOG switch is any CLOSE specifier (except DIALOG,
DIALOG=, UNIT, NAME, FILE, IOSTAT, or ERR) preceded by
a slash (/).
DIALOG=
Specifier
11.5.3 DIALOG= Specifier
The DIALOG= specifier enables you to include all or a portion of the
CLOSE specifiers in a character expression. The contents of the
character expression are interpreted as if you had given the DIALOG
specifier (see above); and, when the asterisk prompt was given, you
had typed in the same string as is contained in the character
expression, followed by a carriage return.
The form of the DIALOG= specifier is:
DIALOG= Character expression
Example:
CLOSE (UNIT=20,ERR=10,DIALOG='/DISPOSE:DELETE')
When DIALOG= is given in the CLOSE list, it is processed after all
other specifiers except DIALOG.
11-52
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
DISPOSE
Specifier
11.5.4 DISPOSE Specifier
The DISPOSE specifier enables you to specify an action to occur when
the file is closed.
The form of the DISPOSE specifier is:
DISPOSE = dis
where:
dis is a character expression having a value equal to one of
the following:
'KEEP'
'SAVE'
'DELETE'
'EXPUNGE'
'PRINT'
'LIST'
'PUNCH'
The DISPOSE specifier must have one of the following values:
KEEP Specifies that the file is to be left on the connected
unit. DISPOSE='KEEP' is the default. You can not
specify DISPOSE='KEEP' if in the corresponding OPEN
statement you specified STATUS='SCRATCH' (see Section
| 11.3.36).
SAVE Same as KEEP.
DELETE Specifies on TOPS-10 that, if the device is either a
DECtape or disk, delete the file; otherwise, take no
action.
On TOPS-20, if the device involved is a disk, delete
the file; otherwise, take no action.
EXPUNGE On TOPS-10, same as DELETE. On TOPS-20, if the device
involved is a disk, expunge the file; otherwise, take
no action.
| EXPUNGE deletes but does not expunge a local RMS file.
| Depending on the capabilities of the remote system,
11-53
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
| EXPUNGE may also expunge a remote RMS or non-RMS file.
PRINT Specifies that the file will be printed and kept (the
file will not be kept if you specify the CLOSE
statement STATUS='DELETE' or 'EXPUNGE'). The file must
| be on disk. This value is not supported for TOPS-20
| RMS files; however, it is supported for VMS RMS files.
LIST Specifies that the file will be printed, deleted, and
expunged (the file will not be deleted if you specify
the CLOSE statement STATUS='KEEP'). The file must be
| on disk. This value is not supported for TOPS-20 RMS
| files; however, it is supported for VMS RMS files.
PUNCH Specifies that the file will be punched on the paper
| tape punch and kept. The file must be on disk. This
| value is not supported for RMS or remote non-RMS files.
NOTE
The value of the CLOSE statement DISPOSE specifier
supersedes the value of the OPEN statement DISPOSE
specifier and the OPEN statement STATUS specifier if
STATUS='EXPUNGE', 'KEEP', and 'DELETE'.
ERR
Specifier
11.5.5 ERR Specifier
The ERR specifier enables you to designate a statement label of an
executable statement, in the current program unit, to which control
passes if an error occurs during the execution of an I/O statement.
The form of the ERR specifier is:
ERR= s
where:
s is the number of an executable statement to which program
control passes if an error occurs during the execution of
the statement in which the ERR specifier is included.
11-54
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
The ERR specifier works the same way when it is given in a CLOSE as it
| does when given in an OPEN statement (see Section 11.3.16).
IOSTAT
Specifier
11.5.6 IOSTAT Specifier
The IOSTAT specifier identifies an integer variable that is used to
store the I/O status code during the execution of a statement.
The form of the IOSTAT specifier is:
IOSTAT= Integer variable or integer array element
LIMIT
Specifier
11.5.7 LIMIT Specifier
The LIMIT specifier designates the number of output units (such as
pages) for spooled print or punch requests, which result from using
DISPOSE='PRINT', DISPOSE='PUNCH', or DISPOSE='LIST' (see Section
11.5.4).
The form of the LIMIT specifier is:
LIMIT= Integer expression
STATUS
Specifier
11-55
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
11.5.8 STATUS Specifier
The STATUS specifier tells FOROTS what to do with a file when it is
closed. In the CLOSE statement, STATUS values are a subset of the
DISPOSE specifier (see Section 11.5.4) values.
NOTE
The ANSI-77 standard does not have DISPOSE and only
allows STATUS='KEEP' or STATUS='DELETE'.
The form of the STATUS specifier is:
STATUS = sta
where:
sta is a character expression having a value equal to one of
the following:
'KEEP'
'DELETE'
'EXPUNGE'
The arguments to STATUS are:
KEEP Specifies that the file is not deleted.
DELETE On TOPS-10, specifies that the file is deleted.
On TOPS-20, specifies that the file is marked for
deletion when the file is closed. The file is erased
when a TOPS-20 EXPUNGE command is given. To undelete a
deleted file, use the TOPS-20 UNDELETE command.
EXPUNGE On TOPS-10, the same as delete. On TOPS-20, this
specifies that the file is deleted and expunged.
| EXPUNGE deletes but does not expunge a local RMS file.
| Depending on the capabilities of the remote system,
| EXPUNGE may also expunge a remote RMS or non-RMS file.
NOTE
The value of the CLOSE statement STATUS specifier
supersedes the value of the OPEN statement DISPOSE
specifier and OPEN statement STATUS specifier if
STATUS='EXPUNGE', 'KEEP', and 'DELETE'.
UNIT
11-56
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
Specifier
(required)
11.5.9 UNIT Specifier (Required)
The UNIT specifier tells FOROTS which logical unit number is to be
closed. This specifier corresponds to the UNIT specifier in the OPEN
| statement (see Section 11.3.38) and to the UNIT specifiers in the data
transfer statements (see Section 10.4.3).
The form of the UNIT specifier is:
UNIT= Integer expression
If the unit specifier is the first specifier given in the CLOSE
statement, the keyword UNIT= is optional. For example, to close a
file on unit 20, you can use the following command:
CLOSE (20)
11.6 OPEN AND CLOSE STATEMENT EXAMPLES
The following are examples of OPEN and CLOSE statements:
OPEN (UNIT=1,DEVICE='DSK',ACCESS='SEQIN',MODE='BINARY')
causes a disk file named FOR01.DAT (since no FILE= option was
specified) to be opened on unit 1 for sequential input in binary mode.
OPEN (UNIT=3,DEVICE='DSK',FILE='PAYROL.DAT',
1 ACCESS='RANDOM',MODE='ASCII',RECORDSIZE= 80,
2 ASSOCIATEVARIABLE=I,ERR=240)
Causes a disk file named PAYROL.DAT to be opened on unit 3 for random
I/O operations in ASCII mode. The records in PAYROL.DAT are 80
characters long; the ASSOCIATE VARIABLE for this file is I. If an
error occurs during the execution of this OPEN statement, the OPEN
terminates, and control is transferred to the statement labeled 240.
| OPEN (UNIT=1, FILE='IDX.DAT',
| 1 ORGANIZATION='INDEXED',STATUS='NEW',
| 1 KEY=(1:15:CHARACTER),RECORDSIZE=80)
|
| Invokes RMS and causes an RMS indexed disk file name IDX.DAT to be
| created on unit 1. A primary index of datatype CHARACTER, specifying
| character positions 1 through 15 of each record has been defined for
| the file.
11-57
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
CLOSE (UNIT=3,DISPOSE='DELETE') The above statement causes the
file associated with unit 3 to be closed and deleted.
11.7 INQUIRE STATEMENT
The INQUIRE statement inquires about specific properties of a file
name or of a logical unit number on which a file might be opened. The
INQUIRE statement has two forms: one inquires by file, and the other
inquires by unit.
11.7.1 INQUIRE by File
An INQUIRE by file is an INQUIRE statement containing the following:
o A FILE= keyword
o An associated file specification
o No UNIT= keyword
It is used to obtain information about a file based on the file name.
INQUIRE by file can be used to get information on the following files:
o Files that are "connected"; meaning files for which an OPEN
statement has been executed or for which a data transfer
statement has been executed.
o Files that are not "connected."
INQUIRE by file has the following form:
| INQUIRE (FILE=fi[DEFAULTFILE=dfi],flist)
where:
fi is a character expression whose value specifies the
name of the file to be inquired about.
flist is a list that can contain at most one of each of the
inquiry specifiers (see Section 11.7.3).
| dfi is a character expression specifying a default file
| name specification string.
|
| DEFAULTFILE=dfi can be used in addition to or in place of FILE=fi when
| used in connection with an inquiry about a file. If both FILE and
| DEFAULTFILE are used, then the DEFAULTFILE specification is merged
| with FILE to obtain the full file specification, with file
| specification fields in FILE superceding corresponding fields in
11-58
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
| DEFAULTFILE.
|
| NOTE
|
| If the file specification is remote, RMS is used to
| access the file.
|
INQUIRE by file may be used any time during the execution of a
program. It can be used before a file is opened to find out about the
existence of the file, or after the file is opened to find out other
attributes of the file. It can also be used to find the unit number
on which the file is opened. If the same file is opened on more than
one unit, the smallest number on which the file is opened is returned.
The determination of whether a file specified in an INQUIRE statement
is opened on a unit is the following:
1. The file specification given in the INQUIRE statement is used
to lookup the file.
2. If the file exists, the file specification, expanded with the
physical device name and generation (TOPS-20 only), is
compared with the file specification for each open unit, in
ascending order, until there is an exact string match.
3. If the file does not exist, the specification given in the
INQUIRE statement (with a default of DSK: added if necessary
for the device name), is compared with the file specification
for each open unit, in ascending order, until there is an
exact string match. Note that this match will only be
successful for 'deferred' OPEN files, since non-deferred OPEN
files are always established in the specified directory
immediately. Therefore, the file exists (see item 2 above).
NOTE
If a file exists, INQUIRE by file will not generally
match the file with a unit for which a 'deferred' OPEN
has been done, since the file specification for the
unit has not been expanded. For example, the file's
logical device name has not been replaced by a
physical device name.
(See Section 18.8 for information on FOROTS and INQUIRE by file.)
11.7.2 INQUIRE by Unit
INQUIRE by unit is an INQUIRE statement containing a UNIT= keyword and
no FILE= keyword. It is used to find out information about the file
11-59
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
that may be "connected" to the specified unit.
INQUIRE by unit has the following form:
INQUIRE ([UNIT=]u,ulist)
where:
u is the number of the logical unit to be inquired about.
The unit need not exist, nor need it be connected to a
file. If the unit is connected to a file, the inquiry
encompasses both the connection and the file.
ulist is a list that can contain at most one of each of the
inquiry specifiers (see Section 11.7.3).
If the optional UNIT= keyword if omitted, u must be the first item in
the list.
INQUIRE by unit can be used at any time during the execution of a
program. It can be used before a file is opened to find out if there
is another file open on the unit, or after the file is opened to find
out other attributes of the file.
11.7.3 INQUIRE Specifiers
The specifiers described in the following sections may be used in
either form of the INQUIRE statement.
11.7.3.1 ACCESS Specifier - The ACCESS specifier has the following
form:
ACCESS = acc
where:
acc is a character variable, array element, or substring
reference. It is assigned the value 'SEQUENTIAL' if the
file is connected for sequential access, 'DIRECT' if the
| file is connected for direct access, or 'KEYED' if the
| file is connected for keyed access. If there is no
connection, acc is 'UNKNOWN'.
11.7.3.2 BLANK Specifier - The BLANK specifier has the following
form:
BLANK = blk
11-60
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
where:
blk is a character variable, array element, or substring
reference. It is assigned the value 'NULL' if the file
was last opened with BLANK='NULL', and is assigned the
value 'ZERO' if the file was opened with BLANK='ZERO'. If
the file is not open, blk is 'UNKNOWN'.
| 11.7.3.3 BYTESIZE Specifier - The BYTESIZE specifier has the
| following form:
|
| BYTESIZE = byte
|
| where:
|
| byte is the integer bytesize of the file (or 0 if the file
| is not open).
11.7.3.4 CARRIAGECONTROL Specifier - The CARRIAGECONTROL specifier
has the following form:
CARRIAGECONTROL = cc
where:
cc is a character variable, array element, or substring
reference. It is assigned the following values:
1. 'FORTRAN' if the file has the FORTRAN carriage-control
attribute
2. 'LIST' if the file has the implied carriage-control
attribute
3. 'NONE' if the file has no carriage-control attribute
4. 'TRANSLATED' if the file has FORTRAN carriage-control
characters being translated directly into vertical
motion characters.
5. 'UNKNOWN' if the CARRIAGECONTROL value cannot be
determined, or the file is not open.
11.7.3.5 DIRECT Specifier - The DIRECT specifier has the following
form:
11-61
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
DIRECT = dir
where:
dir is a character variable, array element, or substring
reference. It is assigned the following values:
1. 'YES' if DIRECT is an allowed access method for the
file
2. 'NO' if DIRECT is not an allowed access method for the
file
3. 'UNKNOWN' if the processor is unable to determine
whether DIRECT is an allowed access method
11.7.3.6 ERR Specifier - The ERR specifier has the following form:
ERR = s
where:
s is the label of an executable statement. ERR is a control
specifier; if an error occurs during execution of the
INQUIRE statement, control is transferred to the statement
whose label is s.
11.7.3.7 EXIST Specifier - The EXIST specifier has the following
form:
EXIST = ex
where:
ex is a logical variable or logical array element. It is
assigned the value .TRUE. if the specified file or unit
exists, and the value .FALSE. if the specified file or
unit does not exist.
11.7.3.8 FORM Specifier - The FORM specifier has the following form:
FORM = fm
where:
fm is a character variable, array element, or substring
reference. It is assigned the value 'FORMATTED' if the
11-62
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
file is connected for formatted I/O, and 'UNFORMATTED' if
the file is connected for unformatted I/O. If there is no
connection, fm is 'UNKNOWN'.
11.7.3.9 FORMATTED Specifier - The FORMATTED specifier has the
following form:
FORMATTED = fmd
where:
fmd is a character variable, array element, or substring
reference. It is assigned the value 'YES' if formatted is
an allowed form for the file. It is assigned the value
'NO' if formatted is not an allowed form of the file, and
the value 'UNKNOWN' if the form cannot be determined.
11.7.3.10 IOSTAT Specifier - The IOSTAT specifier has the following
form:
IOSTAT = ios
where:
ios is an integer variable or integer array element. It is
assigned a processor-dependent positive integer value if
an error occurs during execution of the INQUIRE statement,
or assigned the value zero if there is no error condition.
| 11.7.3.11 KEYED Specifier - The KEYED specifier has the following
| form:
|
| KEYED = kyd
|
| where:
|
| kyd is assigned the value 'YES' if KEYED is an allowed
| access method for the file (that is, the file is
| indexed), 'NO' if KEYED is not an allowed access
| method, and 'UNKNOWN' if the file is not open.
11.7.3.12 NAME Specifier - The NAME specifier has the following form:
NAME = nme
11-63
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
where:
nme is a character variable, array element, or substring
reference. It is assigned the name of the file being
inquired about.
The value assigned to nme is not necessarily identical to
the value specified with FILE=. For example, the value
that the processor returns may contain a directory name or
generation number (TOPS-20 only). However, the value that
is assigned is always valid for use with FILE= in an OPEN
statement.
NOTE
FILE and NAME are synonyms when used with the OPEN
statement, but not when used with the INQUIRE
statement.
For INQUIRE by unit, FOROTS returns the full, expanded
file specification if any of the following is true:
o If there is a file open on the specified unit with
STATUS other than UNKNOWN or SCRATCH.
o If there is a file open on the specified unit with
ACCESS other than SEQUENTIAL.
o An I/O transfer statement has been executed using the
specified unit and the unit has not been closed.
FOROTS returns the string given in the OPEN for NAME= with
defaults applied if both of the following are true:
o If the file is open on the specified unit as a result
of an OPEN statement in which STATUS='UNKNOWN' and
ACCESS='SEQUENTIAL' are specified or implied.
o No I/O transfer statement has been executed using the
specified unit.
If STATUS='SCRATCH', FOROTS returns blanks for NAME=.
If there has been no OPEN statement, and no I/O transfer
statement has been executed using the specified unit,
FOROTS returns for NAME= the default file specification
for that unit.
For INQUIRE by file, FOROTS returns the full, expanded
file specification if the file exists in the specified
directory. If the file does not yet exist on the
specified directory, but has been opened by a 'deferred'
OPEN, FOROTS returns the string given in the INQUIRE
11-64
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
statement, with defaults applied for the device and
generation number (TOPS-20 only). Otherwise, blanks are
returned.
|
| NOTE
|
| INQUIRE on a remote file that returns a full file
| specification, returns the network attributes.
11.7.3.13 NAMED Specifier - The NAMED specifier has the following
form:
NAMED = nmd
where:
nmd is a logical variable or logical array element. It is
assigned the value .TRUE. if the specified file has a
name, and the value .FALSE. if the file does not have a
name.
11.7.3.14 NEXTREC Specifier - The NEXTREC specifier has the following
form:
NEXTREC = nr
where:
nr is an integer variable or integer array element. It is
assigned an integer value that is one more than the last
record number read or written on the specified direct
access file. If no records have been read or written, the
value of nr is one. If the file is not connected for
direct access, or if the position is indeterminate because
of an error condition, nr is zero.
11.7.3.15 NUMBER Specifier - The NUMBER specifier has the following
form:
NUMBER = num
where:
num is an integer variable or integer array element. It is
assigned the number of a logical unit currently connected
to the specified file. If there is no logical unit
11-65
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
connected to the file, num is not defined. If more than
one unit is connected to the file, the smallest unit
number is returned.
11.7.3.16 OPENED Specifier - The OPENED specifier has the following
form:
OPENED = od
where:
od is a logical variable or logical array element. It is
assigned the value .TRUE. if the specified file is opened
on a unit or if the specified unit is opened; it is
assigned the value .FALSE. if the file or unit is not
open.
| 11.7.3.17 ORGANIZATION Specifier - The ORGANIZATION specifier has the
| following form:
|
| ORGANIZATION = org
|
| where:
|
| org is a character variable, array element, or substring
| reference. It is assigned the value 'SEQUENTIAL' if
| the file is a sequential file, 'RELATIVE' if the file
| is a relative file, 'INDEXED' if the file is an indexed
| file, or 'UNKNOWN' if the file is not open or the file
| is not an RMS file.
11.7.3.18 RECL (RECORDSIZE) Specifier - The RECL (RECORDSIZE)
specifier has the following form:
RECL = rcl
where:
rcl is an integer variable or integer array element.
| For non-RMS files, if the file (or unit) is opened, rcl is
the record length for fixed-length record files. In all
other cases, rcl is zero. If the file is opened for
formatted I/O, rcl is expressed in characters, and in
words if the file is unformatted.
| For RMS files, if the file is open, RECL returns the
11-66
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
| maximum record size value associated with the file in
| either bytes (for formatted I/O) or words (for unformatted
| I/O). If the file is not open, RECL returns zero.
11.7.3.19 RECORDTYPE Specifier - The RECORDTYPE specifier has the
following form:
RECORDTYPE = rtype
where:
rtype is a character variable, array element, or substring
reference. It is assigned the value 'FIXED' if the file
has fixed-length records, assigned the value 'VARIABLE' if
the file has variable-length records, and assigned the
value 'STREAM' if the file is a stream file (default for
| disk and magnetic tape). If the file is not open, rtype
is assigned the value 'UNKNOWN'.
11.7.3.20 SEQUENTIAL Specifier - The SEQUENTIAL specifier has the
following form:
SEQUENTIAL = seq
where:
seq is a character variable, array element, or substring
reference. It is assigned the following values:
1. 'YES' if SEQUENTIAL is an allowed access method for
the specified file
2. 'NO' if SEQUENTIAL is not an allowed access method
3. 'UNKNOWN' if the processor cannot determine whether
SEQUENTIAL is an allowed access method
11.7.3.21 UNFORMATTED Specifier - The UNFORMATTED specifier has the
following form:
UNFORMATTED = unf
where:
unf is a character variable, array element, or substring
reference. It is assigned the value 'YES' if unformatted
is an allowed form for the file. It is assigned the value
11-67
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
'NO' if unformatted is not an allowed form of the file,
and the value 'UNKNOWN' if the form cannot be determined.
11-68
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
11-69
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
Table 11-6 summarizes the form and use of the FORTRAN device control
statements.
Table 11-6: Summary of Device-Control Statements
11-70
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
11.8 DEVICE CONTROL STATEMENTS
Device control statements enable you to position external devices.
For example, when performing data transfers with magnetic tape, you
use device control statements to position the tape. The device
control statements may be used for both formatted and unformatted
files.
The following list contains all of the device control statements, and
the section in which each statement is described.
1. FIND (Section 11.8.1)
2. REWIND (Section 11.8.2)
3. UNLOAD (Section 11.8.3)
4. BACKSPACE (Section 11.8.4)
5. ENDFILE (Section 11.8.5)
6. SKIPRECORD (Section 11.8.6)
7. SKIPFILE (Section 11.8.7)
8. BACKFILE (Section 11.8.8)
NOTE
The results of the BACKSPACE and SKIPRECORD statements
are unpredictable when used on list-directed and
NAMELIST formatted data.
The general form of every device control statement is:
keyword un
or
keyword (UNIT=un[,END=s][,ERR=s][,IOSTAT=ios])
or
keyword (un[,END=s][,ERR=s][,IOSTAT=ios])
where:
keyword is the statement name.
un is the FORTRAN logical unit number. Table 10-3
lists the default logical unit numbers. If you
enclose the logical unit specification in
11-71
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
parentheses, you can include the keyword portion
(UNIT=) of the logical unit specification. The
keyword form of the unit specifier makes the
specification positionally independent in the
parenthetical list.
END=s is the optional end-of-file specifier (see Section
10.4.6).
ERR=s is the optional error specifier (see Section
10.4.7).
IOSTAT=ios is the optional I/O error status specifier (see
Section 10.4.8).
The operations performed by the device control statements are usually
used only for magnetic tape devices (MTA). In FORTRAN, however, the
device control operations are simulated for disk devices.
FIND
Statement
11.8.1 FIND Statement
In earlier versions of FORTRAN-10/20, the FIND statement could be used
during direct-access READ/WRITE operations to reduce the time
necessary to do data transfers and to locate records in a
| direct-access file. For FORTRAN-10/20 Version 11, the FIND statement
| has no effect on non-RMS files, except for setting the current record
number and, therefore, the associate variable.
| For an RMS relative file, the FIND statement positions the file at the
| record number specified. This establishes the record as the current
| record, sets the associate variable, and returns. The file on the
| specified unit must be a relative file opened for direct access.
The first form of the FIND statement is:
FIND (UNIT=un,REC=rn[,ERR=s][,IOSTAT=ios])
The second form of the FIND statement operates in the same way as the
first form. The difference between the two forms is in the way that
the unit number and record number are specified.
The second form of this statement is:
11-72
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
FIND(un'rn[,ERR=s][,IOSTAT=ios])
In this form, the unit number and record number do not contain the
keywords UNIT= and REC=. Instead, the unit number is specified first,
followed by a single quote ('), and finally the record number.
The following example demonstrates how the FIND statement is used:
FIND(UNIT=1,REC=100)
This statement positions the file so that the next READ statement
reads record 100.
REWIND
Statement
11.8.2 REWIND Statement
The REWIND statement, used for disk files, causes a specified file to
be positioned at its initial point. For magnetic tape, execution of
the REWIND statement positions the magnetic tape at its initial point.
| The REWIND statement can be used with RMS sequential files or
| sequential access RMS relative files. It is illegal for indexed
| files.
The forms of the REWIND statement are:
REWIND un
or
REWIND (UNIT=un[,ERR=s][,IOSTAT=ios])
or
REWIND (un[,ERR=s][,IOSTAT=ios])
where:
un is the logical unit number of the device on which the REWIND
is being performed. Table 10-3 lists the default logical
unit numbers.
REWIND is illegal for files opened with ACCESS='APPEND'.
11-73
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
UNLOAD
Statement
11.8.3 UNLOAD Statement
The UNLOAD statement rewinds and unloads the magnetic tape associated
with the specified unit.
The forms of the UNLOAD statement are:
UNLOAD un
or
UNLOAD (UNIT=un[,ERR=s][,IOSTAT=ios])
or
UNLOAD (un[,ERR=s][,IOSTAT=ios])
where:
un is the logical unit number of the device on which the UNLOAD
is being performed. Table 10-3 lists the default logical
unit numbers.
BACKSPACE
Statement
11.8.4 BACKSPACE Statement
Execution of a BACKSPACE statement causes the file connected to the
specified unit to be positioned before the preceding record. If there
is no preceding record, the position of the file is not changed. If
the preceding record is an ENDFILE record (see Section 11.8.5), the
file is positioned before the ENDFILE record.
| For RMS files, this statement repositions a file with sequential
| organization to the beginning of the previous record. When the next
11-74
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
| I/O statement is executed, this preceding record is available for
| processing.
The BACKSPACE statement cannot be used for direct-access files,
append-access files, or files that are formatted with list-directed or
NAMELIST-statement formatting.
| For RMS files, BACKSPACE cannot be used for files open ACCESS='APPEND'
| or with ORGANIZATION='RELATIVE' or 'INDEXED'.
The forms of the BACKSPACE statement are:
BACKSPACE un
or
BACKSPACE (UNIT=un[,ERR=s][,IOSTAT=ios])
or
BACKSPACE (un[,ERR=s][,IOSTAT=ios])
where:
un is the logical unit number of the device on which the
BACKSPACE is being performed. Table 10-3 lists the default
logical unit numbers.
ENDFILE
Statement
11.8.5 ENDFILE Statement
The ENDFILE statement closes the file on the specified unit. On
magnetic tape, an 'ENDFILE record' is written and is then positioned
after the end-of-file mark.
| For RMS files, ENDFILE is supported only for files with sequential
| organization.
For disk, the file is closed and then positioned at the end of the
file, and an end-of-file status is set. This status is the equivalent
of the file being positioned after an 'ENDFILE record'.
Thus, for both disk and magnetic tape, a BACKSPACE operation given
11-75
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
after an end file operation positions the file after the last data
record (that is, before the physical (or virtual) 'ENDFILE record').
The ENDFILE statement can be used only with sequential access files.
The forms of the ENDFILE statement are:
ENDFILE un
or
ENDFILE (UNIT=un[,ERR=s][,IOSTAT=ios])
or
ENDFILE (un[,ERR=s][,IOSTAT=ios])
where:
un is the logical unit number of the device on which the
ENDFILE is being performed. Table 10-3 lists the default
logical unit numbers.
SKIPRECORD
Statement
11.8.6 SKIPRECORD Statement
The SKIPRECORD statement skips the record immediately following the
current (last accessed) record. If the SKIPRECORD statement is
executed prior to accessing any records, then the first record in the
file is skipped. You cannot use SKIPRECORD on direct-access files.
| You can use SKIPRECORD on RMS indexed files; it does a sequential read
| on the current index as established by a previous indexed READ, or the
| primary index if no current index has been set.
The forms of the SKIPRECORD statement are:
SKIPRECORD un
or
SKIPRECORD(UNIT=un[,END=s][,ERR=s][,IOSTAT=ios])
or
11-76
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
SKIPRECORD(un[,END=s][,ERR=s][,IOSTAT=ios])
where:
un is the logical unit number of the device on which the
SKIPRECORD is being performed. Table 10-3 lists the default
logical unit numbers.
SKIPFILE
Statement
11.8.7 SKIPFILE Statement
This statement is used only for magnetic tape operations. Unless an
end-of-file has been encountered, the SKIPFILE statement advances to
the beginning of the next file. If an end-of-file has been
encountered, SKIPFILE skips the next file. If the number of SKIPFILE
executions exceeds the number of files available to be skipped, an
error occurs.
The forms of the SKIPFILE statement are:
SKIPFILE un
or
SKIPFILE (UNIT=un[,ERR=s][,IOSTAT=ios])
or
SKIPFILE (un[,ERR=s][,IOSTAT=ios])
where:
un is the logical unit number of the device on which the
SKIPFILE is being performed. Table 10-3 lists the default
logical unit numbers.
BACKFILE
Statement
11-77
FILE-CONTROL AND DEVICE-CONTROL STATEMENTS
11.8.8 BACKFILE Statement
This statement is used only for magnetic tape operations. If an
end-of-file has been encountered, the BACKFILE statement positions to
the start of the file whose end-of-file was detected. Otherwise, the
BACKFILE statement positions to the start of the file that precedes
the current (last accessed) file.
The forms of the BACKFILE statement are:
BACKFILE un
or
BACKFILE (UNIT=un[,ERR=s][,IOSTAT=ios])
or
BACKFILE (un[,ERR=s][,IOSTAT=s])
where:
un is the logical unit number of the device on which the
BACKFILE is being performed. Table 10-3 lists the default
logical unit numbers.
NOTE
On a magnetic tape with multiple files, the position
of the tape after an ENDFILE record of one file is
equivalent to the position at the beginning of the
next file.
11-78
CHAPTER 12
FORMATTED DATA TRANSFERS
Data transfers can be either formatted or unformatted. When the
internal (memory) representation of the data is translated to a
different external (peripheral storage) representation during a data
transfer, that data transfer is considered formatted.
Conversely, when the internal and external representations of the data
are the same, that data transfer is considered unformatted.
A formatted data transfer involves editing of data as it is
transferred to and from memory. FORTRAN provides you with three ways
for specifying how the data is formatted during a formatted data
transfer. These are:
1. FORMAT-Statement Formatting
2. List-Directed Formatting
3. NAMELIST-Statement Formatting
Of the three types, FORMAT-statement formatting provides you with the
most control over how the data is formatted. Section 12.1 describes
FORMAT-statement formatting.
List-directed formatting means that the formatting is controlled by
the data types of the I/O list elements. Section 12.5 describes
list-directed formatting.
NAMELIST-statement formatting is the third method for formatting the
data; the formatting is controlled by the data types of the namelist
elements. In this form, the I/O list is defined in a NAMELIST
statement and referenced by the data transfer statement. Section 12.6
describes NAMELIST-statement formatting.
|
| NOTE
|
| FOROTS/RMS supports transparent data transfers to and
| from VMS systems for all formatted data, and for
12-1
FORMATTED DATA TRANSFERS
| unformatted character data. Numeric data transfers
| are not supported. DIL (Data interchange Library)
| routines or DIU (Data Interchange Utility) should be
| used to correctly exchange numeric data between
| TOPS-20 and VMS systems.
12-2
FORMATTED DATA TRANSFERS
FORMAT-Statement
Formatting
12.1 FORMAT-STATEMENT FORMATTING
A FORMAT statement directs the editing of data during its transfer
between internal and external storage. Every formatted (FORMAT
statement) data transfer statement contains a reference to one of the
following:
1. A line containing a FORMAT statement with a format list
2. A numeric array containing a format list
3. A character expression containing a format list
4. An integer, real, or logical variable that has been assigned
a FORMAT statement number with an ASSIGN statement
The format list is made up of format specifiers.
During execution of a formatted data transfer statement, items in the
I/O list are associated with specifiers in the referenced format list.
The specifiers dictate how the various data items are formatted.
Section 12.1.1 describes how to create a format list in a FORMAT
statement; Section 12.1.2 describes how to create a format
specification as a character expression. Section 12.1.3 describes how
to create a numeric array that contains a format list. Section 12.1.4
describes how to specify a FORMAT statement using an ASSIGNed
variable.
12.1.1 Specifying a Format List in a FORMAT Statement
The general form of a FORMAT statement is:
n FORMAT fs
where:
n is the required statement number. This number,
referenced in the control-information list of an
I/O statement (see Section 10.4.2) provides the
association between the data transfer statement
12-3
FORMATTED DATA TRANSFERS
and the FORMAT statement.
fs is a format specification. The form of a format
specification is:
([format list])
where:
format list is a list of items which may take any of the
following forms:
[r] ed
or
ned
or
[r] (fl)
where:
r is a nonzero, unsigned, integer constant called a
repeat specification.
ed is a repeatable edit descriptor (see Section
12.2.1).
ned is a nonrepeatable edit descriptor (see Section
12.2.2).
fl is a nonempty format list.
The only placement restrictions for FORMAT statements are that they
follow PROGRAM, FUNCTION, SUBPROGRAM, or BLOCK DATA statements, and
that they precede the END statement.
The following example illustrates FORMAT-statement formatting. The
FMT specifier in the WRITE statement references the label of FORMAT
statement 101. This FORMAT statement contains a list of edit
descriptors (X, I, and F) that dictate the formatting of the data in
I/O list (variables J, Y, and Z).
J=2
Y=3.0
Z=5.1
WRITE(UNIT=5,FMT=101)J,Y,Z
101 FORMAT(1X,I,F,F)
12-4
FORMATTED DATA TRANSFERS
12.1.2 Specifying a Format Specification as a Character Expression
You can store format specifications in character variables, character
arrays, character array elements, character substrings, or character
expressions.
A character format specification must be of the form described in
Section 12.1.1. Note that the form begins with a left parenthesis and
ends with a right parenthesis. Character data may follow the right
parenthesis that ends the format specification, with no effect on the
format specification. Blank characters may precede the format
specification.
If the format identifier is a character array name, the format
specification may be contained in more than the first element of the
array. (A character array format specification is considered to be a
concatenation of all the array elements of the array in the order
given by array element ordering (see Section 4.3.3).)
However, if a character array element name is specified as a format
identifier, the length of the format specification must not exceed the
length of the array element.
The following example shows the same format specification used in the
examples in Section 12.1.1. This time, however, instead of
referencing the format specification by statement number, or
referencing the name of a numeric array, the data transfer statement
references the name of the character variable in which the format
specification is contained.
J=2
Y=3.0
Z=5.1
CHARACTER FORNAM*10
FORNAM = '(1X,I,F,F)'
WRITE(UNIT=5,FMT=FORNAM)J,Y,Z
12.1.3 Specifying a Format Specification in a Numeric Array
An alternative to using FORMAT statements is to store the format
specification in a numeric array.
The format specifications are associated with a data transfer
statement by referencing the array name containing the format
specification, instead of a statement label of a FORMAT statement.
The following example shows the same format specification used in the
example in Section 12.1.1. This time, however, instead of referencing
the format specification by statement number, the data transfer
12-5
FORMATTED DATA TRANSFERS
statement references the name of the numeric array in which the format
specification is contained.
INTEGER FORNAM(2)
FORNAM(1)='(1X,I'
FORNAM(2)=',F,F)'
J=2
Y=3.0
Z=5.1
WRITE(UNIT=5,FMT=FORNAM)J,Y,Z
END
In the above example the format specification is stored in both words
of array FORNAM. This is because the format contains ten characters:
the first five are in FORNAM(1); and the last five are in FORNAM(2).
NOTE
When storing a format specification in an array,
always include the outer most parentheses enclosing
the format specifiers. Note that the word FORMAT
should not be included in the string.
12.1.4 Specifying a FORMAT Statement Using an ASSIGNed Variable
Integer, real, or logical variables that have been ASSIGNed FORMAT
statement numbers can be used as format specifiers. (See Section 8.3
for information on the ASSIGN (statement label) assignment statement.)
The variable is assigned a statement number by an ASSIGN statement.
The format specifier references the variable that refers to the
statement number it has been assigned.
The following example shows the same format specification used in the
examples in Sections 12.1.1, 12.1.2, and 12.1.3. This time, however,
instead of referencing the format specification by statement number,
the data transfer statement references a variable that has been
assigned a statement number by an ASSIGN statement.
ASSIGN 101 TO IFORMT
WRITE(UNIT=5,FMT=IFORMT)J,Y,Z
101 FORMAT(1X,I,F,F)
12.1.5 The Ordering and Interpretation of Format List Items
For standard conforming programs, all items within the format list
should be separated by commas, with the exception of the following
12-6
FORMATTED DATA TRANSFERS
cases:
1. Between a P edit descriptor and an immediately following F,
E, D, or G edit descriptor (See Section 12.4.11)
2. Before or after a slash edit descriptor (See Section 12.4.5)
3. Before or after a colon edit descriptor (See Section 12.4.6)
In FORTRAN-10/20, the use of commas to delimit format edit descriptors
within a format list is optional as long as no ambiguity exists. For
example,
FORMAT (3X,A2)
can be written as
FORMAT (3XA2)
But the specification
FORMAT (I22I5)
is ambiguous, since it can represent
FORMAT (I22,I5) or FORMAT (I,22I5)
and requires the comma to eliminate ambiguity.
FORMAT-Statement
Edit Descriptors
12.2 EDIT DESCRIPTORS
Edit descriptors within the format list describe the manner of editing
performed on the data being transferred.
For example, when you transfer integers from a file to memory, you use
an I edit descriptor. When the data transfer statement is executed,
an item in the I/O list is associated with the I edit descriptor in
the format list, and the following results:
1. Before being stored in memory, the data is converted to an
internal integer format by the I edit descriptor in the
format list.
12-7
FORMATTED DATA TRANSFERS
2. The memory location in which the data is stored is identified
by the I/O list element.
The following sample program demonstrates how an integer is read from
the terminal (external device) into the memory location identified in
the I/O list of the ACCEPT statement.
PROGRAM FORMAT
TYPE *,'Please enter a two digit number:'
ACCEPT 101,K
101 FORMAT(I2)
TYPE 102,K
102 FORMAT(1X,I5)
END
The sample output below shows what happens when the user executes the
above program. The user enters 78 in response to the ACCEPT
statement. This causes the integer value to be stored in the variable
K according to the I edit descriptor in FORMAT statement 101. Then
the type statement causes the value of variable K to be printed at the
terminal according to the I edit descriptor in FORMAT statement 102.
EXECUTE TEST
LINK: Loading
[LNKXCT FORMAT execution]
Please enter a two digit number:
78
78
CPU Time 0.1 Elapsed Time 8.7
The I edit descriptor is an example of a repeatable edit descriptor.
FORTRAN has two types of edit descriptors: repeatable (Section
12.2.1) and nonrepeatable (Section 12.2.2). The third type of item
that appears in a format list is the carriage-control specifier
(Section 12.2.3).
Repeatable Edit
Descriptors
12.2.1 Repeatable Edit Descriptors
A repeatable edit descriptor may be preceded by an optional, unsigned,
12-8
FORMATTED DATA TRANSFERS
nonzero, integer constant that specifies a repeat count. This integer
is called a repeat specification.
Using a repeat specification in an edit descriptor gives you a
shorthand way to specify multiple fields with a single specification.
For example, without using the repeat specification, if you wanted to
specify four fields, each of which contain an integer value that is
six characters long, you might construct the following FORMAT
statement:
101 FORMAT (1X,I6,I6,I6,I6)
If you use the repeat specification, however, you need only specify
the edit descriptor and field width a single time, as follows:
101 FORMAT (1X,4I6)
These two FORMAT statements are equivalent.
Table 12-1 lists the repeatable edit descriptors. Each descriptor
listed in the table is shown in its complete form. The key at the
bottom of Table 12-1 describes all the optional elements in each edit
descriptor. The right-most column of Table 12-1 references the
section in which each edit descriptor is discussed.
12-9
FORMATTED DATA TRANSFERS
Table 12-1: Repeatable FORTRAN Edit Descriptors
Nonrepeatable Edit
Descriptors
12.2.2 Nonrepeatable Edit Descriptors
A nonrepeatable edit descriptor can not be preceded by a repeat
12-10
FORMATTED DATA TRANSFERS
specification. The nonrepeatable edit descriptors provide a variety
of editing possibilities, such as positioning within a record,
including character constants in a FORMAT statement, and delimiting
records within a single format descriptor.
Table 12-2 lists the nonrepeatable edit descriptors. The format,
function, and section number where each descriptor is discussed are
listed in the table.
12-11
FORMATTED DATA TRANSFERS
Table 12-2: Nonrepeatable FORTRAN Edit Descriptors
Carriage-Control
Specifiers
12.2.3 Carriage-Control Specifiers
In a data output transfer, the first character of each record can be
used for carriage control. A carriage-control specifier dictates the
12-12
FORMATTED DATA TRANSFERS
action of the printing mechanism on output devices. For example,
carriage-control specifiers determine the vertical spacing for
line-printer output.
NOTE
The CARRIAGECONTROL specifier of the OPEN statement
enables you to decide how the first character of each
record is treated. Depending on the value of the
CARRIAGECONTROL specifier, the first character can be:
1. Replaced with the appropriate printer-control
character(s).
2. Disregarded as a carriage-control character and,
instead, be transferred as part of the record.
For more information on the CARRIAGECONTROL specifier,
see Section 11.3.6
The carriage-control specifier may be written as a character constant.
The following example shows the blank carriage-control character in a
FORMAT statement:
WRITE(5,101)
101 FORMAT(' ','This is a string')
END
When this example is executed, the string in the format list is
printed on unit 5, the terminal, as follows:
This is a string
If you omit the carriage-control specifier from a data output transfer
format list, FOROTS interprets the first character to be output to the
record as the carriage-control character. Using the example above, if
we omit the blank specifier, FOROTS assumes that the first character
encountered (in this case, the "T" in "This") is the carriage-control
character. Executing this example, after removing the
carriage-control specifier, causes the first character to be stripped
from the character constant. Thus, the output at the terminal is:
his is a string
The carriage-control characters are summarized in Table 12-3. The $
(dollar sign) output edit descriptor modifies the action of the
carriage-control specifier (see Section 12.4.4).
12-13
FORMATTED DATA TRANSFERS
Table 12-3: Carriage-Control Specifiers
I/O List & Format List
Interaction
12.3 INTERACTION OF INPUT/OUTPUT LIST AND FORMAT LIST
This section describes how the I/O list and the format list interact
during a data transfer.
12.3.1 General Description
Format control is initiated by execution of a formatted data transfer
statement. The actions performed by format control depend on the
interaction of the edit descriptors in the format specification and
the I/O list elements in the data transfer statement.
12-14
FORMATTED DATA TRANSFERS
The following example shows how the I/O list elements in a data
transfer statement interact with the edit descriptors in the format
list in a simple data transfer.
READ (5,100) N,X,Y
100 FORMAT (I5,F12.0,F10.0)
In this example, the I/O list is
N,X,Y
and the format specification is
(I5,F12.0,F10.0)
The variables in the I/O list and the specifiers in the format are
matched up as follows:
N I5
X F12.0
Y F10.0
A formatted data transfer statement matches elements of the I/O list
and specifiers in the format specification. The matching proceeds
from left to right, one I/O list element to one repeatable edit
descriptor.
In the above example, there are three elements in the I/O list and
three format specifiers. However, the interactions can be more
complicated than those in the example. A format specifier can be
preceded by a repeat count, in which case it corresponds to more than
one element in the I/O list. Also, an element of the I/O list can be
an array name, in which case it can correspond to more than one format
specifier. The number of elements in the I/O list and in the format
specification do not have to be the same.
Table 12-4 details what happens in these more complex cases.
12-15
FORMATTED DATA TRANSFERS
Table 12-4: Record, Format List, and I/O List Interaction
12-16
FORMATTED DATA TRANSFERS
The execution of a formatted I/O statement proceeds by matching I/O
list elements and FORMAT edit descriptors. The edit descriptors I, O,
Z, R, F, E, D, G, L, A, and Q each correspond to one element of the
I/O list. No I/O list element corresponds to H, X, P, T, :, $, S, SP,
SS, BN, BZ, or apostrophe edit descriptors. If one of these
descriptors is encountered, it is executed and the format scan
continues.
12.3.2 Formatted Input
A formatted input statement begins by reading a record from the
specified unit. The format is scanned from left to right. X, P, T,
BN, BZ, and / edit descriptors are executed as they are encountered.
If an I, O, Z, R, F, E, D, G, L, A, or Q descriptor is encountered,
data is read into the corresponding I/O list element as specified by
the edit descriptor.
If the I/O list contains no more elements, execution of the READ
statement ends. Additional records will be read from the specified
unit when a slash occurs in the format, or when the last right
parenthesis of the format is reached, and I/O list elements remain to
be filled.
12-17
FORMATTED DATA TRANSFERS
When an input record is terminated by a slash or by the end of the
format, any data left in the input record is discarded. If the input
record is exhausted before the data transfers are completed, the
remainder of the transfer is completed as if the record were extended
with blanks.
12.3.3 Formatted Output
A formatted output statement begins by scanning the format. The H, X,
P, T, BN, BZ, :, /, $, S, SS, SP, and apostrophe edit descriptors are
executed as they are encountered. If an I, O, Z, R, F, E, D, G, L, or
A descriptor is encountered, data is translated from the corresponding
I/O list element, as specified by the edit descriptor, and placed in
the output record.
If the I/O list contains no more elements, the output record is
written to the specified unit, and execution of the WRITE statement
ends. Additional records will be written to the specified unit when a
slash occurs in the format, or when the last right parenthesis is
reached, and I/O list elements remain to be transferred.
12.3.4 Embedded Format Specifications
Format specifications may contain embedded format specifications with
optional repeat specifications. If a repeat specification is used,
the entire format specification that it precedes is scanned the
specified number of times during the I/O transfer. In the example:
WRITE (1,100) A,B,C,D,E,F,G,H,I,J
100 FORMAT (F10.2,4(I5,1X,I3),I8)
the variable A is matched with the format item F10.2. Then, the
variable B is matched with I5, variable C with I3, variable D with I5,
and so on for four iterations of the embedded format specification.
Finally, the variable J is matched with the format item I8.
If no repeat specification is used preceding an embedded format
specification, a repeat count of 1 is implied.
When the last right parenthesis of the format is reached, and more I/O
list elements remain to be transferred, a new record is started and
format scanning continues. The scanning continues at the beginning of
the format specification whose right parenthesis is the next to last
right parenthesis in the format. If there are no embedded format
specifications, format scanning continues at the beginning of the
format.
For example:
12-18
FORMATTED DATA TRANSFERS
DIMENSION A(100)
INTEGER CASE
CASE=33
WRITE (1,100)CASE,(A(I),I=1,100)
100 FORMAT ('THIS IS CASE ',I6,//,4(1X,F10.5))
After A(1) through A(4) are written, a new line is started and format
scanning continues at the beginning of the embedded format
specification. Thus, A(5) through A(8) are written; a new record is
started, and so forth.
The output file would appear as follows:
THIS IS CASE 33
A(1) A(2) A(3) A(4)
A(5) A(6) A(7) A(8)
A(9) A(10) A(11) A(12)
.
.
.
Example:
DIMENSION A(5),DAT1(100),B(4,100),DAT2(100)
WRITE (1,100) CASE,(A(K),K=1,5),(DAT1(J),(B(I,J),I=1,4),
1 DAT2(J),J=1,100)
100 FORMAT ('CASE',I5,//,5(1X,F10.3),/,(F10.3,4(3X,F15.5)
1 ,1X,F10.3))
In this example, after A(1) through A(5), DAT1(1), B(1,1) through
B(4,1), and DAT2(1) are written, a new record is started, and format
scanning begins. The format scanning begins at the embedded format
specification following the '/' (the specification whose right
parenthesis is the next to last right parenthesis).
The output file would appear as follows:
CASE 33
A(1) A(2) A(3) A(4) A(5)
DAT1(1) B(1,1) B(2,1) B(3,1) B(4,1) DAT2(1)
DAT1(2) B(1,2) B(2,2) B(3,2) B(4,2) DAT2(2)
DAT1(3) B(1,3) B(2,3) B(3,3) B(4,3) DAT2(3)
.
.
.
12-19
FORMATTED DATA TRANSFERS
12.4 FORMAT EDITING
Tables 12-1 and 12-2 describe forms of all the FORMAT edit
descriptors. The edit descriptors enable you to specify the form of a
record and to specify the editing of the data as it is transferred.
The edit descriptors are described according to the character used to
accomplish a particular modification to the data or record in which
the data are stored.
Apostrophe (')
Editing
12.4.1 Apostrophe (') Editing
The apostrophe (') edit descriptor (single-quote) enables you to
include a character constant in a format list.
The form of the apostrophe edit descriptor is:
'h1...hn'
where:
'h1...hn' is a character constant.
To include an apostrophe as part of the character constant, you must
use two successive apostrophes.
This descriptor is only used for output; the characters enclosed by
the apostrophes are written.
Example:
TYPE 10
10 FORMAT (' That''s the way!')
will output
That's the way!
12-20
FORMATTED DATA TRANSFERS
H
Editing
12.4.2 H Editing
The H edit descriptor (also called the Hollerith descriptor) enables
you to include character strings in a format list.
The form of the H edit descriptor is:
nHh1...hn
where:
n is a nonzero, unsigned, integer constant that indicates
the total number of ASCII characters included in the
string.
h1...hn is a string of ASCII characters. (The ASCII character
set is described in Appendix B.)
You may transmit alphanumeric data directly from the FORMAT statement
using either the H or apostrophe specifiers.
This descriptor is only used for output; the n characters that follow
the H are written. For example, you can use the following statement
sequence to print the words PROGRAM COMPLETE on the printer:
PRINT 101
101 FORMAT (17HbPROGRAMbCOMPLETE)
The result of apostrophe editing is the same as Hollerith editing.
For example, you may use the descriptors:
101 FORMAT (17HbPROGRAMbCOMPLETE)
and
101 FORMAT ('bPROGRAMbCOMPLETE')
in the same manner.
Apostrophes can appear anywhere within a Hollerith edit descriptor
without having to be represented by two apostrophes. However, if the
H edit descriptor occurs within a character constant, the apostrophe
is written as two apostrophes, which are counted as one character.
12-21
FORMATTED DATA TRANSFERS
Positional
Editing
12.4.3 Positional Editing
The positional edit descriptors specify the position at which the next
character will be transmitted to or from the record. The positional
edit descriptors are: T, TL, TR, and X.
The T edit descriptor specifies the character position within a record
where the next character will be transmitted (see Section 12.4.3.1).
The TL and TR descriptors specify the number of character positions to
the left or right, respectively, of the current position for the
character position of the next character (see Section 12.4.3.1).
The X descriptor specifies the number of character positions to the
right of the current position for the character position of the next
character (see Section 12.4.3.2).
NOTE
On output, a record is initially filled with blanks.
Therefore, fields skipped by the positional editing
descriptors will be blank-filled. However, the output
record length is determined by actual output. Merely
specifying a positional editing descriptor with no
output will not change the record size. Thus, the
record written with:
FORMAT (I6,50X,T10,I3)
will have a record length of 13 characters, since no
output was done after the 50X.
Examples:
The statement sequence:
PRINT 2
2 FORMAT (T50,'BLACK',T30,'WHITE')
causes the following line to be printed:
WHITE BLACK
12-22
FORMATTED DATA TRANSFERS
(print position 30) (print position 50)
The statement sequence:
1 FORMAT (T35,'MONTH')
READ (2,1)
causes the first 34 characters of the input data associated with
logical unit 2 to be skipped, and the next five characters to replace
the characters M, O, N, T, and H in storage.
If an input record containing:
ABCbbbXYZ
is read with the format specification:
10 FORMAT (T7,A3,T1,A3)
then the characters XYZ and ABC are read in that order.
You can use the field descriptor nX to introduce blanks into output
records or to skip characters of input records. The letter X
specifies the operation, and n is a positive integer that specifies
the number of character positions to be either made blanks (output) or
skipped (input).
The statement:
FORMAT (5HbSTEP,I5,10X,2HY=,F7.3)
may be used to print the line:
STEPbbb28bbbbbbbbbbY=b-3.872
T, TL, and TR
Editing
12.4.3.1 T, TL, and TR Editing - The T edit descriptor specifies that
the transmission of the next character to or from a record is to occur
at the specified character position.
The form of the T descriptor is:
Tc
12-23
FORMATTED DATA TRANSFERS
where:
c is a positive, unsigned, integer constant that indicates the
character position to or from which the next character will
be transferred.
For example:
FORMAT (T20,I5,T8,I2)
specifies that the characters read or written for the I5 descriptor
will start in character position 20, and the characters read or
written for the I2 descriptor will start in character position 8. For
output to carriage-control devices (line printer and terminal), Tn
specifies that n-1 will be the next character written, since the
character position 1 is the carriage-control character position.
The TL edit descriptor specifies that the transmission of the next
character to or from the record is to occur at a position which is a
specified number of positions backward from the current position.
The form of the TL edit descriptor is:
TLc
where:
c is a positive, unsigned, integer constant that indicates the
character position, c positions backward from the current
position, to or from which the next character will be
transferred. If c would cause transmission to start at a
position before the beginning of the current record,
transmission will start instead at position one.
For example:
FORMAT (I5,T13,A5,TL10,I2)
specifies that the characters read or written for the A5 descriptor
will start at character position 13, and that the characters read or
written for the I2 descriptor at will start at character position 8.
The TR edit descriptor specifies that the transmission of the next
character to or from a record will occur at a position that is a
specified number of positions forward from the current position. The
function of this form is identical to that of the X descriptor (see
Section 12.4.3.2).
The form of the TR edit descriptor is:
TRc
12-24
FORMATTED DATA TRANSFERS
where:
c is a positive, unsigned, integer constant that indicates the
character position, c positions forward from the current
position, from which the next character will be transferred.
Example using all three types of T descriptor:
TYPE 10
10 FORMAT(' 234567890123456789012345678901234567890')
TYPE 20
20 FORMAT(T29,'BLACK',T10,'WHITE')
TYPE 30
30 FORMAT(T10,'9012',TR5,'8901')
TYPE 10
TYPE 40
40 FORMAT(T20,'<SECOND>',TL10,'>FIRST<')
END
EXECUTE TEST2.FOR
FORTRAN: TEST2
MAIN.
LINK: Loading
[LNKXCT TEST2 execution]
234567890123456789012345678901234567890
WHITE BLACK
9012 8901
234567890123456789012345678901234567890
>FIRST<ND>
CPU time 0.1 Elapsed time 0.5
In FORMAT 20, 'BLACK' is written, then 'WHITE' is written to the left
of it. In FORMAT 30, five positions are skipped between the two
character strings being printed. In FORMAT 40, '<SECOND>' is written,
the format goes back ten positions and writes '>FIRST<' over the
previously written character string.
X
Editing
12-25
FORMATTED DATA TRANSFERS
12.4.3.2 X Editing - The X edit descriptor specifies that the
transmission of characters to or from a record will occur a specified
number of characters forward from the current position.
The form of the X edit descriptor is:
[n]X
where:
n is an optional, unsigned, positive, integer constant that
indicates the number of characters forward from the current
position, at which the next character will be transmitted.
The default value is 1.
Example:
TYPE 10
10 FORMAT(' 1234567890123456789012345678901234567890')
TYPE 20
20 FORMAT(' A WORD OR TWO',10X,'OR THREE')
END
EXECUTE TEST3.FOR
FORTRAN: TEST3
MAIN.
LINK: Loading
[LNKXCT TEST3 execution]
1234567890123456789012345678901234567890
A WORD OR TWO OR THREE
CPU time 0.2 Elapsed time 2.1
In this example, ten positions are skipped between the printing of
'A WORD OR TWO' and 'OR THREE'.
$ (Dollar Sign)
Editing
12-26
FORMATTED DATA TRANSFERS
12.4.4 $ (Dollar Sign) Editing
The $ (dollar sign) output edit descriptor suppresses all carriage
control at the end of the current record (for CARRIAGECONTROL='LIST')
or at the beginning of the next record (for CARRIAGECONTROL='FORTRAN'
or 'TRANSLATED').
This descriptor is used for interactive I/O; it leaves the terminal
position at the end of the text so that a response will follow the
output on the same line.
Example:
WRITE (5,10)
READ (5,*) N
10 FORMAT (' Number of samples: ', $)
WRITE (5,20)
READ (5,*) X
20 FORMAT (' Mean value: ', $)
END
If the user enters 100 for N and 1.23 for X, executing the program
will produce the typescript:
Number of samples: 100
Mean value: 1.23
The $ edit descriptor can be used to append the output of several
statements into a single line. For example:
DO 10 I = 1,10
10 WRITE (5,20) I
20 FORMAT (1X,I3,$)
WRITE (5,20)
END
will produce one line of output:
1 2 3 4 5 6 7 8 9 10
The $ edit descriptor is ignored for input.
/ (Slash)
Editing
12-27
FORMATTED DATA TRANSFERS
12.4.5 / (Slash) Editing
The / (slash) edit descriptor indicates the end of data transfer for a
record. Two consecutive slashes indicate the transmission of an empty
record.
On input to a file connected for sequential access, the remaining
portion of the current record is skipped, and the file is positioned
at the beginning of the next record. This new record becomes the
current record. On output to a file connected for sequential access,
the current record is terminated, and a new record is created, which
becomes the current and last record of the file.
A record that contains no characters may be written. Also, an entire
record may be skipped on input.
If the file is connected for direct access, the record number is
increased by one, and the file is positioned at the beginning of the
record that has that record number. This record becomes the current
record.
The following statements will write a record with no characters:
WRITE (1,100)
100 FORMAT(/)
To handle a group of I/O records where different records have
different field descriptors, use a slash to indicate a new record.
For example, the statement
FORMAT (3O8/I5,2F8.4)
is equivalent to
FORMAT (3O8)
for the first record, and
FORMAT (I5,2F8.4)
for the second record.
You may omit separating commas when you use a slash. When n slashes
appear at the beginning or end of a format, n blank records will be
written on output or skipped on input. When n slashes appear in the
middle of a format, n-1 blank records are written on output or n-1
records are skipped on input.
12-28
FORMATTED DATA TRANSFERS
: (Colon)
Editing
12.4.6 : (Colon) Editing
The : (colon) edit descriptor terminates format control if there are
no more items in the I/O list of the corresponding data transfer
statement. The colon edit descriptor has no effect if there are any
items left in the I/O list of the corresponding data transfer
statement.
Example:
X1 = 100
X2 = 200
X3 = 300
TYPE 10, X1,X2
10 FORMAT(F6.1,F6.1,:,'THIS SHOULD NOT PRINT',F6.1)
TYPE 20,X1,X2,X3
20 FORMAT(F6.1,F6.1,:,' BUT THIS SHOULD ',F6.1)
END
EXECUTE TEST4.FOR
FORTRAN: TEST4
MAIN.
LINK: Loading
[LNKXCT TEST4 execution]
100.0 200.0
100.0 200.0 BUT THIS SHOULD 300.0
CPU time 0.1 Elapsed time 1.5
S, SP, and SS
Editing
12-29
FORMATTED DATA TRANSFERS
12.4.7 S, SP,and SS Editing
The S, SP, and SS edit descriptors control the output of the optional
plus sign in numeric output fields. These descriptors are used as
follows:
S indicates that the system-defined action is taken. The
system-defined specification for Digital FORTRAN is SS.
SP indicates that the plus sign is printed in all positive
numeric output fields.
SS indicates that the plus sign is not printed in positive
numeric output fields. This descriptor is the default.
The S, SP, and SS edit descriptors affect only I, F, E, D, and G
editing during the execution of a data transfer output statement;
these edit descriptors have no effect during input transfers. These
descriptors stay in effect until the end of the I/O transfer or until
another S, SP, or SS is encountered.
Example:
X1 = 100
X2 = 200
X3 = 300
X4 = 400
TYPE 10, X1,X2,X3,X4
10 FORMAT(' ',S,F7.1, SP,F7.1, SS,F7.1, SP,F7.1)
END
EXECUTE TEST5.FOR
FORTRAN: TEST5
MAIN.
LINK: Loading
[LNKXCT TEST5 execution]
100.0 +200.0 300.0 +400.0
CPU time 0.1 Elapsed time 0.2
In this example, X2 and X4 have plus signs because of the SP
descriptors in front of the F descriptors that correspond to them.
P
Editing
12-30
FORMATTED DATA TRANSFERS
12.4.8 P Editing
The P edit descriptor is used to specify a scale factor for F, E, D,
and G edit descriptors.
The form of the P edit descriptor is:
kP
where:
k is an optionally signed integer constant representing the
scale factor.
If a scale factor is not specified in a format list, a scale factor of
zero is assumed. Once a scale factor is specified in a format list,
that scale factor remains in effect for all F, E, D, and G edit
descriptors until a new scale factor is specified, or to the end of
the execution of the current I/O statement. Scale factors have no
effect on I, Z, and O edit descriptors.
The scale factor affects the F, E, D, and G data transfers as follows:
On input:
If there is an exponent field, the scale factor k has no effect. If
there is no exponent field on the number read in, the number is
multiplied by 10**(-k) before being assigned to the input variable.
On output:
The basic real constant part of the quantity, in E and D editing only,
is multiplied by 10**k and the exponent is reduced by k. For G
editing, the scale factor has no effect unless the magnitude of the
data item to be edited is outside of the range that permits the use of
F editing. If G editing is specified, and the magnitude of the data
item to be edited is such that E editing is required, the scale factor
has the same effect as with E output editing (see Section 12.4.11.3).
The comma is optional between a P edit descriptor and immediately
following F, E, D, or G edit descriptors.
For example, assume the data involved is the real number 26.451; the
edit descriptor
F8.3
produces the external field
bb26.451
The addition of the scale factor of -1P, as in
12-31
FORMATTED DATA TRANSFERS
FORMAT (-1P,F8.3)
produces the external field
bbb2.645
When you add a scale factor to D, E, and G (external field not a
decimal fixed-point) edit descriptors, the scale factor multiplies the
number by the specified power of ten, and the exponent is changed
accordingly.
In input operations, type F (and type G, if the external field is
decimal fixed-point) conversions are the only ones affected by scale
factors.
When you add a scale factor to a D or E edit descriptor, it specifies
a power of 10 so that the external form of the number has its mantissa
multiplied by the specified power of 10; its exponent is adjusted
accordingly.
For example, assume the data involved is the real number 12.49; the
edit descriptor
E11.3
produces the external field
bb0.125E+02
The addition of the scale factor 2P, as in
FORMAT (2P,E11.3)
produces the external field
bb12.49E+00
With a scale factor of zero, the number of significant digits printed
by a format of the form:
Ew.d
or
Dw.d
is the number of digits to the right of the decimal point.
For a negative scale factor nP, for -d<n<0, there will be ABS(n)
leading zeros and d-ABS(n) significant digits after the decimal point
(for a total of d digits after the decimal point). If n<-d, there
will be d insignificant digits (zeros) to the right of the decimal
12-32
FORMATTED DATA TRANSFERS
point.
If the scale factor nP is positive, for 0<n<d+2 there will be n
significant digits to the left of the decimal point and d-n+1
significant digits to the right of the decimal point (for a total of
d+1 significant digits). If n>d+2, there will be d+1 significant
digits and n-d-1 insignificant trailing zeros on the left of the
decimal point.
If the data to be printed is 12.493, these formats produce results as
follows:
FORMAT OUTPUT SIGNIFICANT REASON
DIGITS
E15.3 bbbbbb0.125E+02 3 n=0
1PE15.3 bbbbbb1.249E+01 4 n<d+2
-1PE15.3 bbbbbb0.012E+03 2 -d<n
2PE15.3 bbbbbb12.49E+00 4 n<d+2
-3PE15.3 bbbbbb0.000E+05 0 n<-d
4PE15.3 bbbbbb1249.E-02 4 n<d+2
6PE15.3 bbbb124900.E-04 4 n>d+2
Example:
TYPE 10
10 FORMAT(' Type in a real number')
ACCEPT 20,X1
20 FORMAT(2P,F)
TYPE 30,X1
30 FORMAT(' Number read with P=2 =',F,
1 /,' (Number read)*10**(-2)')
TYPE 40,X1
40 FORMAT(/,' The above number written with P=2',/,
1 ' is =',2P,F,/,' (Number above)*10**(2)')
END
EXECUTE TESTP.FOR
FORTRAN: TESTP
MAIN.
LINK: Loading
[LNKXCT TESTP execution]
Type in a real number
5.
12-33
FORMATTED DATA TRANSFERS
Number read with P=2 = 0.0500000
(Number read)*10**(-2)
The above number written with P=2
is = 5.0000000
(Number above)*10**(2)
CPU time 0.2 Elapsed time 5.1
The number the program receives is (5.)*(10**(-2)) and the value typed
out is (.05)*(10**(2)).
BN and BZ
Editing
12.4.9 BN and BZ Editing
The BN and BZ edit descriptors specify how blanks other than leading
blanks are interpreted only for numeric input fields where a width has
been specified. These edit descriptors have no effect on numeric
output fields.
The BZ descriptor specifies that blanks will be read as zeroes. The
BN descriptor specifies that blanks will not be read as zeroes. The
use of the BN or BZ edit descriptors in a format overrides the BLANK=
specifier in the OPEN statement for the duration of the use of that
format. (The BLANK= specifier is described in Section 11.3.3.)
For example:
ACCEPT (FMT=101)A,B,C,D
101 FORMAT (BN,I5,F10.2,BZ,F10.2,F8.5)
reads the first two numbers of data, ignoring blanks embedded in the
numbers. Then the program reads the second two numbers, substituting
zeroes for blanks embedded in the numbers.
Q
Editing
12-34
FORMATTED DATA TRANSFERS
12.4.10 Q Editing
The Q edit descriptor sets a corresponding integer variable in the I/O
list to the number of characters left in the record being transferred.
This descriptor is for use with input transfers only. You can use
multiple Q descriptors in the same format list. The Q edit descriptor
is useful when you need to know the number of characters remaining in
a record.
For example:
TYPE *,'Enter text:'
ACCEPT 100,L,J1
100 FORMAT (A5,Q)
when used to read the data
Enter text:
HELLO THIS IS A TEST
would yield the value 15 for variable J1, since there are 20
characters in the data, and A5 reads 5 of them.
Numeric
Editing
12.4.11 Numeric Editing
The I, F, E, D, G, Z, and O edit descriptors are used to specify the
input and output of integer, real, complex, double-precision,
hexadecimal, and octal data.
The numeric edit descriptors are repeatable, and can be used without
specifying size. For output, if you use a numeric edit descriptor
without specifying a field width, the defaults shown in Table 12-5 are
used.
For input, the data is scanned until a blank, comma, or character
illegal for the specified edit descriptor is encountered, except for A
format, which uses the defaults shown in Table 12-5.
12-35
FORMATTED DATA TRANSFERS
Table 12-5: Default Field Widths for Numeric Edit Descriptors
The following conventions apply to all I/O transfers using the numeric
edit descriptors:
1. The interpretation of blanks is determined by a combination
of any BLANK= specifier in the corresponding OPEN statement
(see Section 11.3.3), and any BN or BZ edit descriptor (see
Section 12.4.9) that is currently in effect in the format
list. A field of all blanks is always equal to zero.
2. On input transfers, with F, E, D, and G editing, a decimal
point appearing in the input field overrides the portion of
the edit descriptor that specifies the location of the
decimal point.
3. On output transfers, the representation of a positive or zero
value in the field may be prefixed with a plus, as controlled
by the S, SP, and SS edit descriptors (see Section 12.4.7).
The representation of a negative value in the field is
12-36
FORMATTED DATA TRANSFERS
prefixed with a minus sign.
4. On output transfers, the representation of the transferred
datum is right-justified in the specified field. If the
number of characters produced by the editing is smaller than
the specified field width, leading blanks are inserted in the
field.
5. On output transfers, if the number of characters produced
exceeds the field width, or if an exponent exceeds its length
(as specified in the Ew.dEe or Gw.dEe forms), the entire
field width, represented by w, is filled with asterisks.
The next sections describe the individual numeric edit descriptors.
I
Editing
12.4.11.1 I Editing - The I edit descriptor specifies integer
editing.
The form of the I edit descriptor is:
[r]I[w[.m]]
where:
r is an optional, nonzero, unsigned, integer constant
indicating how many fields of I are being specified. The
default is one field.
w is an optional, nonzero, unsigned, integer constant that is
equal to the total number of digits in the integer field
being described. If w is not specified, for output, the
value is 15 (the default); for input, the data is scanned
until a blank, comma, or character illegal for the I edit
descriptor is encountered.
.m is an optional, unsigned, integer constant (separated from w
by a period) that indicates the minimum number of digits to
be output to the integer field being described. The default
is one digit (I15.1). If necessary, leading zeroes are
output.
The value of m must not exceed the value of w. If m is zero
12-37
FORMATTED DATA TRANSFERS
and the value of the internal data item is zero, the output
field consists of only blank characters, regardless of the
sign control in effect.
On input, the Iw.m and the Iw forms of the I edit descriptor are
treated the same.
Example:
10 FORMAT(I,I8,2I9.5)
The first data item is output as a 1- to 15-digit right-justified
integer in the first 15 columns. The second item is a 1- to 8-digit
integer occupying the next 8 columns. The third and fourth items are
5- to 9-digit integers occupying 9 columns each, with leading zeroes
appended to the data to make them 5 digits if necessary.
F
Editing
12.4.11.2 F Editing - The F edit descriptor specifies real
(floating-point) editing.
The form of the F edit descriptor is:
[r]F[w.d]
where:
r is an optional, nonzero, unsigned, integer constant
indicating the number of fields of F being specified. The
default is one field.
w is an optional, nonzero, unsigned, integer constant equal to
the total number of digits in the F field being described.
This total includes the digits to the right and left of the
decimal point, the decimal point itself, and (if included)
the sign. On input, if the decimal point is omitted, the
rightmost d digits of the string, with leading zeros assumed
if necessary, are interpreted as the fractional part of the
value represented.
If w is not specified, for output, the value for
single-precision is 15 (the default), and the value for
double-precision is 25 (the default). For input, the data
12-38
FORMATTED DATA TRANSFERS
is scanned until a blank, comma, or character illegal for
the F edit descriptor is encountered.
.d is an optional, nonzero, unsigned, integer constant that
specifies the total number of fractional digits in the field
of width w. The default for single-precision is 7 digits;
the default for double-precision is 18. The maximum is 63
digits.
NOTE
If the default field width for F format (with no width
specified) is too small for the data, the field width
expands to fit the data.
E and D
Editing
12.4.11.3 E and D Editing - The E and D edit descriptors specify
editing of real data.
The form of the E edit descriptor is:
[r]E[w.d[Ee]]
The form of the D edit descriptor is:
[r]D[w.d[Ee]]
where:
r is an optional, nonzero, unsigned, integer constant that is
equal to the number of E or D fields being described. The
defaults are one single-precision E field and one
double-precision D field.
w is an optional, nonzero, unsigned, integer constant equal to
the total number of digits in the E or D field being
described. The total for both types of fields is equal to:
1. The total number of digits on both sides of the decimal
point
12-39
FORMATTED DATA TRANSFERS
2. The decimal point itself
3. The sign for the number (if included)
4. The exponent character (if included)
5. The digits in the exponent
If w is not specified, for output, the value for single
precision is 15 (the default), and the value for double
precision is 25 (the default). For input, the data is
scanned until a blank, comma, or character illegal for the E
or D edit descriptor is encountered.
d is an optional, nonzero, unsigned integer constant equal to
the total number of fractional digits in the field being
described (unless a scale factor greater than one is in
effect). The defaults for both the E and D edit descriptors
are 7 digits if single precision, and 18 if double
precision. The maximum is 63 digits.
e is an optional, nonzero, unsigned, integer constant equal to
the total number of digits in the E or D field being
described. The default for both types of edit descriptors
is two digits. The maximum is 15 digits.
For KL model B systems, if the program is compiled with the
/GFLOATING switch (see Section 16.1.3 or 16.2.3), you may
want to specify three digits to accommodate the exponent
field of double-precision numbers.
G
Editing
12.4.11.4 G Editing - The G edit descriptor allows editing of
integer, real, double-precision, logical, complex, or character data.
With the exception of real, double-precision, and complex data, the
type of conversion performed by the G edit descriptor depends on the
type of the corresponding variable in the I/O list.
The form of the G edit descriptor is:
[r]G[w.d[Ee]]
where:
12-40
FORMATTED DATA TRANSFERS
r is an optional, nonzero, unsigned, integer constant that is
equal to the number of G fields being described. The
default is one.
w is an optional, nonzero, unsigned, integer constant equal to
the total number of digits in the G field being described.
The total for both types of fields is equal to:
1. The total number of digits on both sides of the decimal
point
2. The decimal point itself
3. The sign for the number (if included)
4. The exponent character (if included)
5. The digits in the exponent
If w is not specified, for output, the value for single
precision is 15 (the default), and the value for double
precision is 25 (the default). For input, the data is
scanned until a blank, comma, or character illegal for the G
edit descriptor is encountered.
d is an optional, nonzero, unsigned integer constant equal to
the total number of fractional digits in the field being
described (unless a scale factor greater than one is in
effect). The defaults are 7 digits if single precision, and
18 if double precision. The maximum is 63 digits.
e is an optional, nonzero, unsigned, integer constant equal to
the total number of digits in the G field being described.
The default is two digits. The maximum is 15 digits.
For KL model B systems, if the program is compiled with the
/GFLOATING switch (see Section 16.1.3 or 16.2.3), you may
want to specify three digits to accommodate the exponent
field of double-precision numbers.
For input, in the case of real, double-precision, and complex data,
the G-format conversion is the same as for E-format conversion. For
output, however, the type of conversion performed depends on the
magnitude of the data items. Table 12-6 illustrates the conversion
performed for various ranges of real, double-precision, and complex
data.
Table 12-6: Effect of Data Magnitude on G-Format Output Conversion
12-41
FORMATTED DATA TRANSFERS
where:
x is a blank.
n is 4 for Gw.d and e+2 for Gw.dEe
NOTE
In all numeric field conversions, the field width (w)
you specify should be large enough to include the
decimal point, sign, and, where applicable, the
exponent character (E), the exponent sign, plus the
exponent digits. This is in addition to the number of
digits in the number to be represented.
If the specified width is too small to accommodate the
converted number, the field will be filled with
asterisks (*). If the number converted occupies fewer
character positions than specified by w, it will be
right-justified in the field, and leading blanks will
be used to fill the field.
If the numeric data representation cannot fit into the
field width F(w-n), the n spaces (n(x)) are removed
from the right, and the numeric data representation is
again processed into the field width Fw.
Examples of G output conversions (where the b signifies a blank) are:
Format Internal Value External Representation
G13.6 0.01234567 b0.123457E-01
G13.6 -1.12345678 -0.123457bbbb
G13.6 1.23456789 bb1.23457bbbb
G13.6 12.34567890 bb12.3457bbbb
G13.6 123.45678901 bb123.457bbbb
G13.6 -1234.56789012 b-1234.57bbbb
12-42
FORMATTED DATA TRANSFERS
G13.6 12345.67890123 bb12345.7bbbb
G13.6 123456.78901234 bb123457.bbbb
G13.6 -1234567.89012345 -0.123457E+07
For comparison, consider the following example of the same values
output under the control of an equivalent F field descriptor.
Format Internal Value External Representation
F13.6 0.01234567 bbbbb0.012346
F13.6 -0.12345678 bbbb-0.123457
F13.6 1.23456789 bbbbb1.234568
F13.6 12.34567890 bbbb12.345679
F13.6 123.45678901 bbb123.456789
F13.6 -1234.56789012 b-1234.567890
F13.6 12345.67890123 b12345.678901
F13.6 123456.78901234 123456.789012
F13.6 -1234567.89012345 *************
Complex
Editing
12.4.11.5 Complex Editing - A complex number consists of a pair of
separate real numbers. The first number of the pair is the real part
of the complex number; the second number is the imaginary part.
The editing of a complex number involves specifying two successive F,
E, D, or G edit descriptors. The edit descriptors need not be the
same.
A sample format list description for a complex number is:
101 FORMAT (F10.2,E10.2)
In this sample, the F10.2 edit descriptor provides editing for the
real part of the complex number; the E10.2 edit descriptor provides
editing for the imaginary part.
You may include any nonrepeatable edit descriptors between the real
and imaginary edit descriptors for a complex number.
12-43
FORMATTED DATA TRANSFERS
O (Octal)
Editing
12.4.11.6 O (Octal) Editing - The O (octal) edit descriptor specifies
octal editing.
The form of the O edit descriptor is:
[r]O[w[.m]]
where:
r is an optional, nonzero, unsigned, integer constant
specifying the number of successive octal fields being
described. The default is one octal field.
w is an optional, nonzero, unsigned, integer constant
specifying the total number of digits in the octal field
being described.
If w is not specified, for output, the value for a
single-precision octal field is 15 (the default), and the
value for a double-precision octal field is 25 (the
default). For input, the data is scanned until a blank,
comma, or character illegal for the O edit descriptor is
encountered.
m is an optional, unsigned, integer constant specifying the
minimum number of digits to be output to the field. The
defaults are 12 for single-precision octal values and 24 for
double-precision octal values.
Z (Hexadecimal)
Editing
12.4.11.7 Z Editing - The Z edit descriptor specifies input and
output of hexadecimal values. Hexadecimal is a base 16 number system
where the characters 0-9 and A-F (or a-f) represent the numbers 0-9
and 10-15, respectively. (On output, A-F only.)
12-44
FORMATTED DATA TRANSFERS
The form of the Z edit descriptor is:
[r]Z[w[.m]]
where:
r is an optional, unsigned, nonzero, integer constant
specifying the number of consecutive hexadecimal fields
being specified. The default is one hexadecimal field.
w is an optional, unsigned, nonzero, integer constant
specifying the total number of digits in the hexadecimal
field being described.
If w is not specified, for output, the value for a
single-precision hexadecimal field is 15 (the default), and
the value for a double-precision hexadecimal field is 25
(the default). For input, the data is scanned until a
blank, comma, or character illegal for the Z edit descriptor
is encountered.
m is an optional, unsigned, integer constant specifying the
minimum number of digits to be output in the field. The
default for single-precision hexadecimal fields is 9 digits;
the default for double-precision fields is 18 digits.
L
Editing
12.4.12 L Editing
The L edit descriptor provides editing of logical data.
The form of the L edit descriptor is:
[r]L[w]
where:
r is an optional, unsigned, nonzero, integer constant
specifying the number of consecutive logical fields being
described. The default is one logical field.
w is an optional, unsigned, nonzero, integer constant
specifying the total number of characters in the logical
field being described.
12-45
FORMATTED DATA TRANSFERS
If w is not specified, for output, the value is 15 (the
default) For input, the data is scanned until a blank,
comma, or character illegal for the L edit descriptor is
encountered.
You may transfer logical data under format control in a manner similar
to numeric data transfer by use of the field descriptor
Lw
where:
L is the control character and w is an integer specifying the
field width. The data is transmitted as the value of a
corresponding logical variable in the associated I/O list.
The input field consists of optional blanks, optionally followed by a
period, followed by a T for true or F for false, optionally followed
by any series of characters (such as, .TRUE. for true or .FALSE. for
false). If the entire input data field is blank or empty, a value of
false is stored.
On output, w minus 1 blanks followed by T or F will be output if the
value of the logical variable is true or false, respectively.
A
Editing
12.4.13 A Editing
The A edit descriptor specifies the editing of character or Hollerith
data. The data are stored left-justified in a word and padded with
blanks to the right.
NOTE
The R edit descriptor performs the same function for
Hollerith data, only it stores the data
right-justified in a word with leading nulls. The R
edit descriptor is not supported for character data.
For a description of the R edit descriptor, see
Section 12.4.14.
The form of the A edit descriptor is:
12-46
FORMATTED DATA TRANSFERS
[r]A[w]
where:
r is an optional, unsigned, integer constant specifying the
number of consecutive A fields being defined. The default
is one A field.
w is an optional, unsigned, integer constant specifying the
total number of characters in the field being defined. The
default for single-precision values is 5 characters; the
default for double-precision and complex values is 10
characters.
Depending on the I/O operation, the A edit descriptor transfers
character or Hollerith data into or from a variable in an I/O list. A
list variable may be of any type. For example,
READ (6,5) V
5 FORMAT (A4)
causes four character or Hollerith characters to be read from unit 6
and stored in the variable V.
The A descriptor deals with variables containing left-justified,
blank-filled characters. The following list summarizes the result of
character or Hollerith data transfer (both internal and external
representations) using the A descriptor. These explanations assume
that w represents the field width and m represents the total number of
characters possible in the variable. Double-precision and complex
variables contain 10 characters (m=10); integer, real, and logical
variables contain 5 (m=5).
A Descriptor
1. INPUT, where w > m -- The rightmost m characters of the field
are read in and stored in the corresponding variable.
2. INPUT, where w < m -- All w characters are read in and stored
left-justified and blank-filled in the corresponding
variable.
3. OUTPUT, where w > m -- m characters are output and
right-justified in the field. The remainder of the field is
blank-filled.
4. OUTPUT, where w < m -- The leftmost w characters of the
corresponding variable are output.
12-47
FORMATTED DATA TRANSFERS
R
Editing
12.4.14 R Editing
The R edit descriptor specifies the editing of Hollerith data. The
Hollerith data are stored right-justified with leading nulls. The R
edit descriptor is not supported for character data.
NOTE
The A edit descriptor, described in Section 12.4.13,
performs the same function as the R descriptor except
that it left-justifies the data in storage with
trailing spaces.
The form of the R edit descriptor is:
[r]R[w]
where:
r is an optional, unsigned, nonzero, integer constant
specifying the number of consecutive R fields being defined.
The default is one R field.
w is an optional, unsigned, nonzero, integer constant that
specifies the total number of characters in the R field.
If w is not specified, for output, the value for a
single-precision field is 5 (the default), and the value for
a double-precision or complex field is 10. For input, the
data is scanned until a blank, comma, or character illegal
for the R edit descriptor is encountered.
The R descriptor deals with variables containing right-justified,
zero-filled characters. The following list summarizes the result of
Hollerith data transfer (both internal and external representations)
using the R descriptor. These explanations assume that w represents
the field width and m represents the total number of characters
possible in the variable. Double-precision and complex variables
contain 10 characters (m=10); integer, real, and logical variables
contain 5 (m=5).
NOTE
When more than five characters are stored, bit zero of
the low-order word is skipped. Thus, a
12-48
FORMATTED DATA TRANSFERS
double-precision or complex variable filled by an
R-format data transfer is of the form:
0 data 0 data
R Descriptor
1. INPUT, where w > m -- The rightmost m characters of the field
are read in and stored in the corresponding variable.
2. INPUT, where w < m -- All w characters are read in and stored
right-justified and zero-filled in the corresponding
variable.
3. OUTPUT, where w > m -- m characters are output and
right-justified in the field. The remainder of the field is
zero-filled.
4. OUTPUT, where w < m -- The rightmost w characters of the
corresponding variable are output.
List-Directed
Formatting
12.5 LIST-DIRECTED FORMATTING
The use of an asterisk in a data transfer statement in place of a
FORMAT statement label specifies list-directed formatting. For this
type of formatting, the type of each transferred data item is
specified by the types of respective elements in the I/O list.
List-directed input data transfers are performed without regard for
column, card, or line boundaries. List-directed output transfers
produce records with a maximum length of 72 characters (the default)
or the length specified by the RECL specifier (see Section 11.3.27 for
devices other than the terminal). Otherwise, the maximum length of
the current terminal width is used.
The following is a sample list-directed data transfer statement:
READ (5,*)I,IAB,M,L
You may use list-directed transfers to read data from any acceptable
input device, including a terminal. However, do not use
device-positioning commands in conjunction with list-directed data
12-49
FORMATTED DATA TRANSFERS
transfers. If you do, the results are unpredictable.
Data for list-directed transfers should consist of alternate constants
and delimiters. The constants used should have the following
characteristics:
1. Input constants must be of a form acceptable to FORTRAN.
2. Character constants must be enclosed within single quotes,
for example, 'ABLE'. Each apostrophe in a character constant
must be represented by two apostrophes.
3. The end of a record is equivalent to a blank except when it
occurs in a character constant. In this case, the end of the
record is ignored and the character constant is continued
with the next record. The first character of the continued
record must be blank, which is ignored.
4. If the string of a character constant exceeds the length of
the data item, the string is truncated. If the string is
shorter than the data item, the string is left-justified and
remaining character positions are blank filled.
5. Blanks are used as delimiters in list-directed input.
Embedded blanks are, therefore, not permitted in any
list-directed data item, with the exception of character
constants.
6. Decimal points may be omitted from real constants that do not
have a fractional part. In this case, it is assumed that the
decimal point follows the rightmost digit of a real constant.
7. Complex constants must be enclosed within parentheses.
8. Octal constants must be preceded with a double quote (").
9. A numeric data item can correspond only to a numeric
constant, and a character data item can correspond only to a
character constant.
A delimiter in a list-directed list of data items separates one data
item from another. Delimiters in data for list-directed input must
comply with the following:
1. Delimiters may be commas, blanks, or slashes.
2. Delimiters may be either preceded by or followed by any
number of blanks, carriage return/line feed characters, tabs,
or line terminators; any such combination is treated as a
single delimiter.
12-50
FORMATTED DATA TRANSFERS
3. A null item (the complete absence of a data item) is
represented by two consecutive commas that have no
intervening constant(s). You may place any number of blanks,
tabs, or carriage return/line feed characters between the
commas of a null item. Each time you specify a null item in
the input data, its corresponding list element is skipped
(unchanged).
The following illustrates the effect of the input of a null
item:
I/O List A,B,IAB,N
Data input 101,'A',,20
Resulting contents of I/O list items:
A 101.
B 'A'
IAB unchanged
N 20
4. Slashes (/) cause the current input operation to terminate
even if all the items of the I/O list are not filled. The
contents of items of the I/O list that either are skipped (by
null items) or have not received an input data item before
the transfer is terminated remain unchanged. Once the I/O
list of the data transfer statement is satisfied, the use of
the / delimiter is optional.
5. Once the I/O list has been satisfied (values have been
transferred to each item of the list), any items remaining in
the input record are skipped.
Constants or null items in data for list-directed input may be
assigned a repeat count so that an item is repeated.
A constant with a repeat count is written as:
r*K
where:
r is an integer constant that specifies the number of
times the constant is repeated, the asterisk delimits
the repeat count from the constant, and K represents
the constant.
A null item with a repeat count is written as an integer, which
specifies the repeat count, followed by an asterisk.
12-51
FORMATTED DATA TRANSFERS
The following are examples of constants and null items:
10*5 represents 5,5,5,5,5,5,5,5,5,5
3*'ABLE' represents 'ABLE','ABLE','ABLE'
3* represents null,null,null
NOTE
The asterisk form representing nulls must be delimited
by a comma or slash; in this case spaces are ignored
and not treated as delimiters.
NAMELIST-Statement
Formatting
12.6 NAMELIST-STATEMENT FORMATTING
The data transfer statements described in Chapter 10 usually include
an I/O list, which is a list of variable, array, or array element
names that identify the names of the data being transferred.
An alternative way of creating I/O lists is to use the NAMELIST
statement. Using this method, you can specify the I/O list in a
NAMELIST statement and then reference the list by name in the
appropriate data transfer statement.
When you use NAMELIST-statement formatting, as opposed to
FORMAT-statement or list-directed formatting, you need only reference
an I/O list by NAMELIST name in a data transfer statement.
NAMELIST
Statement
12.7 NAMELIST STATEMENT
The form of the NAMELIST statement is:
12-52
FORMATTED DATA TRANSFERS
NAMELIST /name/list[/name/list]...
where:
name is the name of the NAMELIST I/O list. This is the name
referenced in data transfer statements. Each NAMELIST
name must be enclosed in slashes.
list is the list of items comprising the NAMELIST I/O list.
Items within the list may be variable names or array
names. Separate multiple list items with commas.
Each list of a NAMELIST statement is identified and
referenced by the name immediately preceding the list.
The following is an example of creating two NAMELIST I/O lists having
the names TABLE and SUMS.
DIMENSION C(2,4),TOTAL(10)
NAMELIST/TABLE/A,B,C/SUMS/TOTAL
In this example, the name TABLE identifies the list consisting of the
scalars A and B and the array C, and the name SUMS identifies the list
consisting of the array TOTAL.
Once a list has been defined in a NAMELIST statement, one or more I/O
statements may reference its name.
The rules for structuring a NAMELIST statement are:
1. You may use a maximum of six characters for a NAMELIST name.
2. You must begin the list name with an alphabetic character.
3. You must enclose the NAMELIST name in slashes.
4. You should use NAMELIST names that are unique within the
program.
5. You may define a NAMELIST name only once, and you must define
it by a NAMELIST statement. Once defined, you may use the
name only in I/O transfer statements.
6. You must define the NAMELIST name before the data transfer
statements in which it is used.
7. You must define any dimensioned variable contained in a
NAMELIST statement in an array declaration statement
preceding the NAMELIST statement.
12-53
FORMATTED DATA TRANSFERS
12.7.1 NAMELIST-Controlled Data Input Transfer
During data input transfers in which a NAMELIST-defined name is
referenced, records are read until a record is found that begins with
a blank, then $ (dollar sign), and then the desired NAMELIST name.
The dollar sign must be the second character in the record; the first
character in the record must be a blank.
NOTE
You may use "&" instead of "$" in NAMELIST-controlled
input.
Data items of records to be input (read) using NAMELIST-defined lists
must be separated by commas and may be of the following form:
V=K1,K2,...,Kn
where:
V may be a variable, array, or array element name.
K1,...,Kn are constants. A series of identical constants
may be represented as a single constant preceded
by a repetition count (5*5 represents 5,5,5,5,5).
You can specify more than one constant only if V
is an array. If V is a scalar, then you may have
only K1.
The input data is always converted to the type of the list variable
when there is a conflict of types. A character constant is truncated
from the right, or extended on the right with blanks, if necessary, to
yield a constant of the same length as the variable, array, or
substring.
The input operation continues until another $ symbol is detected. If
variables appear in the NAMELIST record that do not appear in the
NAMELIST list, an error condition will occur.
A character constant must have delimiting apostrophes. If an
apostrophe is part of a character constant, it must be represented by
two consecutive apostrophes, which must be contained in the same
record (one apostrophe cannot end a record, and the other apostrophe
start a record).
For example, assume:
1. A is a 2-dimensional real array
2. B is a 1-dimensional integer array
12-54
FORMATTED DATA TRANSFERS
3. C is an integer variable
4. D is a character variable of length 5.
5. The program contains the NAMELIST declaration:
NAMELIST /FRED/ A,B,C,D
6. The input data is as follows:
b$FRED A(7,2)=4, B=3,6*2.8, C=3.32, D='RON'$
A READ statement referring to the NAMELIST-defined name FRED will
result in the following:
1. The integer 4 will be converted to floating point and placed
in A(7,2).
2. The integer 3 will be placed in B(1).
3. The integer 2 (after being truncated) will be placed in
B(2),B(3),...,B(7).
4. The floating point number 3.32 will be converted to the
integer 3 and placed in C.
5. The character string 'RONbb' will be placed in D.
12.7.2 NAMELIST-Controlled Data Output Transfers
When a WRITE statement refers to a NAMELIST-defined name, all
variables and arrays and their values belonging to the named list are
written out, each according to its type. Character constants are
written with delimiting apostrophes. Arrays are written out by
columns. Output data is written so that:
1. The fields for the data will be large enough to contain all
the significant digits.
2. The output can be read by an input statement referencing a
NAMELIST-defined list.
For example, if ARRAY is a 2 X 3 real array, A1 is a real variable, K1
is an integer variable, and D is a character variable containing the
five characters AB'CD, the statements:
REAL ARRAY(2,3)
CHARACTER D*5
DATA ARRAY,A1,KI,D/-6.75, 0.234E-04, 680.0, -17.8,0.0,00,
1 73.1, 3, 'AB''CD'/
12-55
FORMATTED DATA TRANSFERS
NAMELIST/NAM1/ARRAY,A1,K1,D
WRITE (u,NAM1)
generate the following form of output:
Column 1
b$NAM1
ARRAY= -6.750000, 0.2340000E-04, 680.0000, -17.80000, 2*0.0000000,
A1= 73.10000, K1= 3, D='AB''CD'
$END
NOTE
Do not use device-positioning commands such as
BACKSPACE or SKIPRECORD with NAMELIST-controlled I/O
operations. If you do, the results are unpredictable.
12-56
CHAPTER 13
FUNCTIONS AND SUBROUTINES
Procedures you use repeatedly in a program can be written once and
then referenced each time you need the procedure. Procedures that may
be referenced are either contained within the program in which they
are referenced, or self-contained executable procedures that can be
compiled separately. The kinds of procedures that can be referenced
are:
1. Intrinsic functions (FORTRAN-defined functions)
2. Statement functions
3. External functions
4. Subroutines
The first three of these categories are referred to collectively as
functions or function procedures; procedures of the last category are
referred to as subroutines or subroutine procedures.
Intrinsic functions perform a predefined computation with a specific
number and type of arguments. These functions are provided by FORTRAN
(see Section 13.1).
Statement functions are user-defined, single statement procedures that
resemble assignment statements. The appearance of a statement
function reference in an expression causes the user-defined
computation to be performed (see Section 13.2).
External functions are separate program units that generally compute a
single value using one or more parameters. There are two types of
external functions available: user-defined and FORTRAN-supplied. A
user-defined external function is defined with a FUNCTION statement.
Both types of external functions are invoked by including a function
reference in an expression (see Section 13.3).
Subroutines are external program units that are used to perform
multiple computations or alter variables. There are two types of
13-1
FUNCTIONS AND SUBROUTINES
subroutines available: user-defined and FORTRAN-supplied.
User-defined subroutines are defined with a SUBROUTINE statement (see
Section 13.4.2.1). Both types of subroutines are invoked with a CALL
statement (see Section 13.4.2.2).
13.1 INTRINSIC FUNCTIONS
Intrinsic functions are supplied with the FORTRAN software. Each
intrinsic function performs a predefined computation. There are two
types of intrinsic functions: specific and generic.
Specific functions have an implicitly defined data type. Each
specific function requires arguments of a particular type and returns
results of a predefined type. The IMPLICIT statement cannot be used
to change the type of a specific intrinsic function.
The data type of the return value of a generic function is determined
by the data type of its arguments. The FORTRAN generic functions are:
ABS DIM
ACOS EXP
AINT INT
ALOG LOG
ALOG10 LOG10
AMAX1 MAX
AMIN1 MIN
ANINT MOD
ASIN NINT
ATAN REAL
ATAN2 SIGN
CMPLX SIN
COS SINH
COSH SQRT
DBLE TAN
TANH
NOTE
Table 13-1 lists all the specific and generic
intrinsic functions. For ease of identification, each
generic function name in the table is indicated by an
asterisk.
13.1.1 Using an Intrinsic Function
An intrinsic function is used in a FORTRAN expression by referencing
the name of the function in an expression. For example, the following
program contains two intrinsic functions: ABS (returns the absolute
13-2
FUNCTIONS AND SUBROUTINES
value of the argument) and SQRT (returns the square root of the
argument).
PROGRAM TEST
Y = -64
A = ABS (Y)
TYPE ,A
B = SQRT (A)
TYPE ,B
END
When the preceding program is executed, variable Y is assigned the
value -64. The ABS function in the second expression calculates the
absolute value of -64. Next, in the third expression, the SQRT
function calculates the square root of the absolute value of Y, which
is A. The square root of A is assigned to B in the third expression.
Executing the program yields the following results:
EXECUTE TEST.FOR
FORTRAN: TEST
TEST
LINK: Loading
[LNKXCT TEST execution]
64.00000
8.000000
CPU time 0.1 Elapsed time 4.0
The following example contains specific and generic functions. In the
example, the generic function SQRT is used to find the square root of
the double-precision value 64.0. Next, the specific function DSQRT is
used to find the square root of the double-precision value 64.0. If
the argument supplied to DSQRT was not a double-precision number, a
fatal compilation error would result.
PROGRAM TESFUN
DOUBLE PRECISION A,B,AR,BR
REAL C,CR
A = 64.00D0
B = 64.00D0
C = 64.00
C GENERIC SQRT RETURNS DP
C SQRT BECAUSE ARG TYPE IS DP
AR = SQRT(A)
C SPECIFIC DSQRT PERFORMS THE
13-3
FUNCTIONS AND SUBROUTINES
C SAME FUNCTION WHEN GIVEN A DP
C ARGUMENT
BR = DSQRT(A)
C SPECIFIC SQRT RETURNS A REAL
C VALUE RESULT
CR = SQRT(C)
TYPE , AR,BR,CR
END
Executing the program above yields the following results:
EXE TESFUN
LINK: Loading
[LNKXCT TESFUN Execution]
8.0000000000000000, 8.0000000000000000, 8.000000
CPU time 0.1 Elapsed time 0.7
Table 13-1 lists the FORTRAN intrinsic functions. This table gives
function definitions, argument and function types, and ranges of
acceptable values. Each function contains a description of the range
for valid arguments(s) and the range within which the function returns
valid results. If function arguments do not fall within the specified
range, the result of the function is undefined.
For more information on the precision and accuracy of the FORTRAN
intrinsic functions, refer to the TOPS-10/TOPS-20 Common Math Library
Manual.
13-4
FUNCTIONS AND SUBROUTINES
Table 13-1: FORTRAN Instrinsic Functions
13-5
FUNCTIONS AND SUBROUTINES
13-6
FUNCTIONS AND SUBROUTINES
13-7
FUNCTIONS AND SUBROUTINES
13-8
FUNCTIONS AND SUBROUTINES
13-9
FUNCTIONS AND SUBROUTINES
13-10
FUNCTIONS AND SUBROUTINES
13-11
FUNCTIONS AND SUBROUTINES
13.1.2 Character Intrinsic Functions
Character intrinsic functions are functions that take character
arguments or return character values. Character comparison intrinsic
functions are functions that take character arguments and return
logical values.
FORTRAN provides four character intrinsic functions:
1. LEN
The LEN function returns the length of a character
13-12
FUNCTIONS AND SUBROUTINES
expression. The LEN function has the following form:
LEN(arg)
where:
arg is a character expression. The value returned
indicates how many characters there are in the
expression.
The following example illustrates the LEN function:
C This subroutine reverses an entire character
C string.
SUBROUTINE REVERS(S)
CHARACTER T, S*(*)
J = LEN(S)
DO 10 I=1,J/2
T = S(I:I)
S(I:I) = S(J:J)
S(J:J) = T
J = J - 1
10 CONTINUE
RETURN
END
2. INDEX
The INDEX function searches for a substring (arg2) in a
specified character string (arg1), and, if it finds the
substring, returns the substring's starting position. If
arg2 occurs more than once in arg1, the starting position of
the first (leftmost) occurrence is returned. If arg2 does
not occur in arg1, the value zero is returned. The INDEX
function has the following form:
INDEX(arg1,arg2)
where:
arg1 is a character expression specifying the string
to be searched for the substring specified by
arg2.
arg2 is a character expression specifying the
substring that is searched for.
The following example illustrates the INDEX function:
13-13
FUNCTIONS AND SUBROUTINES
C This subroutine places the symbol # into the
C variable MARKS at places corresponding to the
C beginning of all occurrences of the substring
C SUB within the string S.
SUBROUTINE FINSTR(SUB,S)
CHARACTER*(*) SUB, S
CHARACTER*132 MARKS
INTEGER I,J
I = 1
MARKS = ' '
10 J = INDEX(S(I:), SUB)
IF (J .NE. 0) THEN
I = 1 + J
MARKS(I-1:I-1) = '#'
IF (I .LE. LEN(S)) GO TO 10
END IF
WRITE (5,91) S, MARKS
91 FORMAT (2(/1X,A))
END
3. ICHAR
The ICHAR function converts a character expression to its
equivalent ASCII code and returns the ASCII value. The
ICHAR function has the following form:
ICHAR(arg)
where:
arg is the character to be converted to an ASCII
code. If arg is longer than one character, only
the value of the first character is returned;
the remaining characters are ignored.
4. CHAR
The CHAR function returns the single character whose ASCII
code is the integer or octal argument. The CHAR function
has the following form:
CHAR(arg)
where:
arg is an integer expression.
The following example illustrates the CHAR and ICHAR functions:
13-14
FUNCTIONS AND SUBROUTINES
CHARACTER C*1
INTEGER I
C Convert number between 0 and 9 in I to a character
C digit
C = CHAR(I+ICHAR('0'))
END
13.1.3 Character Comparison Functions
The four character comparison functions provided with FORTRAN are:
LLT, where LLT(arg1,arg2) is equivalent to (arg1.LT.arg2)
LLE, where LLE(arg1,arg2) is equivalent to (arg1.LE.arg2)
LGT, where LGT(arg1,arg2) is equivalent to (arg1.GT.arg2)
LGE, where LGE(arg1,arg2) is equivalent to (arg1.GE.arg2)
The comparison functions have the following form:
func(arg1,arg2)
where:
arg is a character expression.
The character comparison functions defined by the FORTRAN-77 standard
are guaranteed to make comparisons according to the ASCII collating
sequence, even on non-ASCII processors. On TOPS-10/20 systems, the
character comparison functions are identical to the corresponding
character relationals.
An example of the use of a character comparison function follows:
CHARACTER*10 CH2
IF (LGT(CH2,'SMITH')) STOP
The IF statement in this example is equivalent to:
IF (CH2.GT.'SMITH') STOP
13-15
FUNCTIONS AND SUBROUTINES
13.1.4 Bit Manipulation Functions
Intrinsic bit manipulation functions are used for manipulation of the
bits in the binary patterns that represent integers. Integer data
types are represented internally in binary two's complement notation.
Bit positions in the binary representation are numbered from right
(least significant bit) to left (most significant bit); the rightmost
bit position is numbered 0, and the leftmost bit position is numbered
35. A bit in a binary pattern has a value of 0 or 1.
The intrinsic functions IAND, IOR, IEOR, and NOT perform bitwise
operations on all the bits of their arguments. Bit 0 of the result is
the result of applying the specified logical operation to bit 0 of the
arguments. Bit 1 of the result is the result of applying the
specified logical operation to bit 1 of the arguments, and so on for
all the bits of the result.
The shift functions ISHFT and ISHFTC shift binary patterns. A
positive shift count indicates a left shift, while a negative shift
count indicates a right shift. A shift count of zero means no shift.
ISHFT specifies a logical shift; bits shifted out of one end are lost
and zeros are shifted in at the other end. ISHFTC performs a circular
shift; bits shifted out at one end are shifted back in at the other
end.
The function IBITS and the subroutine MVBITS (see Section 13.4.1.21)
operate on bit fields. A bit field is a contiguous group of bits
within a binary pattern. Bit fields are specified by a starting bit
position and a length. A bit field must be entirely contained in its
source operand.
For example, the integer 79 is represented by the following binary
pattern:
0...0101111
n...6543210 (bit position)
where:
n is 35 (the number of bit positions in an integer).
You can refer to the bit field contained in bits 3 through 6 by
specifying a starting position of 3 and a length of 4. In the above
example, the selected bit pattern would be the following:
0...000101
Negative integers are represented in two's complement notation. The
integer -79 is represented by the following binary pattern:
1...1010001
13-16
FUNCTIONS AND SUBROUTINES
n...6543210 (bit position)
where:
n is 35 (the number of bit positions in an integer).
NOTE
The value of bit position 35 is 1 for a negative
number and 0 for a non-negative. Also, all the
high-order bits of the pattern to the left of the
value up to bit 35 are the same as bit 35.
IBITS and MVBITS operate on bit fields. Both the starting position of
a bit field and its length are arguments to these intrinsics. IBSET,
IBCLR, and BTEST operate only on one bit. Thus, they do not require a
length argument.
13.2 STATEMENT FUNCTIONS
A statement function is a procedure specified by a single statement
that is similar in form to an arithmetic, character, or logical
assignment statement. The statement function enables you to define a
single-line computation once in your program, give it a name, and have
that calculation performed each time you reference the statement
function in the program. A statement function is classified as a
nonexecutable statement.
13.2.1 Defining a Statement Function
Statement functions have the following form:
fun ( [d [,d]...] ) = e
where:
fun is the symbolic name for the statement function. The
function name follows the rules for forming symbolic names
in FORTRAN (see Chapter 4).
d is an optional dummy argument. Separate multiple dummy
arguments with commas. (Dummy arguments are described in
Section 13.4.5.) The parentheses are still required if no
dummy arguments are specified.
e is any type of FORTRAN expression. The expression part of
the statement function (to the right of the equal sign)
13-17
FUNCTIONS AND SUBROUTINES
defines the computation performed using the dummy arguments.
The relationship between fun and e must conform to the assignment
rules in Sections 8.1, 8.2, and 8.4. Note that the type of the
expression may be different from the type of the statement function
name.
The following rules govern the formation and use of statement
functions:
1. The dummy argument list in the statement function serves only
to indicate the order, number, and type of arguments for the
statement function.
2. The dummy arguments used in a statement function are local to
that statement function. It is valid to use the same names
in multiple statement functions in the same program unit. A
dummy argument name may also be used elsewhere in the program
unit to identify a variable of the same type, including its
appearance as a dummy argument in a FUNCTION, SUBROUTINE, or
ENTRY statement.
3. Each dummy argument in a statement function dummy argument
list must be unique; the same dummy argument cannot appear
twice in a single list.
Each variable reference in the function can be either a reference to a
dummy argument of the statement function, or a reference to a variable
that appears within the same program unit as the statement function
statement.
If a statement function dummy argument name is the same as the name of
another entity, the appearance of that name in the expression of a
statement function statement is a reference to the statement function
dummy argument.
13.2.2 Using a Statement Function
Statement functions are used in FORTRAN programs by referencing the
name of the statement function in an expression that is in the same
program unit as the statement function definition. If a character
function is referenced in a program unit, the function length
specified in the program unit must be an integer constant expression.
For example, the following program uses a statement function (called
PROFIT) to determine the profit for a product. In the statement
function definition, PROFIT is defined as the difference between
wholesale and retail prices minus .05 sales tax.
PROGRAM STAFUN
13-18
FUNCTIONS AND SUBROUTINES
PROFIT (A,B) = ((A - B) - (A .05))
WRITE(UNIT=5,FMT=100)
100 FORMAT(1X,'Enter Wholesale Price and Retail Price')
ACCEPT ,WHOSAL,RETAIL
150 C = PROFIT(RETAIL,WHOSAL)
WRITE(UNIT=5,FMT=101) C
101 FORMAT(1X,'The Profit (minus sales tax) is: ',F8.2)
END
When the program is executed, the retail and wholesale values are
entered at the terminal. Next, the expression at statement number 150
uses the values of RETAIL and WHOSAL to calculate the profit as
defined in the PROFIT statement function. A sample execution of this
program yields the following results:
EXECUTE STATE
LINK: Loading
[LINKXCT STAFUN execution]
Enter Wholesale Price and Retail Price
31.67 45.95
The profit (minus sales tax) is: 11.98
CPU time 0.2 Elapsed time 18.5
When a FORTRAN expression that contains a statement function reference
is executed, the following happens:
1. The actual arguments contained in the statement function
reference are evaluated.
2. The actual arguments in the statement function are associated
with the dummy arguments in the statement function
definition.
3. The expression portion of the statement function is evaluated
using the actual arguments.
4. If necessary, the value of the expression is converted to the
type of the statement function. Finally, the value resulting
from the expression evaluation is substituted in the
expression containing the statement function reference.
13.2.3 Statement Function Restrictions
The following rules and restrictions must be adhered to when using
statement functions:
13-19
FUNCTIONS AND SUBROUTINES
1. The actual arguments in a function reference must agree in
type and number with the corresponding dummy arguments in the
statement function dummy argument list.
2. An actual argument in a statement function reference can
itself be an expression; all actual arguments must be defined
when a statement function reference is evaluated.
3. A statement function can only be referenced in the program
unit that contains the statement function statement.
4. A statement function must not contain a reference to another
statement function that appears later in the program unit,
but can contain a reference to another statement function
that appears earlier in the program.
5. The symbolic name used to identify a statement function must
not appear as a symbolic name in any specification statement
except a type statement (to specify the type of the function)
or as the name of a common block in the same program unit.
6. An external function reference (see Section 13.3) in the
expression part of a statement function statement must not
cause a dummy argument of the statement function to become
undefined or redefined.
7. The symbolic name of a statement function may not be an
actual argument. It must not appear in an EXTERNAL statement
(see Section 7.6).
8. A statement function statement in a function subprogram (see
Section 13.3.4.) must not contain a function reference to the
name of the function subprogram or an entry name in the
function subprogram.
9. An actual argument in a statement function reference can be
any expression, including a character expression involving
concatenation of an operand whose length specification is an
asterisk in parentheses.
10. The length specification of a character statement function
must be an integer constant expression.
13.3 EXTERNAL FUNCTIONS
An external function is a procedure that is defined externally to the
program unit that references it. FORTRAN offers two types of external
functions: FORTRAN-supplied and user-defined. The FORTRAN-supplied
external functions are described in Section 13.3.1; the user-defined
13-20
FUNCTIONS AND SUBROUTINES
functions are described in Sections 13.3.2 through 13.3.4.
13.3.1 FORTRAN-Supplied External Functions
FORTRAN-supplied external functions are similar to intrinsic
functions. To use a FORTRAN-supplied function, you reference its name
in an expression.
The following are the FORTRAN-supplied external functions:
x=DTOG(y) returns a G-floating double-precision number
in the range 1.47 x 10**-39 to 1.70 x
10**+38. The argument y is a D-floating
double-precision number. (Also, see the
DTOGA subroutine, Section 13.4.1.12.)
x=GTOD(y) returns a D-floating double-precision number
in the range 1.47 x 10**-39 to 1.70 x
10**+38. The argument y is a G-floating
double-precision number. (Also, see the
GTODA subroutine, Section 13.4.1.18.)
x=LSNGET(unit) returns the last line number read in a line
sequenced file. LSNGET returns a positive
integer if the last line has a valid line
number; returns zero if the last line is a
page mark; or returns -1 if the last line
number is invalid (such as, AAAA with bit 35
set). It also returns -1 if the file
contains no line number, or was opened with a
mode other than LINED (see Section 11.3.20).
x=RAN(0) returns a pseudo random floating-point number
in the range of 0.LT.x.LT.1. The argument is
a dummy (not used) and may be any number.
Refer to the related subroutines SETRAN (see
Section 13.4.1.27) and SAVRAN (see Section
13.4.1.26).
x=RANS(0) returns a pseudo random floating-point number
in the range of 0.LT.x.LT.1. RANS is a
prime-modulus random number generator with
shuffling capability. It calls RAN to
generate its initial table of random
deviates. Refer to related subroutins SETRAN
(see Section 12.4.1.27) and SAVRAN (see
Section 12.4.1.26).
y=SECNDS(x) returns the system time in seconds as a
single-precision, floating-point value, minus
13-21
FUNCTIONS AND SUBROUTINES
the value of its single-precision,
floating-point argument. The argument y is
set equal to the time in seconds since
midnight, minus the user-supplied value of x.
x=TIM2GO(0) returns the number of seconds remaining in
the job's run-time limit. The time limit is
set by the /TIME switch when submitting the
batch job. The argument is a dummy (not
used) and may be any number.
You may also specify a time limit for an
interactive job by using the SET TIME-LIMIT
command on TOPS-20, or the SET TIME command
on TOPS-10.
FORTRAN-supplied external functions are treated in the same manner as
user-defined functions. Implicit or explicit type declarations affect
these functions, and no argument checking (type or number) is
performed at compile time.
13.3.2 User-Defined External Functions
An external user-defined function is a procedure that is external to
the program unit that references it. The function subprogram enables
you to define a multiline function. By referencing the name of that
function in an expression, the lines of the function are automatically
executed.
The FUNCTION statement is always the first statement in a function
subprogram. The form of the FUNCTION statement is:
[type] FUNCTION fun ([arg1 [,arg2]...])
where:
type is an optional type specification for the external
function. This may be INTEGER, REAL, DOUBLE PRECISION,
COMPLEX, LOGICAL, or CHARACTER (plus the optional size
modifier *len).
For CHARACTER, len is the length specification of the
result of the character function. If you specify
CHARACTER*(*), the function assumes the length declared
for it in the program unit that invokes it. If len is
an integer constant, the value of len must agree with
the length of the function specified in the program
unit that invokes the function. If a length is not
specified in a CHARACTER FUNCTION statement, a length
of one is assumed.
13-22
FUNCTIONS AND SUBROUTINES
If you do not specify a type, the type of the function
subprogram name determines the data type of the
external function.
fun is the symbolic name of the external function
subprogram. Unless the optional data type is specified
in the FUNCTION statement, the type of the function
name determines the data type of the function
subprogram.
arg is an optional dummy argument. Arg may be a variable
name, array name, or dummy procedure name. Separate
multiple dummy arguments with commas. The parentheses
are optional if no dummy arguments are specified.
You must define the symbolic name assigned a function subprogram as a
variable name in the function. During each execution of the function,
this variable can be redefined. The value of the variable at the time
of execution of any RETURN statement is the value of the function.
NOTE
The RETURN statement returns control to the statement
that referenced the function subprogram (see Section
13.4.4). Additionally, you may desire to have a
function start executing at a statement other than the
first executable statement in the function subprogram.
The ENTRY statement (see Section 13.4.3) enables you
to define an alternate entry point in the function
subprogram.
13.3.3 Function Subprogram Restrictions
The following rules govern the structuring of a function subprogram:
1. You can not use the symbolic name of a function subprogram in
any nonexecutable statement in the subprogram except in the
initial FUNCTION statement or a type statement.
2. Dummy argument names cannot appear in any EQUIVALENCE,
COMMON, or DATA statement used within the subprogram.
3. The function subprogram can define or redefine one or more of
its arguments so as to return results in addition to the
value of the function.
4. The function subprogram can contain any FORTRAN statement
except BLOCK DATA, SUBROUTINE, PROGRAM, or another FUNCTION
statement.
13-23
FUNCTIONS AND SUBROUTINES
5. The function subprogram should contain at least one RETURN
statement and must be terminated by an END statement. The
RETURN statement signifies a logical conclusion of the
computation made by the subprogram, and returns the computed
function value and control to the calling program. A
subprogram can have more than one RETURN statement.
The END statement specifies the physical end of the
subprogram and implies a return.
6. If the type of a function is specified in a FUNCTION
statement, the function name must not appear in a type
statement. Note that a name must not have its type
explicitly specified more than once in a program unit.
7. A function specified in a subprogram may be referenced within
any other procedure subprogram or the main program of the
executable program. A function subprogram must not reference
itself, either directly or indirectly.
8. If the name of a function subprogram is of type character,
each entry name in the function subprogram must be of type
character. If the name of the function subprogram or any
entry in the subprogram has a length of (*) declared, all
such items must have a length of (*) declared; otherwise, all
such items must have a length specification of the same
integer value.
13.3.4 Using a Function Subprogram
After defining a function subprogram, you use it by referencing the
name of the function subprogram in an expression. Function
subprograms are referenced in expressions using the following form:
fun ([arg1,arg2,...argn])
where:
fun is the function subprogram name. This is the same name
that appears in the corresponding FUNCTION statement.
The length of the character function in a character
function reference must be the same as the length of
the character function in the referenced function.
arg is an optional list of actual arguments. These
arguments must agree in type and number with the dummy
argument list of the corresponding FUNCTION statement.
If the actual and dummy arguments do not agree, no type
conversion is done; and the results are unpredictable.
The parentheses are required even if no actual
13-24
FUNCTIONS AND SUBROUTINES
arguments are specified.
When an expression that contains a function subprogram reference is
executed, the following happens:
1. Evaluation of actual arguments that are expressions
2. Association of actual arguments with the corresponding dummy
arguments
3. Execution of the referenced function subprogram
Section 13.3.3 describes all the restrictions that must be adhered to
when using function subprograms.
13.4 SUBROUTINES
A subroutine subprogram is a procedure that is external to the program
units that reference it. FORTRAN offers two types of subroutines:
user-defined and FORTRAN-supplied. FORTRAN-supplied subroutines are
described in Sections 13.4.1 - 13.4.1.32; user-defined subroutines are
described in Sections 13.4.2 through 13.4.2.4.
NOTE
The FORTRAN-supplied subroutines are described in this
manual in two sections. Section 13.4.1 describes the
general FORTRAN subroutines; Appendix F describes the
subroutines that enable you to use a plotter.
Program units reference subroutines with the CALL statement (see
Section 13.4.2.2). The subroutine reference in the CALL statement
contains the unique name of the subroutine, as defined in a SUBROUTINE
statement (see Section 13.4.2.1). The SUBROUTINE statement is always
the first statement in a subroutine.
When a CALL statement reference is made to a subroutine subprogram,
program execution transfers from that CALL statement to the referenced
subroutine subprogram.
By including the ENTRY statement (see Section 13.4.3) within the body
of a subroutine subprogram, you can enter the subroutine at a point
other than the first statement in the subroutine. In this case, the
CALL statement used to reference an entry point in a subroutine
contains a reference to an entry point name, as opposed to the
subroutine name.
Return of program control from the subroutine to the calling program
unit occurs when the RETURN statement is executed (see Section
13.4.4). The RETURN statement is always the last statement executed
13-25
FUNCTIONS AND SUBROUTINES
in a subroutine subprogram.
Table 13-2: FORTRAN-Supplied Subroutines
13-26
FUNCTIONS AND SUBROUTINES
13.4.1 FORTRAN-Supplied Subroutines
The FORTRAN software includes a set of predefined subroutines. This
section describes the general FORTRAN subroutines (and a function that
is similar) in alphabetical order. (See Appendix F for the
FORTRAN-supplied plotter subroutines.)
NOTE
Sections 13.4.1.2 through 13.4.1.7 describe
subroutines (and a function) that are used for
calculations on double-precision complex numbers. You
must supply your own subroutines for performing
addition, subtraction, multiplication, and division of
double-precision complex numbers.
In addition, FORTRAN does not support the
double-precision complex data type (called
COMPLEX*16). These numbers are kept as arrays and
cannot be used in expressions or as the arguments of
generic routines.
13-27
FUNCTIONS AND SUBROUTINES
ALCCHR
Subroutine
13.4.1.1 ALCCHR Subroutine - The ALCCHR subroutine allocates space
for dynamic character concatenation operations. You do not normally
need to allocate space for this purpose unless you are doing very
large character concatenation operations.
The form of the ALCCHR subroutine is:
CALL ALCCHR(size)
where:
size is the integer size in characters for either creating
or expanding the character stack.
CDABS
Function
13.4.1.2 CDABS Function - The CDABS function returns the
double-precision absolute value of the specified double-precision
complex number. (Although CDABS is a function and is not a
subroutine, it is included here because it is similar to some
subroutines.)
The form of the CDABS function is:
dpres = CDABS(dparg)
where:
dparg is a 2-element double-precision array containing the
complex value whose absolute value you want calculated.
The first element of dparg contains the real part of
the double-precision complex number; the second element
contains the imaginary part.
dpres is a double-precision variable that is set to the
absolute value of the complex number.
13-28
FUNCTIONS AND SUBROUTINES
CDCOS
Subroutine
13.4.1.3 CDCOS Subroutine - The CDCOS subroutine finds the complex
cosine of the specified double-precision complex number.
The form of the CDCOS subroutine is:
CALL CDCOS(dparg,dpres)
where:
dparg is a 2-element double-precision array containing the
complex value whose cosine you want calculated. The
first element of dparg contains the real part of the
double-precision complex number; the second element
contains the imaginary part.
dpres is a 2-element double-precision array in which the
subroutine returns the result of the calculation. The
first element of dpres contains the real part of the
double-precision complex number; the second element
contains the imaginary part.
Example:
DOUBLE PRECISION dparg(2),dpres(2)
dparg(1) = 1D0 !arg is (1,-1)
dparg(2) = -1D0
CALL CDCOS(dparg,dpres)
CDEXP
Subroutine
13.4.1.4 CDEXP Subroutine - The CDEXP subroutine finds the complex
exponential of the specified double-precision complex number.
The form of the CDEXP subroutine is:
CALL CDEXP(dparg,dpres)
13-29
FUNCTIONS AND SUBROUTINES
where:
dparg is a 2-element double-precision array that contains the
complex argument to the subroutine. The first element
of dparg contains the real part of the double-precision
complex number; the second element contains the
imaginary part.
dpres is a 2-element double-precision array that stores the
result of the calculation. The first element of dpres
stores the real part of the result; the second element
stores the imaginary part.
Example:
DOUBLE PRECISION dparg(2),dpres(2)
dparg(1) = 0D0
dparg(2) = 1D0 !arg is (0,1)
CALL CDEXP(dparg,dpres)
CDLOG
Subroutine
13.4.1.5 CDLOG Subroutine - The CDLOG subroutine returns the complex
logarithm of a specified double-precision complex number.
The form of the CDLOG subroutine is:
CALL CDLOG(dparg,dpres)
where:
dparg is a 2-element double-precision array that contains the
double-precision complex number whose logarithm you
want calculated. The first element of dparg contains
the real part of the complex number; the second element
contains the imaginary part.
dpres is a 2-element double-precision array that stores the
result returned by CDLOG. The first element of dpres
contains the real part of the double-precision complex
number; the second element contains the imaginary part.
Example:
DOUBLE PRECISION dparg(2),dpres(2)
dparg(1) = 1D0 !arg is (1,0)
13-30
FUNCTIONS AND SUBROUTINES
dparg(2) = 0D0
CALL CDLOG(dparg,dpres)
CDSIN
Subroutine
13.4.1.6 CDSIN Subroutine - The CDSIN subroutine returns the complex
sine of the double-precision complex number specified.
The form of the CDSIN subroutine is:
CALL CDSIN(dparg,dpres)
where:
dparg is a 2-element double-precision array that contains the
number whose sine you want calculated. The first
element of dparg contains the real part of the
double-precision complex number; the second element
contains the imaginary part.
dpres is a 2-element double-precision array in which the
result of the calculation is returned. The first
element of dpres contains the real part of the result;
the second element contains the imaginary part.
Example:
DOUBLE PRECISION dparg(2),dpres(2)
dparg(1) = -1D0 !arg is (-1,01)
dparg(2) = 1D0
CALL CDSIN(dparg,dpres)
CDSQRT
Subroutine
13.4.1.7 CDSQRT Subroutine - The CDSQRT subroutine returns the
complex square root of the specified double-precision complex number.
13-31
FUNCTIONS AND SUBROUTINES
The form of the CDSQRT subroutine is:
CALL CDSQRT(dparg,dpres)
where:
dparg is a 2-element double-precision array that contains the
double-precision complex number whose square root you
want calculated. The first element of dparg contains
the real part of the double-precision complex number;
the second element contains the imaginary part.
dpres is a 2-element double-precision array that contains the
result of the calculation. The first element of dpres
contains the real part of the complex square root; the
second element contains the imaginary part.
Example:
DOUBLE PRECISION dparg(2),dpres(2)
dparg(1) = 10D0
dpres(2) = -10D0 !arg is (10,-10)
CALL CDSQRT(dparg,dpres)
CHKDIV
Subroutine
13.4.1.8 CHKDIV Subroutine - The CHKDIV subroutine returns the number
of the unit to which error messages are being written. This
subroutine returns the value -1 if the messages are being sent to the
terminal.
The form of the CHKDIV subroutine is:
CALL CHKDIV(unitvar)
where:
unitvar is the variable in which the unit number is stored.
CLFRMT
Subroutine
13-32
FUNCTIONS AND SUBROUTINES
13.4.1.9 CLRFMT Subroutine - The CLRFMT subroutine discards the
encoded form of the FORMAT statement saved by the execution of the
SAVFMT subroutine (see Section 13.4.1.25).
The form of the CLRFMT subroutine is:
CALL CLRFMT(arrayname)
where:
arrayname is the name of the array that contains the encoded
form of the FORMAT specifications saved by the
SAVFMT subroutine.
DATE
Subroutine
13.4.1.10 DATE Subroutine - The DATE subroutine stores the current
date as a left-justified ASCII string in a character variable. The
date is in the form:
dd-mmm-yyb
where:
dd is a 2-digit day (if the first digit is 0, it is converted
to a blank), mmm is a 3-letter month abbreviation (such as,
Jan,Feb), yy is a 2-letter year, and b is a blank. The data
is stored in ASCII, left-justified, and blank filled.
The form of the DATE subroutine is:
CALL DATE(name)
where:
name is the name of a character variable. The date returned
by the subroutine is stored in this variable.
NOTE
For compatibility with previous versions of
FORTRAN-10/20, you can specify a numeric array name as
the argument for the DATE subroutine. The current
date is stored as a left-justified ASCII string in a
2-word array or data item (double-precision or
complex). The array must have at least two elements.
13-33
FUNCTIONS AND SUBROUTINES
DIVERT
Subroutine
13.4.1.11 DIVERT Subroutine - The DIVERT subroutine enables you to
redirect error messages from the current device to an open file on a
specified device.
The form of the DIVERT subroutine is:
CALL DIVERT(un)
where:
un is the logical device number of the file on which the open
file resides.
DTOGA
Subroutine
13.4.1.12 DTOGA - The DTOGA subroutine converts elements of
double-precision arrays from D-floating double-precision format to
G-floating double-precision format.
The form of the DTOGA subroutine is:
CALL DTOGA (sname,dname,n)
where:
sname is the name of the source array.
dname is the name of the destination array.
n is the number of elements to convert.
(See Section 13.4.1.18 for the GTODA subroutine.)
DUMP
13-34
FUNCTIONS AND SUBROUTINES
Subroutine
13.4.1.13 DUMP Subroutine - The DUMP subroutine causes specified
portions of memory to be dumped to the line printer (LPT:).
The form of the DUMP subroutine is:
CALL DUMP(LB1,UB1,format1[...,LBn,UBn,formatn])
where:
LB1,UB1 are the integer values of the upper and lower memory
addresses to be dumped.
format1 is an integer that indicates the dump format. The
possible specifications are:
0 = octal
1 = real
2 = integer
3 = ASCII
If no arguments are supplied, all of user memory is dumped in octal.
If only the bounds arguments are specified, or if the format value is
out of range, the dump format is octal. If only the first bound
argument is specified, all locations from that address to the end of
memory are dumped.
The dump is terminated by a call to EXIT.
ERRSET
Subroutine
13.4.1.14 ERRSET Subroutine - The ERRSET subroutine controls the
output of warning messages during program execution.
The ERRSET subroutine has three forms:
1. CALL ERRSET(n)
2. CALL ERRSET(n,i)
13-35
FUNCTIONS AND SUBROUTINES
3. CALL ERRSET(n,i,subr)
where:
n is the maximum number of error messages to type.
i is the code to which error the call applies; one of the
following:
-1 any of the following
0 integer overflow
1 integer divide
2 input integer overflow
3 input floating overflow
4 floating overflow
5 floating divide check
6 floating underflow
7 input floating underflow
8 library routine error
9 output field width too small
21 FORLIB warnings
22 nonstandard usage warnings
23 Bounds check warnings
if i is not specified, -1 is assumed
subr is the name of the user-defined error handling routine
to be invoked each time any of the above errors occur.
The effect is as if
CALL SUBR (I,IPC,N2,ITYPE,UNFIXD,FIXED)
were placed in the program just after the instruction
causing the trap.
I = error number of trap, same as above
IPC = PC of trap instruction (if code 9 is
trapped, IPC = PC of the IOLST. call
N2 = second error number (reserved for Digital)
ITYPE = data type of value
UNFIXD = value returned by the hardware
FIXED = value after fixup (SUBR can change this
value)
If SUBR is not specified, no routine is called on
the APR trap.
13-36
FUNCTIONS AND SUBROUTINES
ERRSNS
Subroutine
13.4.1.15 ERRSNS Subroutine - The ERRSNS subroutine returns integer
values that describe the status (success or failure) of the last I/O
operation (see Appendix D). This subroutine can be used to determine
the reason for an error trapped by ERR= on an OPEN, CLOSE, or data
transfer operation. Both return values are always cleared after a
successful data transfer operation.
The forms of the ERRSNS subroutine are:
CALL ERRSNS (I)
or
CALL ERRSNS (I,J)
or
| CALL ERRSNS (I,J,MSG,K)
where:
I returns a FORTRAN-supplied number that describes the
class of failure that occurred.
J optionally returns a processor-specific number that
further describes or qualifies the type of the last
error.
MSG If present, is a character variable used to return the
ASCII text of the last error message. If the variable
for MSG is less than 80 characters, the text is
truncated; if the variable is greater than 80
characters, the text is padded to the right with
blanks.
NOTE
For compatibility with previous versions of
FORTRAN-10/20, you can specify a numeric array
as the MSG argument. The numeric array is used
as a 16-word array to return the ASCII text of
the last error message.
| K optionally returns the RMS STV code that explains the
| reason for the last RMS error.
13-37
FUNCTIONS AND SUBROUTINES
EXIT
Subroutine
13.4.1.16 EXIT Subroutine - The EXIT subroutine terminates the
program and returns control to the monitor. The EXIT subroutine takes
no arguments.
The form of the EXIT subroutine is:
CALL EXIT
FFUNIT
Subroutine
13.4.1.17 FFUNIT Subroutine - The FFUNIT subroutine returns the
lowest available FORTRAN logical unit number (see Table 10-3).
The form of the FFUNIT subroutine is:
CALL FFUNIT (n)
GTODA
Subroutine
13.4.1.18 GTODA Subroutine - The GTODA subroutine converts elements
of double-precision arrays from G-floating double-precision format to
D-floating double-precision format.
The form of the GTODA subroutine is:
CALL GTODA(sname,dname,n)
where:
13-38
FUNCTIONS AND SUBROUTINES
sname is the source array name.
dname is the destination array name.
n is the number of array elements to convert.
(See Section 13.4.1.12 for the DTOGA subroutine.)
ILL
Subroutine
13.4.1.19 ILL Subroutine - The ILL subroutine sets the ILLEG flag.
If this flag is set and an illegal character is encountered in
floating-point, double-precision input, the corresponding value is set
to zero and no error message is issued. The ILL subroutine takes no
arguments. The ILLEG flag is not set initially.
The form of the ILL subroutine is:
CALL ILL
LEGAL
Subroutine
13.4.1.20 LEGAL Subroutine - The LEGAL subroutine clears the ILLEG
flag set by the ILL subroutine. The LEGAL subroutine takes no
arguments.
The form of the LEGAL subroutine is:
CALL LEGAL
MVBITS
Subroutine
13-39
FUNCTIONS AND SUBROUTINES
13.4.1.21 MVBITS Subroutine - The MVBITS subroutine transfers a bit
field from one storage location (source) to a field in a second
storage location (destination).
The form of the MVBITS subroutine is:
CALL MVBITS(m,i,len,n,j)
where:
m is an integer expression that represents the source location
from which a bit field is transferred.
i is an integer expression that identifies the first bit
position in the source field transferred from m.
len is an integer expression that identifies the length of the
field transferred from m.
n is an integer variable or array element that is the
destination location to which a bit field is transferred.
j is an integer expression that identifies the first bit
position in the destination field transferred from m.
The MVBITS subroutine transfers len bits from position i through
i+len-1 of the source location (m) to positions j through j+len-1 of
the destination location (n). Other bits of the destination location
and all of the bits of the source location remain unchanged. The
values of i+len and j+len must not be greater than 36.
(See Section 13.1.4 for information on bit manipulation functions.)
OVERFL
Subroutine
13.4.1.22 OVERFL Subroutine - The OVERFL subroutine returns
information about overflow, underflow, and divide check.
The form of the OVERFL subroutine is:
CALL OVERFL(IANS)
where:
IANS is an integer variable whose value specifies whether an
overflow, underflow, or divide check has occurred since
13-40
FUNCTIONS AND SUBROUTINES
the last call to OVERFL. The values returned are:
1 = at least one overflow, underflow, or divide
check occurred.
2 = none occurred.
PDUMP
Subroutine
13.4.1.23 PDUMP Subroutine - The PDUMP subroutine functions exactly
like the DUMP subroutine (see Section 13.4.1.13) except that control
returns to the calling program after the dump has been executed.
The form of the PDUMP subroutine is:
CALL PDUMP(LB1,UB1,format1[...,LBn,UBn,formatn])
where:
LB1,UB1 are the integer values of the upper and lower memory
addresses to be dumped.
format1 is an integer that indicates the dump format. The
possible specifications are:
0 = octal
1 = real
2 = integer
3 = ASCII
If no arguments are supplied, all of user memory is dumped in octal.
If only the bounds arguments are specified, or if the format value is
out of range, the dump format is octal. If only the first bound
argument is specified, all locations from that address to the end of
memory are dumped.
QUIETX
Subroutine
13-41
FUNCTIONS AND SUBROUTINES
13.4.1.24 QUIETX Subroutine - The QUIETX subroutine suppresses all
summary typeout when the program terminates, including library error
summaries and CPU times. The QUIETX subroutine takes no arguments.
The form of the QUIETX subroutine is:
CALL QUIETX
SAVFMT
Subroutine
13.4.1.25 SAVFMT Subroutine - The SAVFMT subroutine directs FOROTS to
encode the FORMAT specifications contained in the specified character
variable or array, and to save the encoded form. This action improves
the performance of any future I/O statements which that character
variable or array is the format identifier.
FOROTS saves the encoded form of the format until a call to CLRFMT
(see Section 13.4.1.9) is executed for that variable or array, or
until another call to SAVFMT is executed for that variable or array.
NOTE
After a call to SAVFMT, you must not change the value
of the variable or array. If the value is changed,
the new value may be ignored. A call to SAVFMT with a
variable or array whose address is identical to that
in a previous call, does an implied call to CLRFMT.
The form of the SAVFMT subroutine is:
CALL SAVFMT(name[,arraysize])
where:
name is the name of the character variable or array
that contains the FORMAT descriptors that you want
encoded.
arraysize is the number of array elements if an array is
specified.
NOTE
For compatibility with previous versions of
FORTRAN-10/20, you can specify a numeric array name as
the argument for the SAVFMT subroutine.
13-42
FUNCTIONS AND SUBROUTINES
SAVRAN
Subroutine
13.4.1.26 SAVRAN Subroutine - The SAVRAN subroutine saves the last
internal integer seed value generated by the RAN function. The RAN
function, described in Section 13.3.1, returns a random number each
time it is called. This value can be used at a later time in a call
to SETRAN to reestablish the same random number sequence.
The form of the SAVRAN subroutine is:
CALL SAVRAN(n)
where:
n is an integer variable into which the SAVRAN subroutine
stores the last internal integer seed value generated.
SETRAN
Subroutine
13.4.1.27 SETRAN Subroutine - The SETRAN subroutine specifies the
internal integer seed value for the RAN function. If the SETRAN
argument is zero, RAN uses its own default starting value.
The form of the SETRAN subroutine is:
CALL SETRAN(n)
where:
n is a nonnegative integer constant or variable (less than
2**31).
SORT
Subroutine
13-43
FUNCTIONS AND SUBROUTINES
13.4.1.28 SORT Subroutine - The SORT subroutine sorts one or more
files using the SORT program. You can successfully use this
subroutine only if the SORT software has been installed (see the
FORTRAN Installation Guide). The SORT software is sold as a separate
product and may not be available at your installation.
The form of the SORT subroutine is:
CALL SORT('sort string')
where:
sort string is a command line containing file specifications
and SORT switches. For specific information about
the SORT command line, see the SORT/MERGE User's
Guide.
NOTE
The sort string must be compatible with
the current version of the standalone
SORT. Therefore, the string is not the
same for TOPS-10 and TOPS-20 (see the
SORT/MERGE User's Guide).
SRTINI
Subroutine
13.4.1.29 SRTINI Subroutine - The SRTINI subroutine directs FOROTS to
start allocating memory from top downward to account for large overlay
programs and preallocates pages 600:677 (octal) for SORT.
The form of the SRTINI routine is:
CALL SRTINI(n)
where:
n is top page number to use when allocating memory.
Note that FOROTS will not allocate pages (including DDT pages) that
have been marked as unavailable at memory initialization.
TIME
13-44
FUNCTIONS AND SUBROUTINES
Subroutine
13.4.1.30 TIME Subroutine - The TIME subroutine returns the current
time of day in left-justified ASCII.
The TIME subroutine has two forms:
CALL TIME(x)
or
CALL TIME(x,y)
where:
x is a character variable. In the one argument form, TIME
returns the time in x in the form: hh:mm, where hh is the
hour (24-hour time) and mm is the minutes.
y is a character variable. When the two argument form of the
TIME subroutine is used, the forms of the time returned in x
is the same as the one argument form, and the value returned
in y has the form: bss.t, where b is a blank, ss is the
current seconds, and t is the current tenths of seconds.
NOTE
For compatibility with previous versions of
FORTRAN-10/20, you can specify a numeric variable or
array element as an argument of the TIME subroutine.
The following example demonstrates using the one and the two argument
forms of the TIME subroutine in a program.
PROGRAM TIMTST
CHARACTER*10 X,Y
CALL TIME(X,Y)
WRITE(UNIT=5,FMT=101)X,Y
CALL TIME(X)
WRITE (UNIT=5, FMT=102)X
102 FORMAT(1X,'THE ONE ARGUMENT TIME RETURNS: ',A)
END
EXECUTE TIMTST
LINK: Loading
13-45
FUNCTIONS AND SUBROUTINES
[LNKXCT TIMTST execution]
THE TWO ARGUMENT TIME RETURNS: 09:00 20.9
THE ONE ARGUMENT TIME RETURNS: 09:00
CPU time 0.1 Elapsed time 0.2
TOPMEM
Subroutine
13.4.1.31 TOPMEM Subroutine - The TOPMEM subroutine directs FOROTS to
start allocating memory from a specified page number downward to
account for large overlay programs.
The form of the TOPMEM subroutine is:
CALL TOPMEM(n)
where:
n is the top page number to use in allocating memory.
Note that FOROTS will not allocate pages (including DDT pages) that
have been marked as unavailable at memory initialization.
TRACE
Subroutine
13.4.1.32 TRACE Subroutine - The TRACE subroutine generates a list of
active subprograms on the terminal. An active subprogram is one that
has been called but has not yet returned. The main program is always
active. The trace listing starts at the currently active routine (the
one containing the call to TRACE) and proceeds back to the main
program.
The form of the TRACE subroutine is:
CALL TRACE
The information produced by the TRACE routine consists of, for each
subprogram:
13-46
FUNCTIONS AND SUBROUTINES
1. The name of the routine
2. The address of the routine (in octal)
3. The address of the subprogram call (expressed as routine-name
+ offset)
4. The address of the subprogram call (expressed as label +
offset with the calling routine)
5. The number of arguments passed to the called routine
6. The types of the arguments passed including:
C - Character string descriptor
D - D-floating double precision
F - Real
G - G-floating double precision
I - Integer or double integer
K - Literal string
L - Logical
O - Octal or double octal
S - Statement label
U - Unknown argument type
X - Complex
If there are too many arguments to display, the 'types' column will
contain '...'.
If local symbols are loaded with the program, the label+offset
information will be much more informative. A label of the form 12345P
refers to FORTRAN statement number 12345; a label of the form 56789L
refers to line number 56789 in the compiler listing. Line number
labels only appear if the program was compiled with /DEBUG:LABELS (see
Chapter 16).
The traceback listing is sent to the error-message unit, which is
normally the terminal. You can use the DIVERT subroutine (Section
13.4.1.11) to change where the listing is sent.
Example:
PROGRAM MAIN
TYPE 10
10 FORMAT (/' Calling SUB1:')
CALL SUB1
TYPE 20
20 FORMAT (/' Calling SUB2:')
CALL SUB2 (A,B)
END
SUBROUTINE SUB1
Y = F(X)
END
13-47
FUNCTIONS AND SUBROUTINES
SUBROUTINE SUB2 (G,H)
CALL SUB3 (G,H,I)
END
SUBROUTINE SUB3 (A1,A2,A3)
CALL TRACE
END
FUNCTION F(Y)
CALL SUB2 (Y,0)
F=2.
END
EXECUTE TRC.FOR
LINK: Loading
[LNKXCT TRC execution]
Calling SUB1:
Name (Loc) <<--- Caller (Loc) Args Types
TRACE. (426373) <<--- SUB3+2 (SUB3+2) 0
SUB3 (256) <<--- SUB2+6 (SUB2+6) 3 FFI
SUB2 (232) <<--- F+20 (F+20) 2 FI
F (307) <<--- SUB1+2 (SUB1+2) 1 F
SUB1 (214) <<--- MAIN.+7 (MAIN.+7) 0
Calling SUB2:
Name (Loc) <<--- Caller (Loc) Args Types
TRACE. (426373) <<--- SUB3+2 (SUB3+2) 0
SUB3 (256) <<--- SUB2+6 (SUB2+6) 3 FFI
SUB2 (232) <<--- MAIN.+14 (MAIN.+14) 2 FF
CPU time 0.4 Elapsed time 3.1
13.4.2 User-Defined Subroutines
A subroutine subprogram is a separate program unit. The FORTRAN CALL
statement is used in a program unit to call a subroutine subprogram.
The CALL statement contains the name of the subroutine to which
control passes when the CALL statement is executed. The CALL
statement can also optionally contain actual arguments that are passed
to the called subroutine. The CALL statement is described in Section
13.4.2.2.
The SUBROUTINE statement is always the first statement in a subroutine
subprogram. The SUBROUTINE statement defines the name and,
optionally, any dummy arguments used by the subroutine. The
SUBROUTINE statement is described in Section 13.4.2.1.
The ENTRY statement enables you to enter a subroutine subprogram at a
statement other than the first statement of the subroutine. The ENTRY
13-48
FUNCTIONS AND SUBROUTINES
statement is described in Section 13.4.3.
The last logical statement of a subroutine subprogram is always the
RETURN statement. By default, the RETURN statement always returns
control to the first executable statement in the calling program that
immediately follows the CALL statement. Optionally, you may use the
alternate return form of the RETURN statement to return control to a
statement other than the default. Both forms of the RETURN statement
are described in Section 13.4.4.
13.4.2.1 SUBROUTINE Statement - The SUBROUTINE statement is always
the first statement in a subroutine subprogram. It is used to define
the name of the subroutine and, optionally, to define dummy arguments
that are used by the subroutine.
The form of the SUBROUTINE statement is:
SUBROUTINE sub [([d1[,d2]...])]
where:
sub is the symbolic name of the subroutine or dummy procedure.
d is an optional dummy argument for the subroutine subprogram.
This argument can be a variable name, an array name, a dummy
procedure name, or any combination of these separated by
commas. The parentheses are optional if no dummy arguments
are specified.
The following rules control the structuring of a subroutine
subprogram:
1. You can not use the symbolic name of the subprogram in any
statement within the defined subprogram except the SUBROUTINE
statement itself. The symbolic name of a subroutine is a
global name and must not be the same as any other global name
or any local name in the program unit.
2. The symbolic name of a dummy argument is local to the program
unit and must not appear in an EQUIVALENCE, PARAMETER, SAVE,
INTRINSIC, COMMON, or DATA statement except as a common block
name.
3. The subroutine subprogram may define or redefine one or more
of its dummy arguments so as to return results.
4. If the actual argument is a constant or expression, the
subroutine must not change the value of that argument.
5. The subroutine subprogram may contain any FORTRAN statement
except BLOCK DATA, FUNCTION, PROGRAM, another SUBROUTINE
statement, or any statement that either directly or
13-49
FUNCTIONS AND SUBROUTINES
indirectly references the subroutine being defined or any of
the subprograms in the chain of subprogram references leading
to this subroutine.
6. Dummy arguments that represent statement labels may be either
an *, $, or &.
7. The subprogram should contain at least one RETURN statement
and must be terminated by an END statement. The RETURN
statement indicates a logical end of the routine; the END
statement signifies the physical end of the subroutine. If
no RETURN precedes the END statement, then the RETURN
statement is implicit.
8. Subroutine subprograms can have as many entry points as
desired (see description of ENTRY statement given in Section
13.4.3).
9. A character dummy argument whose length specification is an
asterisk in parentheses may appear as an operand for
concatenation.
13.4.2.2 CALL Statement - The CALL statement is used in a program
unit to reference a subroutine. Execution of the CALL statement
causes a transfer of program control to the subroutine referenced in
the CALL statement.
The CALL statement can also contain a list of arguments that is used
by the computation performed in the referenced subroutine.
The form of the CALL statement is:
CALL sub [([a1[,a2]...])]
where:
sub is the symbolic name of a subroutine or dummy procedure.
a is an optional actual argument that is used by the
subroutine. The actual arguments in the CALL statement must
agree in position and type with the dummy arguments in the
referenced SUBROUTINE statement. The parentheses are
optional if no actual arguments are specified.
13.4.2.3 Execution of a CALL Statement - When a CALL statement is
executed, the following results occur:
1. Any actual arguments in the CALL statement argument list that
are expressions are evaluated.
13-50
FUNCTIONS AND SUBROUTINES
2. The actual arguments are then associated with the dummy
arguments in the referenced SUBROUTINE statement.
3. Control passes to the subroutine and it is executed.
4. Return of control from the referenced subroutine to the
calling program completes the execution of the CALL
statement.
A subroutine can be referenced within any other procedure or the main
program of the executable program. A subprogram cannot, however,
reference itself, either directly or indirectly.
13.4.2.4 Actual Arguments for a Subroutine - Actual arguments can
appear in the CALL statement argument list. Actual arguments must
agree in order, number, and type with the corresponding dummy
arguments in the dummy argument list of the referenced subroutine.
The exception to the agreement rules between actual and dummy argument
lists is the use of a subroutine name or an alternate return specifier
as an actual argument.
Actual arguments in CALL statements can be any of the following:
1. Any expression, including a character expression whose length
specification is an asterisk in parentheses.
2. An array name
3. An intrinsic function name
4. An external procedure name
5. A dummy procedure name
6. An alternate return label
An actual argument in a subroutine reference may be a dummy argument
name that appears in a dummy argument list within the subprogram
containing the reference. An asterisk dummy argument must not be used
as an actual argument in a subprogram reference.
13.4.3 ENTRY Statement
The ENTRY statement provides you with a method for entering a function
or subroutine subprogram at any executable statement. The ENTRY
statement can appear anywhere within a function subprogram after the
FUNCTION statement, or within a subroutine subprogram after the
SUBROUTINE statement. An ENTRY statement cannot appear between a DO
statement and the terminal statement of its DO-loop or inside a
block-IF statement.
13-51
FUNCTIONS AND SUBROUTINES
A subprogram may optionally have one or more ENTRY statements. An
ENTRY statement is classified as a nonexecutable statement.
The form of the ENTRY statement is:
ENTRY en [(d1 [,d2...])]
where:
en is the symbolic name of an entry in a function or subroutine
subprogram. This symbolic name is called an entry name. If
the entry name appears in a subroutine subprogram, it is
referred to as a subroutine name; if the entry name appears
in a function subprogram, it is called an external function
name.
d is a variable name, array name, dummy procedure name, or the
symbols: *, $, or & (these symbols can represent a dummy
argument which is an alternate return label). The symbol
references (asterisk, ampersand, and dollar sign) are
permitted only when the ENTRY statement appears in a
subroutine subprogram.
If you do not specify any parentheses after the entry name, you need
not specify any dummy arguments. If, however, you include the
parentheses, you must specify at least one dummy argument. The rules
for the use of an ENTRY statement follow:
1. The ENTRY statement allows entry into a subprogram at a place
other than that defined by the SUBROUTINE or FUNCTION
statement. You may include more than one ENTRY statement in
an external subprogram.
2. Execution begins at the first executable statement following
the ENTRY statement.
3. Appearance of an ENTRY statement in a subprogram does not
negate the rule that statement functions in subprograms must
precede the first executable statement.
4. ENTRY statements are nonexecutable and do not affect the
execution flow of a subprogram.
5. You can not use an ENTRY statement in a main program or have
a subprogram reference itself through its entry points.
6. You can not use an ENTRY statement in the range of a DO
statement construction.
7. The dummy arguments in the ENTRY statement need not agree in
order, number, or type with the dummy arguments in SUBROUTINE
or FUNCTION statements or any other ENTRY statement in the
subprogram. However, the arguments for each call or function
reference must agree with the dummy arguments in the
13-52
FUNCTIONS AND SUBROUTINES
SUBROUTINE, FUNCTION, or ENTRY statement that is referenced.
8. Entry into a subprogram initializes only the dummy arguments
of the referenced ENTRY statement.
9. You can not reference a dummy argument unless it appears in
the dummy list of the ENTRY, SUBROUTINE, or FUNCTION
statement by which the subprogram is entered.
10. The source subprogram must be ordered such that references to
dummy arguments in executable statements follow the
appearance of the dummy argument in the dummy list of a
SUBROUTINE, FUNCTION, or ENTRY statement.
11. Dummy arguments that were defined for a subprogram by some
previous reference to the subprogram are undefined for
subsequent entry into the subprogram.
12. The value of a function must be returned by use of the
current entry name.
13. If an entry name in a function subprogram is of type
character, each entry name and the name of the function
subprogram must be of type character. If the name of the
function subprogram or any entry in the subprogram has a
length of (*) declared, all such items must have a length
specification of the same integer value.
13.4.4 RETURN Statement
The RETURN statement returns control to the referencing program unit
and may appear only in a function subprogram or a subroutine
subprogram.
The RETURN statement has two possible forms, depending on whether it
is the last statement in a function subprogram or a subroutine
subprogram.
The form of the RETURN statement in a function subprogram is:
RETURN
The form of the RETURN statement in a subroutine subprogram is:
RETURN [e]
where:
e is an integer constant, variable, or expression. This form
of the RETURN statement is called an alternate return. The
alternate return form enables you to select any labeled
13-53
FUNCTIONS AND SUBROUTINES
statement in the calling program unit as a return point
after execution of the program unit in which the alternate
RETURN statement appears.
The value of e should be a positive integer that is equal to
or less than the number of statement labels given in the
argument list of the calling statement. If e is less than 1
or is larger than the number of available statement labels,
a standard return is performed. (A standard return
transfers control back to the first executable statement
immediately following the calling statement in the calling
program unit).
NOTE
A dummy argument for a statement label must be either
an asterisk (*), a dollar sign ($), or an ampersand
(&).
You may use more than one RETURN (standard return) statement in any
subprogram. The use of the alternate return form of the RETURN
statement is restricted to subroutine subprograms.
For example, assume the following statement sequence in a main
program:
CALL EXAMP(1,*10,K,*15,M,*20)
GO TO 101
.
.
.
10 alternate return #1
.
.
.
15 alternate return #2
.
.
.
20 alternate return #3
.
.
.
END
SUBROUTINE EXAMP (L, *,M, *,N,*)
.
.
.
RETURN
.
.
13-54
FUNCTIONS AND SUBROUTINES
.
RETURN
.
.
.
RETURN(I+J)
.
.
.
END
Each occurrence of RETURN returns control to the statement GO TO 101
in the calling program.
If, on the execution of the RETURN(I+J) statement, the value of (I+J)
is:
Value The following is performed:
less than one a standard return to the GO TO 101
statement is made
1 the return is made to statement 10
2 the return is made to statement 15
3 the return is made to statement 20
Greater than 3 a standard return to the GO TO 101
statement is made.
13.4.5 Dummy and Actual Arguments
Since you may reference subprograms at more than one point throughout
a program, many of the values used by the subprogram may be changed
each time it is used. Dummy arguments in subprograms represent the
actual values to be used, which are passed to the subprogram when it
is called.
For example, shown below is a subroutine (TEST) being called from the
main program by a CALL statement. In this example, the variables in
the CALL statement, A, B, and C(2), represent actual values in the
main program. They are therefore called actual arguments.
On the other hand, the variables in the SUBROUTINE statement, R, X,
and Z, do not represent any values until they have values passed to
them from the CALL statement. They are therefore called dummy
arguments.
(The CALL, SUBROUTINE, and RETURN statements are described in Sections
13.4.2.2, 13.4.2.1, and 13.4.4, respectively.)
CALL TEST (A,B,C(2))
13-55
FUNCTIONS AND SUBROUTINES
.
.
.
END
SUBROUTINE TEST (R,X,Z)
.
.
.
RETURN
END
Functions and subroutines use dummy arguments to indicate the type of
the actual arguments they represent and whether the actual arguments
are variables, arrays, subroutine names, or the names of external
functions. Each dummy argument must be used within a function or
subroutine as if it were a variable, array, subroutine, or external
function identifier.
Dummy arguments are given in an argument list associated with the
identifier assigned to the subprogram; actual arguments are normally
given in an argument list associated with a call made to the desired
subprogram.
The position, number, and type of each dummy argument in a subprogram
list must agree with the position, number, and type of each argument
list of the subprogram reference.
NOTE
If the /DEBUG:ARGUMENTS compiler switch is specified
(see Section 16.3), optional type checking is
performed at load time on dummy and actual arguments.
Dummy arguments may be:
1. variables
2. array names
3. subroutine identifiers
4. function identifiers
5. the symbols *, $, or & that are used to denote the position
of alternate return labels
When you reference a subprogram, its dummy arguments are replaced by
the corresponding actual arguments supplied in the reference. All
appearances of a dummy argument within a function or subroutine are
related to the given actual arguments. Except for subroutine
identifiers and character constants, a valid association between dummy
and actual arguments occurs only if both are of the same type;
13-56
FUNCTIONS AND SUBROUTINES
otherwise, the results of the subprogram computations will be
unpredictable.
Argument association may be carried through more than one level of
subprogram reference if a valid association is maintained through each
level. The dummy/actual argument associations established when a
subprogram is referenced are terminated when the desired subprogram
operations are completed.
The following rules govern the use and form of dummy arguments:
1. The number and type of the dummy arguments of a procedure
must be the same as the number and type of the actual
arguments given each time the procedure is referenced.
2. Dummy argument names may not appear in EQUIVALENCE, DATA, or
COMMON statements.
3. A variable dummy argument should have a variable, an array
element identifier, an expression, or a constant as its
corresponding argument.
4. An array dummy argument should have either an array name or
an array element identifier as its corresponding actual
argument. If the actual argument is an array, the length of
the dummy array should be less than or equal to that of the
actual array. Each element of a dummy array is associated
directly with the corresponding elements of the actual array.
5. A dummy argument representing a subroutine identifier should
have a subroutine name as its actual argument.
6. A dummy argument representing an external function must have
an external function as its actual argument.
7. A dummy argument may be defined or redefined in a referenced
subprogram only if its corresponding actual argument is a
variable. If dummy arguments are array names, then elements
of the array may be redefined.
Additional information regarding the use of dummy and actual arguments
is given in the description of how subprograms are defined and
referenced.
13.4.5.1 Length of Character Dummy and Actual Arguments - The length
of a dummy argument of type character must not be greater than the
length of its associated actual argument. Note that if the character
dummy argument's length is specified as *(*), the length used is
exactly the length of the associated actual argument. This is known
as a passed length character argument.
13-57
FUNCTIONS AND SUBROUTINES
The length of the dummy argument is determined each time control
transfers to the function. The length of the actual argument can be
the length of a character variable, array element, substring, or
expression.
A character array dummy argument can have passed length. The length
of each element in the dummy argument is the length of the elements in
the actual argument. The passed length and the array declaractor
together determine the size of the passed length character array.
The following example of a function subprogram uses a passed length
character argument. The function finds the position of the character
with the highest ASCII code value; it uses the length of the passed
length character argument to control the iteration. (Note that the
intrinsic function LEN is used to determine the length of the
argument. See Table 13-1 for a description of the LEN function.)
INTEGER FUNCTION ICMAX(CVAR)
CHARACTER*(*) CVAR
ICMAX = 1
DO 10 I = 2, LEN(CVAR)
10 IF (CVAR(I:I) .GT. CVAR(ICMAX:ICMAX)) ICMAX =I
RETURN
END
Each of the following function references specifies a different length
for the dummy argument:
CHARACTER VAR*10, CARRAY(3,5)*20
.
.
.
I1 = ICMAX(VAR)
I2 = ICMAX(CARRAY(2,2))
I3 = ICMAX(VAR(3:8))
I4 = ICMAX(CARRAY(1,3)(5:15))
I5 = ICMAX (VAR(3:4)//CARRAY(3,5))
13.4.5.2 Character and Hollerith Constants as Actual Arguments -
Actual arguments and their corresponding dummy arguments must agree in
data type. If the actual argument is a Hollerith constant (for
example, 4HABCD), the dummy argument must be of numeric data type.
In FORTRAN-10/20, if an actual argument is a character constant (for
example 'ABCD'), the corresponding dummy argument can have either
numeric or character data type. If the dummy argument has a numeric
data type, the character constant 'ABCD' is, in effect, converted to a
Hollerith constant by the FORTRAN compiler and the loader.
13-58
FUNCTIONS AND SUBROUTINES
An exception to this occurs when the function or subroutine name is
itself a dummy argument. It is not possible to determine at compile
time or load time whether a character constant or Hollerith constant
is required. In this case, a character constant actual argument can
correspond only to a character dummy argument.
13-59
14-1
CHAPTER 14
BLOCK DATA SUBPROGRAMS
Block data subprograms provide initial values for variables and array
elements in named common blocks.
A block data subprogram must start with the BLOCK DATA statement. The
only valid statements within a block data subprogram are the
specification and DATA statements (COMMON, DIMENSION, EQUIVALENCE,
IMPLICIT, PARAMETER, SAVE, type statements, and DATA statements). The
last statement of a block data subprogram must be an END statement.
You can enter initial values into more than one labeled common block
in a single subprogram of this type.
An executable program can contain more than one block data subprogram.
14.1 BLOCK DATA STATEMENT
The form of the BLOCK DATA statement is:
BLOCK DATA [sub]
where:
sub is the optional symbolic name of a block data subprogram in
which the BLOCK DATA statement appears.
The name sub is a global name and must therefore be a unique
symbolic name within the executable program.
The following is an example of a block data subprogram:
BLOCK DATA TEST
COMMON /SQUARE/ CIRCLE,RECTAN,PI
DATA CIRCLE,RECTAN,PI/1.,2.,3.14159/
END
14-1
BLOCK DATA SUBPROGRAMS
This example initializes the COMMON variables CIRCLE, RECTAN, and PI
to 1., 2., and 3.14159 respectively.
14-2
CHAPTER 15
WRITING USER PROGRAMS
This chapter is a guide for writing effective programs with FORTRAN.
It contains techniques for optimization, interaction with non-FORTRAN
programs, and other useful programming hints.
15.1 GENERAL PROGRAMMING CONSIDERATIONS
The following paragraphs describe programming considerations you
should observe when preparing a FORTRAN program to be compiled by
FORTRAN.
15.1.1 Accuracy and Range of Double-Precision Numbers
Floating-point and real numbers may consist of up to 16 digits in a
double-precision mode. Their range is specified in Chapter 3, Section
3.2. You must be careful when testing the value of a number within
the specified range, since, although numbers up to 10**38 may be
represented, FORTRAN can only test numbers of up to eight significant
digits (REAL precision) and 16 significant digits (DOUBLE precision).
NOTE
For KL model B systems, if the /GFLOATING compiler
switch is specified (see Section 16.1.3 or 16.2.3),
double-precision numbers up to 10**307 can be
represented.
You must also be careful when testing floating-point computations for
a result of 0. In most cases the anticipated result, that is, 0 will
be obtained; however, in some cases the result may be a very small
number that approximates 0. Such an approximation of 0 will cause
tests for equality to 0 to fail.
To increase the accuracy of its compile-time arithmetic, the compiler
15-1
WRITING USER PROGRAMS
does all floating point arithmetic in double precision (it converts
back to single precision when necessary). For KL model B systems, if
the /GFLOATING compiler switch is specified (see Section 16.1.3 or
16.2.3), the compiler does its compile-time arithmetic in G-floating
double-precision. If the /DFLOATING compiler switch is specified (the
default), the compiler does its compile-time arithmetic in D-floating
double-precision.
Compile-time arithmetic done in G-floating double-precision may not
overflow or underflow as it might with D-floating double-precision
arithmetic. G-floating double-precision has a greater range than
D-floating double-precision (see Section 3.4).
15.1.2 Writing FORTRAN Programs for Use on Other Computers
If you prepare a program to run on both TOPS-10 or TOPS-20 and another
manufacturer's computer, you should:
1. Avoid using any blue print language extensions in this
manual. (All information in blue print represents aspects of
FORTRAN that are extensions to the FORTRAN-77 Standard.)
2. Consider the accuracy and size of the numbers that another
manufacturer's computer is capable of handling.
You can use the /FLAG compiler switch to invoke the compatibility
flagger. This feature provides warning messages for language elements
that are extensions to the FORTRAN-77 standard or that are
incompatible with VAX FORTRAN (see Section 16.6).
| 15.1.2.1 Remote Links - A remote network link is established each
| time an OPEN statement or INQUIRE-by-file for a remote file is
| performed. The link remains open until the file is closed or the
| INQUIRE statement completes. The maximum number of simultaneous open
| links available to a user process is a site-dependent monitor
| parameter.
|
|
|
| 15.1.2.2 Reducing Network Overhead - A substantial part of the
| overhead associated with remote file access consists in establishing
| the remote link. Since a READ, READ, WRITE sequence for a file opened
| for read access causes FOROTS to close and reopen the file for
| read/write access, network overhead can be reduced by ensuring that
| remotes files to be written to are opened with an ACCESS specifying
| both read and write access. Likewise, file specifications in CLOSE
| statements for remote files, which cause FOROTS to establish a link
| for a network rename operation, should not be routinely used unless a
15-2
WRITING USER PROGRAMS
| full remote rename is required.
15.1.3 Using Floating-Point DO Loops
FORTRAN permits you to use noninteger, single- or double- precision
numbers as the parameter variables in a DO statement. This lets you
generate a wider range of values for the DO loop index variables,
which may, in turn, be used inside the loop for computations.
WARNING
If a noninteger index is used, accumulation of
rounding errors may lead to unexpected values for the
loop variable.
15.1.4 Computation of DO Loop Iterations
The number of times through a DO loop is computed outside the loop and
is not affected by any changes to the DO index parameters within the
loop. The formula for the number of times a DO loop is executed is:
DO 10 I=M1,M2,M3
Number of cycles=MAX (INT((M2-M1+M3)/M3),0)
The values of the parameters M1, M2, M3 can be of any type except
complex. If the iteration count is less than or equal to zero, the
body of the loop is not executed. The index variable retains its
assigned value (M1). (See Section 9.3.)
NOTE
The interpretation of the iteration count and the
index variable described above is different from that
of earlier versions of FORTRAN-10/20. If the /NOF77
compiler switch is specified (see Section 16.1.3 or
16.2.3), and the iteration count is less than or equal
to zero, the body of the loop is executed once. In
addition, the final value of the index variable of the
DO statement is undefined after a normal exit.
15.1.5 Subroutines - Programming Considerations
Consider the following items when preparing and executing subroutines:
15-3
WRITING USER PROGRAMS
1. During execution, no check is made to see if the proper
number of arguments is passed (unless the /DEBUG:ARGUMENTS
compiler switch is specified, see Section 16.3).
2. If the number of actual arguments passed to a subroutine is
less than the number of dummy arguments specified, the values
of the unspecified arguments are undefined (unless the
/DEBUG:ARGUMENTS compiler switch is specified, see Section
16.3).
3. If the number of actual arguments passed to a subroutine is
greater than the number of dummy arguments given, the excess
arguments are ignored (unless the /DEBUG:ARGUMENTS compiler
switch is specified, see Section 16.3).
4. If an actual argument is a constant and its corresponding
dummy argument is set to another value (an illegal usage),
all references made to the constant in the calling program
may be changed to the new value of the dummy argument.
5. No check is made to see if the arguments passed are of the
same type as the dummy arguments (unless the /DEBUG:ARGUMENTS
compiler switch is specified, see Section 16.3).
NOTE
An exception is that a check is always made
for G-floating and D-floating type mismatches
regardless of the /DEBUG:ARGUMENTS switch
being specified.
In addition, when you pass character data to
a subroutine or function that is compiled
with the /EXTEND switch, the calling program
must also be compiled with the /EXTEND
switch.
If an actual parameter is a constant and the corresponding
dummy is of type real, be sure to include the decimal point
in the constant. If the dummy is double-precision, be sure
to specify the constant with a "D".
NOTE
You are given no warning if any of the situations
described in items 1,2,3,4, or 5 occur (unless the
/DEBUG:ARGUMENTS compiler switch is specified, see
Section 16.3).
Examples:
15-4
WRITING USER PROGRAMS
If a function F has a single dummy argument of type real, and that
function is called with:
F(2)
F interprets the integer 2 as an unnormalized floating-point number.
In this instance, F(A) should be called with:
F(2.0)
Similarly, if the function F1(D) is called with:
F1(2.5)
and D is double-precision, F1 assumes that its parameters have been
specified with two words of precision and picks up whatever follows
the constant 2.5 in memory. The proper method is to use:
F1(2.5D0)
15.1.6 Reordering of Computations
Computations that are not enclosed within parentheses may be reordered
by the compiler. Sometimes it is necessary to use parentheses to
ensure proper results from a specific computation.
For example, assuming that:
1. RL1 represents a large number, such that RL1*RL2 will cause
an overflow condition, and
2. RS1 is a very small number, that is, less than 1, the program
sequence:
.
.
.
A=RS1*RL1*RL2
B=RS2*RL2*RL1
.
.
.
will not produce an overflow when evaluated left to right,
since the first computation in each expression (that is,
RS1*RL1 and RS2*RL2) will produce an interim result that is
smaller than either large number (RL1 or RL2).
However, the compiler may recognize RL1*RL2 as a common subexpression
(see Section 15.2.1.1) and generate the following sequence:
15-5
WRITING USER PROGRAMS
temp = RL1*RL2
A = RS1*temp
B = RS2*temp
The computation of temp will cause an overflow.
You should write the program as follows to ensure that the desired
results are obtained:
.
.
A=(RS1*RL1)*RL2
B=(RS2*RL2)*RL1
Computations may be reordered even when global optimization is not
selected.
15.1.7 Dimensioning of Dummy Arrays
When you specify an array as a dummy argument to a subprogram unit,
you must indicate to the compiler that the parameter is an array by
dimensioning the array in a specification statement. This is the only
way the compiler is able to distinguish a reference to such an array
from a function reference. A dummy array can be dimensioned the
following ways:
1. Assumed size
2. Adjustable dimensioned
3. Fixed dimension bound
Dimensioning the array with a size of 1 is a common, although
dangerous, practice. The alternative to this practice is to use
assumed-size arrays (see Section 7.1.2).
Example:
SUBROUTINE SUB1(A,B)
DIMENSION A(1)
There are disadvantages to using the above technique because it may
prevent the compiler from diagnosing illegal programs, specifically:
1. Reading or writing the array by name
DIMENSION ARRAY (10)
READ (1) ARRAY
The above is a binary read that will read ten words into
15-6
WRITING USER PROGRAMS
ARRAY.
SUBROUTINE SUB1(A)
DIMENSION A(1)
READ(1)A
This binary read will cause one word to be read into A.
2. Using the array as a format
SUBROUTINE SUB2(FMT)
DIMENSION FMT(1)
READ (1,FMT)
Only the first word of the format specification contained in
FMT is used.
3. Using the /DEBUG:BOUNDS compilation switch (see Section
16.3), the dimension information used is that which is
specified in the array declaration
SUBROUTINE SUB3(A)
DIMENSION A(1)
A(2)=0
The reference to A(2) will cause the out-of-bounds warning
message to be generated.
15.2 FORTRAN GLOBAL OPTIMIZATION
You have the option of invoking the global optimizer during
compilation. The optimizer treats groups of statements in the source
program as a single entity. The purpose of the global optimizer is to
prepare a more efficient object program that produces the same results
as the original unoptimized program, but takes significantly less
execution time.
The output of the lexical and syntactic analysis phase of the compiler
is developed into an optimized source program equivalent (in results)
to the original. The optimized program is then processed by the
standard compiler code generation phase.
15.2.1 Optimization Techniques
15-7
WRITING USER PROGRAMS
15.2.1.1 Elimination of Redundant Computations - Often the same
subexpression will appear in more than one computation throughout a
program. If the values of the operands of such a common expression
are not changed between computations, the subexpression may be written
as a separate arithmetic expression. Also, the variable representing
its resultant may then be substituted where the subexpression appears.
This eliminates unnecessary recomputation of the subexpression. For
example, the instruction sequence:
A=B*C+E*F
.
.
.
H=A+G-B*C
.
.
.
IF((B*C)-H) 10,20,30
contains the subexpression B*C three times when it really needs to be
computed only once. Rewriting the preceding sequence as:
T=B*C
A=T+E*F
.
.
H=A+G-T
.
.
IF(T-H) 10,20,30
eliminates two computations of the subexpression B*C from the overall
sequence.
Decreasing the number of arithmetic operations performed in a source
program by the elimination of common subexpressions shortens the
execution time of the resulting object program.
15.2.1.2 Reduction of Operator Strength - The time required to
execute arithmetic operations varies according to the operator(s)
involved. The hierarchy of arithmetic operations according to the
amount of execution time required is:
MOST TIME OPERATOR
**
/
*
LEAST TIME +,-
During program optimization, the global optimizer replaces, where
15-8
WRITING USER PROGRAMS
possible some arithmetic operations that require the most time with
operations that require less time. For example, consider the
following DO loop that is used to create a table for the conversion of
from 1 to 20 miles to their equivalents in feet:
DO 10 MILES=1,20
10 IFEET(MILES)=5280*MILES
The execution time of the loop would be shorter if the time-consuming
multiply operation, that is, 5280*MILES, could be replaced by a faster
operation. Since you increment MILES on each pass, you can replace
the multiply operation by an add and total operation.
In its optimized form, the loop would be replaced by a sequence
equivalent to:
K=5280
DO 10 MILES=1,20
IFEET(MILES)=K
10 K=K+5280
In the optimized form of the loop, the value of K is set to 5280 for
the first iteration of the loop, and is increased by 5280 for each
succeeding iteration of the loop.
This situation occurs frequently in subscript calculations that
implicitly contain multiplications.
15.2.1.3 Removal of Constant Computation from Loops - The speed with
which a given algorithm may be executed can be increased if
instructions and/or computations are moved out of frequently traversed
program sequences into less frequently traversed program sequences.
Movement of code is possible only if none of the arguments in the
items to be moved are redefined within the code sequences from which
they are to be taken. Computations within a loop consisting of
variables or constants that are not changed in value within the loop
may be moved outside the loop. Decreasing the number of computations
made within a loop greatly decreases the execution time required by
the loop.
For example, in the sequence:
DO 10 I=1,100
10 F=2.0*Q*A(I)+F
the value of the computation 2.0*Q, once calculated on the first
Numerical analysis considerations severely limit the number of cases
where this is possible.
15-9
WRITING USER PROGRAMS
iteration, will remain unchanged during the remaining 99 iterations of
the loop. Reforming the preceding sequence to:
QQ=2.0*Q
DO 10 I=1,100
10 F=QQ*A(I)+F
moves the calculation 2.0*Q outside the scope of the loop. This
movement of code eliminates 99 multiply operations.
In addition, it is possible to remove entire assignment statements
from loops. This action can be easily detected from the macro
expanded listings. The internal sequence number remains with the
statement and appears out of order in the leftmost column of the macro
expanded listing (LINE).
15.2.1.4 Constant Folding and Propagation - In this method of
optimization, expressions containing determinate constant values are
detected and the constants are replaced, at compile time, by their
defined or calculated value. For example, assume that the constant PI
is defined and used in the following manner:
.
.
.
PI=3.14159
.
.
.
X=2*PI*Y
.
.
.
At compile time, the optimizer will have used the defined value of PI
to calculate the value of the subexpression 2*PI. The optimized
sequence would then be:
.
.
PI=3.14159
.
.
.
X=6.28318*Y
.
.
thereby eliminating a multiply operation from the object code program.
15-10
WRITING USER PROGRAMS
The evaluation of constant expressions at compile time is called
"folding"; the replacement of variables with their constant values is
called "constant propagation".
NOTE
For KL model B systems, use of the /GFLOATING compiler
switch (see Section 16.1.3 or 16.2.3) may affect
compile-time arithmetic.
15.2.1.5 Removal of Inaccessible Code - The optimizer detects and
eliminates any code within the source program that cannot be accessed.
In general, this will not happen since programmers do not normally
include such code in their programs; however, inaccessible code may
appear in a program during the debugging process. The removal of
inaccessible code by the optimizer reduces the size of the object
program.
A warning message is generated for each inaccessible line removed.
15.2.1.6 Global Register Allocation - During the compilation of a
source program, the optimizer controls the allocation of registers to
minimize computation time in the optimized object program. The
allocation process is designed to minimize the number of MOVE and
MOVEM machine instructions that will appear in the most frequently
executed portions of the code.
15.2.1.7 I/O Optimization - Every effort is made to minimize the
number of required calls to the FOROTS system. This is done primarily
through extensive analysis of implied DO loop constructs on I/O data
transfer statements. The formats of these special blocks are
described in Chapter 18. These optimizations reduce the size of the
program (argument code plus argument block size is reduced) and
greatly improve the performance of programs that use implied DO loop
I/O statements.
15.2.1.8 Uninitialized Variable Detection - A warning message may be
generated when a scalar variable is referenced before it has received
a value (only when optimizing).
15-11
WRITING USER PROGRAMS
15.2.1.9 Test Replacement - If the only use of a DO loop index is to
reduce operator strength (see Section 15.2.1.2) and the loop does not
contain exits (GO TOs out of the loop), the DO loop index is not
needed and can be replaced by the reduced variable.
For example:
DO 10 I=1,10
K=K+7*I
10 CONTINUE
Reduction of operator strength and test replacement together transform
this loop into:
DO 10 I=7,70,7
K=K+I
10 CONTINUE
This situation occurs frequently in subscript computation. After
execution of these statements, I=11.
15.2.2 Programming Techniques for Effective Optimization
Observe the following recommendations during the coding of a FORTRAN
source program. They will improve the effectiveness of the optimizer:
1. Do not use DO loops with an extended range.
2. Specify label lists when using assigned GO TOs.
3. Nest loops so that the innermost index is the one with the
largest range of values.
4. Avoid the use of associated I/O variables.
5. Avoid unnecessary use of COMMON and EQUIVALENCE.
15.3 FUNCTION SIDE EFFECTS
Unpredictable results can occur if a statement includes calls to
different functions that modify the same variables.
Consider the following example:
COMMON A
A=5.
P=F(1.)+Q(2.)
15-12
WRITING USER PROGRAMS
END
FUNCTION F(X)
COMMON A
A=0.
F=X+1
END
FUNCTION Q(Y)
COMMON A
Q=A
END
In the preceding sequence, if P is evaluated by calling F before Q,
the value of P will be 2. If P is evaluated by calling Q before F,
the value of P will be 7.
15.4 INTERACTING WITH NON-FORTRAN PROGRAMS AND FILES
15.4.1 Using The Sharable High-Segment FOROTS
If your program does not contain a FORTRAN main program module, and
you wish to have the sharable FOROTS GETSEGed at run time, you must do
the following:
1. Force the loading of the FOROTS initialization routine RESET.
by declaring it as an external.
2. Define the symbol FOROT% as a global with a positive, nonzero
value before FORLIB.REL is searched.
3. Initialize FOROTS by the appropriate initialization call:
JSP 16, RESET.
EXP 0
15.4.2 Calling Sequences
The following paragraphs describe the standard procedures for writing
subroutine calls.
1. Procedure
a. The calling program must load the accumulator (AC) 16
with the address of the first argument in the argument
list.
b. The subroutine is then called by a PUSHJ instruction
15-13
WRITING USER PROGRAMS
using AC 17.
c. The return will be made to the instruction immediately
after the PUSHJ 17 instruction.
d. The FOROTS trace facility requires the calling sequence
to be:
XMOVEI 16,AP
PUSHJ 17,F
where AP is the pointer to the argument list and F is the
subprogram name. The word preceding the first word of an
entry point should have its name in SIXBIT.
2. Restrictions
a. Skip returns are not permitted.
b. The contents of the pushdown stack located before the
address specified by AC 17 belong to the calling program;
they cannot be read by the called subprogram.
c. FOROTS assumes that it has control of the stack;
therefore, you must not create your own stack. The
FOROTS stack is initialized by the call to RESET. (See
Section 15.4.1).
15.4.3 Accumulator Usage
The specific functions performed by accumulators (AC) 17,16,0, and 1
are:
1. Pushdown Pointer - AC 17 is always maintained as a pushdown
pointer. In section zero, its right half points to the last
location in use on the stack, and its left half contains the
negative of the number of words allocated to the unused
remainder of the stack.
In non-zero sections, the pushdown pointer contains the
global address of the last location in use on the stack.
2. Argument List Pointer - AC 16 is used as the argument
pointer. The called subprogram does not need to preserve its
contents. The calling program cannot depend on getting back
the address of the argument list passed to the called
subprogram. AC 16 cannot point to the ACs or to the stack.
15-14
WRITING USER PROGRAMS
3. Temporary and Value Return Registers - AC 0 and 1 are used as
temporary registers and for returning values. The called
subprogram does not need to preserve the contents of AC 0 or
1 (even if not returning a value). The calling program must
never depend on getting back the original contents of the
data passed to the called subprogram.
4. Returning Values - A subroutine subprogram may pass back
results by modifying arguments.
A numeric function subprogram always returns the value of the
function in AC 0 (or ACs 0-1 if the value is double precision
or complex). A function subprogram may also pass back
additional results by modifying the arguments. (See Section
15.4.4 for a description of character functions.)
5. Preserved ACs - FORTRAN function subprograms preserve ACs 2
through 15; subroutine subprograms do not.
The design of the called subprogram cannot depend on the contents of
any of the ACs being set up by the calling subprogram, except for ACs
16 and 17. Passing information must be done explicitly by the
argument list mechanism. Otherwise, the called subprograms cannot be
written in either FORTRAN or COBOL.
15.4.4 Argument Lists
Since the FORTRAN compiler uses the indirect bits on argument lists
(note that this permits shared, pure code argument lists), it is
essential for code that accesses parameters to take this into account.
Specifically, sequences that obtained the values of parameters through
use of operations such as:
HRRZ R,1(16)
to pick up the address of the second argument should be changed to
XMOVEI R,@1(16)
The latter operation will work when interfacing with FORTRAN.
The format of the argument list is as follows:
Arg count word
Arg list addr.---First arg entry
Second arg entry
.
.
.
Last arg entry
15-15
WRITING USER PROGRAMS
The format of the arg count word is:
bits 0-17 These contain -n, where n is the number of arg
entries.
bits 18-35 Reserved for future DIGITAL development, and must be
0.
The format of an arg entry is as follows (each entry is a single
word):
bit 0 IFIW (Instruction Format Indirect Word) flag, must be
1.
bits 1-8 Reserved for future DIGITAL development, must be 0.
bits 9-12 Arg type code.
bit 13 Indirect bit if desired.
bits 14-17 Index field, must be 0.
bits 18-35 Address of the argument.
For character functions, the first argument points to the return
value, which is a character string descriptor (see Section 15.4.6).
The actual arguments to the function start in the second argument
entry.
The following restrictions should be observed:
1. Neither the argument list nor the arguments themselves can be
on the stack. The same restriction applies to any indirect
argument pointers.
2. The called program may not modify the argument list itself.
The argument list may be in a write-protected segment.
Note that the arg count word is at position -1 with respect
to the contents of AC 16. This word is always required even
if the subroutine does not handle a variable number of
arguments. A subroutine that has no arguments must still
provide an argument list consisting of two words, that is,
the argument count word with a 0 in it and a zero argument
word.
Example:
XMOVEI 16,AP ;SET UP ARG POINTER
PUSHJ 17,SUB ;CALL SUBROUTINE
... ;RETURN HERE
.
.
.
;ARGUMENT LIST
-3,,0
AP: IFIW 4,A
15-16
WRITING USER PROGRAMS
IFIW 4,B
IFIW 4,C
;SUBROUTINE TO SET THIRD ARG TO SUM OF FIRST TWO ARGS
SUB: MOVE T,@0(16) ;GET FIRST ARG
ADD T,@1(16) ;ADD SECOND ARG
MOVEM T,@2(16) ;SET THIRD ARG
POPJ 17, ;RETURN TO CALLER
15.4.5 Argument Types
Table 15-1: Argument Types and Types Codes
Type Code Description
(Octal)
FORTRAN Use COBOL Use
0 Unspecified Unspecified
1 FORTRAN Logical Not applicable
2 Integer 1-word COMP
3 Reserved Reserved
4 Real COMP-1
5 Reserved Reserved
6 Octal Reserved
7 Label Procedure address
10 Double real Not applicable
(D-floating)
11 Not applicable 2-word COMP
12 Double octal Not applicable
13 Double real Not applicable
(G-floating)
14 Complex Not applicable
15 Character Byte string descriptor
16 Reserved Reserved
17 Hollerith Not applicable
Literal arguments are permitted, but they must reside in a writable
segment. This is because the FORTRAN compiler makes a local copy of
all non array elements and may copy dummy arguments back to the actual
arguments. All unused type codes are reserved for future DIGITAL
development.
15-17
WRITING USER PROGRAMS
15.4.6 Description of Arguments
The types of the arguments that may be passed are:
1. Type 0 - Unspecified
The calling program has not specified the type. The called
subprograms should assume that the argument is of the correct
type if it is checking types. If several types are possible,
the called subprogram should assume a default as part of its
specification. If none of the above conditions is true, the
called subprogram should handle the argument as an integer
(type 2).
2. Type 1 - FORTRAN logical
A 36-bit binary value containing 0 or positive to specify
.FALSE. and negative to specify .TRUE..
3. Type 2 - Integer and 1-word-COMP
A 36-bit 2's complement signed binary integer.
4. Type 4 - Real and COMP-1
A 36-bit floating-point number.
bit 0 sign
bits 1-8 excess 128 exponent
bits 9-35 mantissa
5. Type 6 - Octal
A 36-bit unsigned binary value.
6. Type 7 - Label and procedure address
The address of the parameter is the address of an alternate
return label or a subprogram.
7. Type 10 - Double real (D-floating)
A double-precision floating-point number represented in
D-floating form. (See Section 3.4.)
8. Type 11 - 2-word COMP
A 2-word (72-bit) 2's complement signed binary integer.
word 1, bit 0 sign
word 1, bits 1-35 high order
word 2, bit 0 same as word 1, bit 0
15-18
WRITING USER PROGRAMS
word 2, bits 1-35 low order
9. Type 12 - Double octal
A 72-bit unsigned binary value.
10. Type 13 - Double real (G-floating) (KL model B only)
A double-precision floating-point number represented in
G-floating form. (See Section 3.4.)
11. Type 14 - Complex
A complex number represented as an ordered pair of 36-bit
floating-point numbers. The first represents the real part,
and the second represents the imaginary part.
12. Type 15 - Character string descriptor
The format of the character string descriptor is:
word 1: ILDB-type pointer, that is, aimed at the
character preceding the first character of the
string
word 2: EXP character count
The character descriptor may not be modified by the called
program. The character string itself must consist of a
string of contiguous 7-bit ASCII characters.
13. Type 17 - Hollerith
A string of contiguous 7-bit ASCII characters left justified
on the word boundary of the first word and terminated by a
null character in the last word.
The FORTRAN compiler emits constants that are padded with
spaces to a word boundary, followed by a full-word containing
zero.
15.4.7 Interaction with COBOL
FORTRAN programs can call COBOL programs as subprograms, and,
conversely, the COBOL programs can call FORTRAN programs as
subprograms.
Note that I/O operations can be performed only in subprograms that are
written in the same language as the main program. Also note that APR
trap handling will be done in a manner consistent with the language
used in the main program.
15-19
WRITING USER PROGRAMS
15.4.7.1 Calling FORTRAN Subprograms from COBOL Programs - COBOL
programmers may write subprograms in FORTRAN to use the conveniences
and facilities provided by this language. The COBOL verb ENTER is
used to call FORTRAN subroutines. The form of ENTER is as follows:
identifier-1 identifier-2
ENTER FORTRAN program name USING literal-1 , literal-2...
procedure-name-1 procedure-2
The USING clause names the data within the COBOL program that is to be
passed to the called FORTRAN subprogram. The passed data must be in a
form acceptable to FORTRAN (see Table 14-1).
NOTE
G-floating double-precision does not exist as a data
type in COBOL.
The calling sequence used by COBOL in calling a FORTRAN subprogram is:
MOVEI 16, address of first entry in argument list
PUSHJ 17, subprogram address
If the USING clause appears in the ENTER statement, the compiler
creates an argument list that contains an entry for each identifier or
literal in the order of appearance in the USING clause. It is
preceded by a word containing, in its left half, the negative number
of the number of entries in the list. If no USING clause is present,
the argument list contains an empty word, and the preceding word is
set to 0. Each entry in the list is one 36-bit word of the form:
0-8 9-12 13-35
| 0 type Effective address (E)
|
| where:
|
| type is a 4-bit code that indicates the USAGE of the
| argument, and bits 13-35 contain the effective address
| (E) of the first word of the argument.
|
| If the passed argument is a 1-word COMP item, the type code is 2 and E
| is the location of the argument.
|
| If the passed argment is a 2-word COMP item, the type code is 11
| (octal) and E is the location of the first word of the argument; the
| second word of the argument is at E+1.
|
| If the passed argument is a COMP-1 item, the code is 4 and E is the
| location of the argument.
15-20
WRITING USER PROGRAMS
| if the passed argument is a COMP-2 item, the code is 10 (octal) and E
| is the location of the first word of the argument; the second word of
| the argument is at E+1.
|
| If the passed argument is a DISPLAY-6, DISPLAY-7, DISPLAY-9, or COMP-3
| item, the code is 15 (octal) and E is the location of a 2-word
| descriptor for the argument. The first word of the descriptor is a
| byte pointer word pointing to the argument. Its byte-size is 6 for
| DISPLAY-6, 7 for DISPLAY-7, and 9 for DISPLAY-9 or COMP-3.
|
| The second word of the descriptor is of the form:
|
| Bit 0 Reserved
|
| Bit 1-4 Type code:
| 1= DISPLAY-6
| 2= DISPLAY-7
| 3= DISPLAY-9
| 4= COMP-3
|
| Bit 5 Item is a literal
|
| Bit 6 item is a figurative constant (such as SPACES)
|
| Bit 7 Item is numeric
|
| if bit 7 = 0;
|
| Bit 8-11 Reserved
|
| Bit 12-35 Size of item in bytes
|
| If bit 7 = 1;
| Bit 8 Item is signed
|
| Bit 9 Item is scaled (such as PICTURE contains "P's" to
| left of implied decimal point, for example,
| 999PP)
|
| Bit 10 Item is numeric edited
|
| If bit 9 = 0;
|
| Bits 11-25 Reserved
|
| Bits 26-30 Number of decimal places
|
| Bits 31-35 Size of item in bytes
|
| If bit 9 = 1;
|
| Bits 11-25 Reserved
15-21
WRITING USER PROGRAMS
| Bits 26-30 Scale factor (such as, 2 if picture was 999PP)
|
| Bits 31-35 Size of item in bytes (such as, 3 if picture was
| 999PP)
|
The return from a subprogram (through POPJ 17,) is to the statement
after the call.
15.4.7.2 Calling COBOL Subroutines from FORTRAN Programs - To call
COBOL subprograms use the CALL statement:
CALL sub (args...)
where sub is a COBOL subprogram.
|
| NOTE
|
| COBOL 12C subroutines called from FORTRAN programs
| must be compiled with the /R COBOL switch to prevent
| an undefined global error at LINK time.
|
15.4.8 Interaction with BLISS-36
FORTRAN programs can call BLISS-36 routines as subprograms, and,
conversely, BLISS-36 programs can call subprograms written in FORTRAN.
BLISS routines called by FORTRAN programs must be able to coexist
compatibly with FOROTS. For instance, they must use FUNCT. functions
(see Section 18.6) for dynamic memory management within the section
that FOROTS is in, since FOROTS assumes that it has control of that
section.
One problem that the BLISS routines can encounter is stack overflow.
The size of the program stack as set up by FOROTS may be too small for
BLISS routines which have several STACKLOCAL variables. The only
supported way to increase the size of the stack is to use a copy of
FORLIB that has been assembled with a larger stack.
15.4.8.1 Calling FORTRAN Subprograms From BLISS-36 Programs - To call
a FORTRAN subprogram from a BLISS-36 program, the FORTRAN subprogram
must be declared an EXTERNAL ROUTINE in any module that contains a
call to the subprogram. In addition, if the FORTRAN subprogram is a
subroutine, it must be declared with a linkage type of FORTRAN_SUB.
If the FORTRAN subprogram is a function, then it must be declared with
a linkage of FORTRAN_FUNC. For example:
15-22
WRITING USER PROGRAMS
EXTERNAL ROUTINE FOO: FORTRAN_SUB,
BAR: FORTRAN_FUNC;
declares FOO to be the name of a FORTRAN subroutine which will be
called in this module, and declares BAR to be the name of a FORTRAN
function. After the FORTRAN subprogram has been declared
appropriately, it can be called just like any function written in
BLISS.
15.4.8.2 Calling BLISS-36 Routines From FORTRAN - A BLISS-36 routine
that is to be called from a FORTRAN program must have either the
FORTRAN_SUB linkage attribute (if the routine is to be used as a
subroutine) or the FORTRAN_FUNC linkage attribute (if the routine is
to be used as a function).
The programmer that wishes to write a BLISS-36 routine to be called
from FORTRAN must be familiar with the calling sequence used by
FORTRAN to call subprograms (see Section 15.4.2), FORTRAN argument
lists (see Section 15.4.4), and FORTRAN argument descriptors (see
Sections 15.4.5 and 15.4.6). This knowledge is necessary because the
values of the formal arguments of the BLISS-36 routine are the FORTRAN
argument list entries that correspond to actual arguments of the BLISS
routine.
In general, the BLISS routines must be compiled with
ADDRESSING_MODE(INDIRECT), or MACHOP calls must be used to generate
any instruction that references formals since all FORTRAN arguments
must be accessed through indirect addressing. This must be done
because the FORTRAN compiler frequently sets the indirect bit in
argument lists (see Section 15.4.4).
See the BLISS-36 Language Guide for more information.
NOTE
ADDRESSING_MODE(INDIRECT) can have far reaching
effects on your program, which you should understand
fully before using.
15.4.9 LINK Overlay Facilities
LINK provides several routines that are accessible directly from a
FORTRAN program. These routines are presented here briefly, together
with the FORTRAN specification of their parameters. In general, LINK
performs these functions automatically. These routines are available
only for your convenience. Full details of the use of the overlay
facilities can be found in the LINK Reference Manual.
15-23
WRITING USER PROGRAMS
NOTE
Overlays are not allowed when TOPS-20 extended
| addressing is used. In addition, the overlay handler
| does not support programs using long symbols (symbols
| longer than six characters).
The following terms are used to describe the parameters to LINK
overlay routines.
File spec A character expression consisting of
'dev:file.ext[directory]' (TOPS-10), or
'dev:<directory>file.typ.gen' (TOPS-20).
Name A quoted string giving a link name, or an
integer constant or variable giving a link
number.
List of link names A sequence of name items separated by commas.
The routines available are:
CLROVL Specifies a non-writable overlay.
GETOVL(List of link names) Used to change the overlay
structure in core.
INIOVL(File spec) Used to specify the overlay file to
be found if the load time
specification is to be overridden.
LOGOVL(File spec) Used to specify where the log file
is to be written. If no arguments
are given, the log file is closed.
REMOVL(List of link names) Removes the specified links from
core.
RUNOVL(Name) Loads the specified link and
transfers to that LINK.
SAOVL Specifies a writable overlay.
For a full description of these routines, refer to the LINK Reference
Manual.
NOTE
The SAVE statement retains the values stored in a
variable, array, or common block after execution of a
RETURN or END statement in a subprogram. When
15-24
WRITING USER PROGRAMS
overlays are used, the SAVE statement must be used to
ensure retention of values. When the SAVE statement
is used, it is not necessary to specify the LINK
switch /OVERLAY:WRITABLE when loading a program (see
Section 7.10).
15.4.10 FOROTS and Overlay Memory Management
For sharable FOROTS, the FOROTS static data area is several pages
located at the top of FOROTS. FOROTS dynamic memory is allocated at
runtime below FOROTS and in a downward direction (toward the user's
program).
For nonsharable FOROTS (FOROTS loaded from FORLIB), the FOROTS data
area is located in the low segment, so that it will be linked with
variables used by the user's program. FOROTS dynamic memory is
allocated at runtime starting at the page designated by the symbol
STARTP in FORPRM.MAC, downward toward the user program. The
distributed value for this page number is 577. If the user's program
has two segments, FOROTS allocates memory down to the user's high
segment, skips over the high segment, and begins allocating memory
below the user's high segment toward the user's low segment.
For both sharable and nonsharable FOROTS, when FOROTS can no longer
allocate memory downward toward the user's low segment, it allocates
memory starting at the top of memory downward. When FOROTS can no
longer allocate any memory, it reports:
?Memory full
and returns to the monitor after attempting to close all files.
Figure 15-1 illustrates the run-time memory layout.
15-25
WRITING USER PROGRAMS
Figure 15-1: Run-time Memory Layout for Section Zero
FOROTS has a separate memory manager specifically designed for use by
OVRLAY. This memory manager allocates memory at the top of the
users's low segment. In general, user programs that use overlays
should not use the FUNCT. calls GAD, COR, and RAD. OVRLAY expects to
be able to use memory beginning at the top of the user's low segment,
allowing for a special FOROTS scratch space allocated by the /SPACE
switch.
Under certain circumstances, notably when concatenating character
expressions whose length is not known until runtime, FOROTS
15-26
WRITING USER PROGRAMS
dynamically allocates a special scratch area using the FUNCT. COR
function (see Section 18.6). This area is allocated the first time a
dynamic concatenation is performed.
The /SPACE switch to LINK determines the maximum size for such
"dynamic concatenations" if overlays are used. The default value
given by LINK for this value is 4000 (octal). (See the LINK Reference
Manual.)
You can allocate space for dynamic character concatenation using the
ALCCHR subroutine (see Section 13.4.1.1).
15.4.11 Extended Addressing Memory Layout (TOPS-20 only)
The FORTRAN compiler must determine which psect every word of data or
code should reside in. For non-extended addressing compilations, the
data and code reside in either the low segment or the high segment.
For extended addressing compilations, there are three segments
(psects) in which the data and code can be allocated:
1. The code psect corresponds to the non-extended high segment.
The default name is .CODE..
2. The data psect corresponds to the non-extended low segment.
The default name is .DATA..
3. The .LARG. psect is where large data resides. (Note that the
name of this psect cannot be changed.)
A data item can be placed in the .LARG. psect by either of the
following ways:
1. The data item is an array or any character scalar whose size
is greater or equal to the value of the /EXTEND:DATA switch
(default 10,000 words). (See Section 16.5).
2. The data item is placed in a COMMON block or EQUIVALENCE
group that is in the .LARG. psect.
Table 15-2 describes the various memory allocations for extended and
non-extended compilations.
Table 15-2: Memory Allocations for /EXTEND and /NOEXTEND
Item /NOEXTEND /EXTEND
15-27
WRITING USER PROGRAMS
User subprogram Hiseg Code
FORLIB Hiseg .CODE.
Argument blocks Hiseg Code
Compile-time constant Hiseg Code
character descriptors
Array dimension information Hiseg Code
EFIWS N/A Code
Symbol tables (from LINK) Lowseg or Hiseg .DATA. (by default)
FORMAT statements Lowseg Data
Constants Lowseg Data
Small arrays and scalars Lowseg Data
Large arrays Lowseg .LARG.
COMMON variables Lowseg .LARG. (by default)
Variables EQUIVALENCED to Lowseg .LARG.
large arrays
PDV N/A .DATA.
NOTE
When the sharable FOROTS is used, LINK loads the
/NOEXTEND high-segment into the low-segment. This
is done so that the sharable FOROTS can be used as
the high-segment (see Section 16.9)
15.5 USING INDEXED FILES (TOPS-20 ONLY)
| Traditionally, sequential and direct access have been the only file
| access modes available to FORTRAN programs. To overcome some of the
| limitations of these access modes, FORTRAN-20 supports a third
| access mode, called keyed access (see Section 10.2.3). Keyed access
| allows you to retrieve records, at random or in sequence, based on
| key fields that are established when you create a file with indexed
| organization.
|
| You can access files with indexed organization using either
15-28
WRITING USER PROGRAMS
| sequential or keyed access, or a combination of both.
|
| 1. Keyed access retrieves records randomly based on the
| particular key fields and key values that you specify.
|
| 2. Sequential access retrieves records in an ascending
| sequence based on the values within the particular key
| field that you specify.
|
| The combination of keyed and sequential access is commonly referred
| to as the Indexed Sequential Access Method (ISAM). Once you have
| read a record by means of an indexed read request, you can then use
| a sequential read request to retrieve records with ascending key
| field values, beginning with the key field value in the record
| retrieved by the initial read request.
|
| Indexed organization is especially suitable for maintaining complex
| files in which you want to select records based on one of several
| criteria. For example, a mail-order firm could use an indexed
| organization file to store its customer list. Key fields could be a
| unique customer order number, the customer's zip code, and the item
| ordered. Reading sequentially based on the zip code key would
| enable you to produce a mailing list sorted by zip code. A similar
| operation based on customer order number or item number key would
| enable you to list the records in customer order number or item
| number sequence.
|
| The remainder of this section provides information on the following
| topics:
|
| o Creating an indexed file (Section 15.5.1)
|
| o Writing records to an indexed file (Section 15.5.2)
|
| o Reading records from an indexed file (Section 15.5.3)
|
| o Updating records in an indexed file (Section 15.5.4)
|
| o Deleting records from an indexed file (Section 15.5.5)
|
| Information is also provided about the effects of read and write
| operations on positioning your program to records within an indexed
| file (Section 15.5.6) and about how to build logic into your program
| to handle exception conditions that commonly occur (Section 15.5.7).
|
|
|
| 15.5.1 Creating an Indexed File
|
| You can create a file with an indexed organization by using either
| the FORTRAN OPEN statement or the RMSUTL utility.
15-29
WRITING USER PROGRAMS
| o Use the OPEN statement to specify the file options
| supported by FORTRAN.
|
| o Use the RMSUTL utility to select features not directly
| supported by FORTRAN.
|
| When you create an indexed file, you define certain fields within
| each record key fields. One of these key fields, called the primary
| key, is identified as key number zero and must be present in every
| record. Additional keys, called alternate keys, can also be
| defined; they are numbered from 1 through a maximum of 254. An
| indexed file can have as many as 255 key fields defined. In
| practice, however, few applications require more than 3 or 4 key
| fields.
|
| The data types used for key fields must be either INTEGER or
| CHARACTER.
|
| In designing an indexed file, you must decide the byte positions of
| the key fields. For example, in creating an indexed file for use by
| a mail-order firm, you might define a file record to consist of the
| following fields:
|
| INTEGER ORDER_NUMBER ! Positions 1:4, key 0
| CHARACTER*20 NAME ! Positions 5:24
| CHARACTER*20 ADDRESS ! Positions 25:44
| CHARACTER*19 CITY ! Positions 45:63
| CHARACTER*2 STATE ! Positions 64:65
| CHARACTER*9 ZIPCODE ! Positions 66:74, key 1
| INTEGER ITEM_NUMBER ! Positions 75:76, key 2
|
| Given this record definition, you could use the following OPEN
| statement to create an indexed file:
|
| OPEN (UNIT=1,FILE='CUSTOMER.DAT',STATUS='NEW',
| 1 ORGANIZATION='INDEXED',ACCESS='KEYED',
| 2 RECORDTYPE='VARIABLE',FORM='UNFORMATTED',
| 3 RECL=19,
| 4 KEY=(1:4:INTEGER, 66:74:CHARACTER, 75:76:INTEGER),
| 5 IOSTAT=IOS, ERR=9999)
|
| This OPEN statement establishes the attributes of the file,
| including the definition of a primary key and two alternate keys.
| The data type size are determined by the number of character
| positions allotted to the key fields, which in this case are 4 and 2
| character positions, respectively.
|
| If you specify the KEY= specifier (see Section 11.3.21) when opening
| an existing file, the key specification that you give is ignored.
| However, RMS does update the key XAB chain with key information from
| the file. (See Chapter 18 for more information on RMS data
| structures.)
15-30
WRITING USER PROGRAMS
| FORTRAN uses RMS default key attributes when creating an indexed
| file. These default are:
|
| o The values in primary key fields cannot be changed when a
| record is rewritten and cannot have duplicates.
|
| o The values in alternate key fields can be changed and can
| have duplicates.
|
| You can use the RMSUTL utility or a USEROPEN routine to override
| these defaults and to specify other values not supported by
| FORTRAN-20, such as null key field values, null key names, and key
| data types other than integer and character.
|
| See Section 18.9 for information on the use of the USEROPEN
| specifier in OPEN statements. The RMS-20 Programmer's Reference
| Manual has more information on indexed file options. Use of the
| RMSUTL utility is explaind in the TOPS-20 RMS User's Guide.
|
|
|
| 15.5.2 Writing Indexed Files
|
| You can write records to an indexed file with either formatted or
| unformatted indexed WRITE statements (see Section 10.6.3). Each
| write operation inserts a new record into the file and updates the
| key index(es) so that the new record can be retrieved in a
| sequential order based on the values in the respective key fields.
|
| For example, you could add a new record to the file for the
| mail-order firm, described in Section 15.5.1, with the following
| statement:
|
| WRITE (UNIT=1,IOSTAT=IOS,ERR=9999)
|
| The following two sections describe considerations that relate to
| write operations:
|
| o The effect of writing records with duplicate values in key
| fields (Section 15.5.2.1)
|
| o The method by which you can prevent an alternate key field
| in a record from being indexed during a write operation
| (Section 15.5.2.2)
|
|
|
|
| 15.5.2.1 Duplicate Values in Key Fields - It is possible to write
| two or more records with the same value in a single key field. The
| attributes specified for the file when it is created determine
| whether this duplication is allowed. By default, FORTRAN creates
15-31
WRITING USER PROGRAMS
| files that allow duplicate alternate key field values and prohibit
| duplicate primary key field values. If duplicate key field values
| are present in a file, the records with equal values are retrieved
| on a first-in/first-out basis.
|
| For example, assume that five records are written to an indexed file
| in this order (for clarity, only key fields are shown):
|
| ORDER_NUMBER ZIP_CODE ITEM_NUMBER
|
| 1023 70856 375
| 942 02163 2736
| 903 14853 375
| 1348 44901 1047
| 1263 33032 690
|
| If the file is later opened and read sequentially by primary key
| (ORDER_NUMBER), the order in which the records are retrieved is not
| affected by the duplicated value (375) in the ITEM_NUMBER key field.
| In this case, the records would be retrieved in the following order:
|
| ORDER_NUMBER ZIP_CODE ITEM_NUMBER
|
| 903 14853 375
| 942 02163 2736
| 1023 70856 375
| 1263 33032 690
| 1348 44901 1047
|
| However, if the read operation is based on the second alternate key
| (ITEM_NUMBER), the order is which the records are retrieved is
| affected by the duplicate key field value. In this case, the
| records would be retrieved in the following order:
|
| ORDER_NUMBER ZIP_CODE ITEM_NUMBER
|
| 1023 70856 375
| 903 14853 375
| 1263 33032 690
| 1348 44901 1047
| 942 02163 2736
|
| Notice that the records containing the same key field value (375)
| are retrieved in the order in which they were written to the file.
|
|
|
| 15.5.2.2 Preventing the Indexing of Alternate Key Fields - When
| writing to an indexed file that contains variable-length records,
| you can prevent entries from being added to the key indexes for any
| alternate key fields. This is done by omitting the names of the
| alternate key fields from the WRITE statement. The ommitted
15-32
WRITING USER PROGRAMS
| alternate key fields must be at the end of the record; another key
| field cannot be specified after the omitted key field.
|
| For example, assume that the last record (ORDER_NUMBER 1263) in the
| mail-order example is written with the following statement:
|
| WRITE (UNIT=1,IOSTAT=IOS,ERR=9999) ORDER_NUMBER,
| 1 NAME, ADDRESS, CITY,
| 1 STATE, ZIP_CODE
|
| Because the field name ITEM_NUMBER is omitted from the WRITE
| statement, an entry for that key field is not created in the index.
| As a result, an attempt to read the file usng the alternate key
| ITEM_NUMBER would not retrieve the last record and would produce the
| following listing:
|
| ORDER_NUMBER ZIP_CODE ITEM_NUMBER
|
| 1023 70856 375
| 903 14853 375
| 1348 44901 1047
| 942 02163 2736
|
| You can omit only trailing alternate keys from a record; the primary
| key must always be present.
|
|
|
| 15.5.3 Reading Indexed Files
|
| You can read records in an indexed file with either sequential or
| indexed READ statements (formatted or unformatted) under the keyed
| mode of access (see Section 10.5.3). By specifying ACCESS='KEYED'
| in the OPEN statement (see Section 11.3.1), you enable both
| sequential and keyed access to the indexed file.
|
| Indexed READ statements position the file pointers (see Section
| 15.5.6) at a particular record, determined by the key field value,
| the key-of-reference, and the match criterion. Once you retrieve a
| particular record by an indexed READ statement, you can then use
| sequential access READ statements to retrieve records with
| increasing key field values.
|
| The form of the external record's key field must match the form of
| the value you specify in the KEY= specifier (see Section 11.3.21).
| Thus, if the key field contains character data, you should specify
| the KEY= specifier value as a CHARACTER data type. If the key field
| contains binary data, then the KEY= specifier value should be of
| INTEGER data type.
|
| Note that if you write a record to an indexed file with formatted
| I/O, the data type is converted from its internal representation to
15-33
WRITING USER PROGRAMS
| an external representation. As a result, the key value must be
| specified in the external form when you read the data back with an
| indexed read. Otherwise, a match will occur when you do not expect
| it.
|
| The following FORTRAN program segment prints the order number and
| zip code of each record where the first five characters of the zip
| code are greater than or equal to '10000' but less than '50000':
|
| C Read first record with ZIP_CODE key greater than or
| C equal to '10000'.
|
| READ (UNIT=1,KEYGE='10000',KEYID=1,IOSTAT=IOS,ERR=9999)
| 1 ORDER_NUMBER, NAME, ADDRESS,
| 1 CITY,STATE,ZIP_CODE,ITEM_NUMBER
|
| C While the zip code previously read is within range, print
| C the order number and zip code, then the next record.
|
| DO WHILE (ZIP_CODE .LT. '50000')
| PRINT *, "Order number',ORDER_NUMBER, 'has zip code',
| 1 ZIP_CODE
| READ (UNIT=1,IOSTAT=IOS,END=200,ERR=9999)
| 1 ORDER_NUMBER, NAME, ADDRESS
| 1 CITY, STATE, ZIP_CODE, ITEM_NUMBER
|
| C END= branch will be taken if there are no more records
| C in the file.
|
| END DO
| 200 CONTINUE
|
| The error branch on the keyed READ in this example is taken if no
| record is found with a zip code greater that or equal to '10000'; An
| attempt to access a nonexistent record is an error. If the sequential
| READ has accessed all records in the file, however, an end-of-file
| status occurs, just as with other file organizations.
|
| If you wish to detect a failure of the keyed READ, you can examine the
| I/O status variable (IOS) for the appropriate error number (see Table
| D-1 for a list of the returned error codes).
|
|
|
| 15.5.4 Updating Records
|
| The REWRITE statement (see Section 10.14) updates existing records in
| an indexed file. You cannot replace an existing record simply by
| writing it again; a WRITE statement would attempt to add a new record.
|
| An update operation is accomplished in two steps. First, you must
| read the record in order to make it the current record. Next, you
15-34
WRITING USER PROGRAMS
| execute the REWRITE statement. For example, to update the record
| containing ORDER_NUMBER 903 (see prior examples) so that the NAME
| field becomes 'Theodore Zinck', you might use the following FORTRAN
| code segment:
|
| READ (UNIT=1,KEY=903,KEYID=0,IOSTAT=IOS,ERR=9999)
| 1 ORDER_NUMBER, NAME, ADDRESS, CITY, STATE, ZIP_CODE,
| 1 ITEM_NUMBER
| NAME = 'Theodore Zinck'
| REWRITE (UNIT=1,IOSTAT=IOS,ERR=9999)
|
| When you rewrite a record, key fields may change. The attributes
| specified for the file when it was created determines whether this
| type of change is permitted.
|
|
|
| 15.5.5 Deleting Records
|
| To delete records from an indexed file, you use the DELETE statement
| (see Section 10.13). The DELETE and REWRITE statements are similar; a
| record must first be locked by a READ statement before it can be
| operated on.
|
| The following FORTRAN code segment deletes the second record in the
| file with ITEM_NUMBER 375 (see previous examples):
|
| READ (UNIT=1,KEY=375,KEYID=2,IOSTAT=IOS,ERR=9999)
| READ (UNIT=1,IOSTAT=IOS,ERR=9999) (IOLIST)
| IF (ITEM_NUMBER .EQ. 375) THEN
| DELETE (UNIT=1, IOSTAT=IOS, ERR= 9999)
| ELSE
| PRINT *, 'There is no second record,'
| END IF
|
| Deletion removes a record from all defined indexes in the file.
|
|
|
| 15.5.6 Current Record and Next Record Pointers
|
| The RMS file system maintains two pointers into an open indexed file:
| the "next record" pointer and the "current record" pointer.
|
| o The next record pointer indicates the record to be retrieved
| by a sequential read. When you open an indexed file, the
| next record pointer indicates the record with the lowest
| primary key field value. Subsequent sequential read
| operations cause the next record pointer to be the one with
| the next higher value in the same key field. In case of
| duplicate key field values, records are retrieved in the
| order in which they were written.
15-35
WRITING USER PROGRAMS
| o The current record pointer indicates the record most recently
| retrieved by a READ operation; it is the record that is
| locked from access by other programs sharing the file. The
| current record is the one operated on by the REWRITE
| statement and the DELETE statement. The current record is
| undefined until a read operation is performed on the file.
| Any file operation other than a read causes the current
| record pointer to become undefined. Also, an error results
| if a rewrite or delete operation is performed when the
| current record pointer is undefined.
|
|
|
|
| 15.5.7 Exception Conditions
|
| You can expect to encounter certain exception conditions when using
| indexed files. The two most common of these conditions involve valid
| attempts to read locked records and invalid attempts to create
| duplicate keys. Provisions for handling both of these situations
| should be included in a well-written program.
|
| When an indexed file is shared by several users, any read operation
| may result in a "record locked" error. One way to recover from this
| error condition is to ask if the user would like to reattempt the
| read. If the user's response is positive, then the program can go
| back to the READ statement.
|
| You should avoid simply looping back to the READ statement without
| first providing some type of delay (caused by a request to try again,
| or to discontinue). If your program reads a record but does not
| intend to modify the record, you should place an UNLOCK statement (see
| Section 10.15) immediately after the READ statement. This technique
| reduces the time that a record is locked and permits other programs to
| access the record.
|
| The second exception condition, creation of duplicate keys, occurs
| when your program tries to create a record with a key field value that
| is already in use. When duplicate key field values are not desirable,
| you might have your program prompt for a new key field value whenever
| an attempt is make to create a duplicate.
15-36
CHAPTER 16
USING THE FORTRAN COMPILER
This chapter explains how to use the FORTRAN compiler. Section 16.1
describes using the FORTRAN-10 compiler and Section 16.2 describes
using the FORTRAN-20 compiler.
16.1 USING THE FORTRAN-10 COMPILER
This section describes how use the FORTRAN-10 compiler. You should be
familiar with the TOPS-10 operating system. The TOPS-10 Operating
System provides commands that enable you to compile, execute, and
debug FORTRAN programs. These commands are known as the COMPILE-Class
commands.
16.1.1 TOPS-10 COMPILE-Class Commands
You can invoke the FORTRAN-10 compiler by using TOPS-10 COMPILE-Class
commands. These commands enable you to compile, execute, and debug a
program by giving the commands at TOPS-10 command level.
The COMPILE-Class commands are:
COMPILE
LOAD
EXECUTE
DEBUG
Example:
.EXECUTE ROTOR.FOR
The compiler switches OPTIMIZE, CREF, and DEBUG may be specified
directly in COMPILE-Class commands and may be used globally or
locally. (See Section 16.1.3 for a description of FORTRAN-10
switches.)
16-1
USING THE FORTRAN COMPILER
Example:
.EXECUTE/CREF P1.FOR,P2.FOR/DEBUG
The other compiler switches must be passed in parentheses for each
specific source file.
Example:
.EXECUTE P1.FOR(INCLUDE)
Refer to the TOPS-10 Operating System Commands Manual for further
information about the COMPILE-Class commands.
16.1.2 RUNNING THE FORTRAN-10 COMPILER
On TOPS-10, the command to run the FORTRAN compiler directly is:
.R FORTRA
The compiler responds with an asterisk (*), and is then ready to
accept a command string. The form of the FORTRAN compiler command
string is:
object filespec, listing filespec=source filespec(s)
You are given the following options:
1. File specifications consist of an optional device name, a one
to six character filename, an optional one to three character
file extension, and an optional directory path specification.
The path may include SFDs.
2. You may specify more than one source file in the compilation
command string. These files will be logically concatenated
by the compiler and treated as one source file.
3. More than one program unit may be contained in a single
source file.
4. A program unit may consist of more than one source file.
5. If no object file is specified, no relocatable binary file is
generated.
6. If no listing file is specified, no listing is generated.
7. If no extension is given, the defaults are the following for
the respective files:
16-2
USING THE FORTRAN COMPILER
.LST (listing)
.REL (relocatable binary)
.FOR (source)
.CRF (cross reference) if the /CROSSREF switch is
specified (see Section 16.1.3)
16.1.3 TOPS-10 Compiler Command Switches
Switches to the FORTRAN-10 compiler are accepted anywhere in the
command string. They are totally position and file independent.
Table 16-1 lists the switches.
Table 16-1: FORTRAN-10 Compiler Switches
Switch Meaning Defaults
/CROSSREF Generates a file with extension .CRF OFF
that can be input to the CREF program.
/DEBUG Includes debugging information in your NONE
program (see Section 16.3).
/DFLOATING Indicates that double-precision ON
numbers are stored in D-floating
format. (See Section 3.4.)
/EXPAND Includes the octal-formatted version OFF
of the object file in the listing.
/F66 The FORTRAN-66 standard rules apply for OFF
DO loops and EXTERNAL statements. (Same
function as the /NOF77 switch.)
/F77 The FORTRAN-77 standard rules apply for ON
DO loops and EXTERNAL statements.
/FLAG Invokes the compatibility flagger (see OFF
Section 16.6).
/GFLOATING Indicates that double-precision OFF
numbers are stored in G-floating
format. (See Section 3.4.)
16-3
USING THE FORTRAN COMPILER
/INCLUDE Compiles a D in card column 1 as OFF
space.
/LNMAP Produces a line number/octal location OFF
map in the listing only if /MACROCODE
was not specified.
/MACROCODE Adds the mnemonic translation of the OFF
object code to the listing file.
/NOFLAG Indicates that no compatibility ON
flagging will be done (see Section
16.6).
/NOF77 The FORTRAN-66 standard rules apply for OFF
DO loops and EXTERNAL statements. (Same
function as the /F66 switch.)
/NOERRORS Does not print error messages on the OFF
terminal.
/NOWARN Suppresses warning messages (see NONE
Section 16.4).
/OPTIMIZE Performs global optimization. OFF
/SYNTAX Performs syntax check only. OFF
Each switch must be preceded by a slash (/). Switch names need only
contain those letters that are required to make the switch name
unique. You are encouraged to use at least three letters to prevent
conflict with switches in future implementations.
Example:
.R FORTRA
*OFILE,LFILE=SFILE/MAC,S2FILE
The /MAC switch will cause the MACRO code generated for SFILE and
S2FILE to appear in LFILE.LST.
All switches, used or implied, are printed at the top of each listing
page.
16-4
USING THE FORTRAN COMPILER
16.2 USING THE FORTRAN-20 COMPILER
This section describes how to use the FORTRAN-20 compiler. You should
be familiar with the TOPS-20 Operating System. The TOPS-20 Operating
System provides commands that enable you to compile, execute, and
debug FORTRAN program. These commands are known as the COMPILE-Class
commands.
16.2.1 TOPS-20 COMPILE-Class Commands
The TOPS-20 COMPILE-Class commands enable you to initiate compilation,
execution, and debugging of FORTRAN programs from TOPS-20 command
level.
The TOPS-20 COMPILE-Class commands are:
COMPILE
LOAD
EXECUTE
DEBUG
Example:
@EXECUTE ROTOR.FOR
The following FORTRAN compiler switches (see Section 16.2.3) can be
specified directly in a COMPILE-Class command:
/ABORT
/BINARY
/CROSS-REFERENCE
/DEBUG
/LIST
/MACHINE-CODE
/NOWARNINGS
/OPTIMIZE
/WARNINGS
NOTE
When you specify the switches /BINARY, /DEBUG,
/LIST, and /NOWARNINGS directly in a
COMPILE-Class command, the switches cannot have
arguments as they can when running the compiler.
All other switches must be specified by using Language-switches,
as shown in the following example:
@COMPILE TEST.FOR/OPT/LANG:"/NOWARNINGS"
16-5
USING THE FORTRAN COMPILER
Refer to the TOPS-20 Commands Reference Manual for more
information about the COMPILE-Class commands.
NOTE
You cannot use long TOPS-20 filenames with the
COMPILE-Class commands.
16.2.2 RUNNING THE FORTRAN-20 COMPILER
On TOPS-20, the command to run the FORTRAN compiler directly is:
@FORTRA
The compiler responds with the following prompt:
FORTRAN>
and is then ready to accept a command string.
You can use the question mark to list the commands beginning with
a specific letter or letters. Type the letter or letters
followed by a question mark. (Refer to the TOPS-20 User's
Guide.)
You can type commands to the system by using either full input,
recognition input, abbreviated input, or a combination of these
methods.
To give a command using full input, type the complete command
name, arguments, or switches (if any), using a space to separate
the fields.
To give a command using recognition input, type a portion of the
switch or filename and press the ESC key. You must type enough
of the switch or filename to make it unique. Continue typing and
pressing the ESC key until the switch or filename is complete.
Recognition input requires less typing than full input, so you
are less likely to make a mistake. You can use recognition in
typing switches, switches arguments, and file specifications.
When typing file specifications, you can also use CTRL/F to
complete the rest of a partial file specification.
To give a command using abbreviated input, type only enough of
the switch or filename to distinguish one switch or filename from
another. (Refer to the TOPS-20 User's Guide.)
You should enter a command string in one of the following forms:
16-6
USING THE FORTRAN COMPILER
| 1. [COMPILE] <source-file-spec> [switches]
If no switches are specified, the compiler produces a .REL
file, with the same filename as the source file. The user
must use a /LISTING switch to get a listing file (see Section
16.2.3 for a description of FORTRAN-20 compiler switches).
COMPILE is optional if the command begins with a switch or
begins with a file specification that cannot be confused with
the words EXIT, HELP, TAKE, or COMPILE.
|
| 2. [COMPILE] <source-file-spec>+<source-file-spec>+...
| [switches]
The source files are treated as if they were concatenated
together prior to the beginning of compilation.
If no switches are specified, the compiler produces a .REL
file, with the same filename as the last source file in the
list. The user must use a /LISTING switch to get a listing
(see Section 16.2.3 for a description of FORTRAN-20 compiler
switches). COMPILE is optional if the command begins with a
switch or begins with a file specification that cannot be
confused with the words EXIT, HELP, TAKE, or COMPILE.
3. TAKE <file-spec> [/ECHO]
The compiler reads the file specified as the command input
stream. The TAKE command is legal within 'take' files. The
maximum nesting depth is 10 'take' files.
The /ECHO switch optionally causes commands to be displayed
on TTY: as they are executed. The optional /NOECHO switch
can be used on a nested take command to cancel the affect of
the /ECHO switch while processing that nested command file.
4. RUN <file-spec> [/OFFSET:<integer>]
This command runs another program (for example, LINK). It
causes an exit from the FORTRAN compiler and the start of
execution of the program indicated by the file specification,
with the additional option of starting that program at an
OFFSET relative to the normal starting address.
5. HELP
This command prints information on the user's terminal about
how to use the FORTRAN compiler.
6. EXIT
This command exits from FORTRA.
16-7
USING THE FORTRAN COMPILER
You are given the following options:
1. Filename specifications consist of the following:
An optional device name (the default device is DSK:)
An optional directory name
An up to 39 alphanumeric character filename
An optional up to 39 alphanumeric character file type
An optional generation number that identifies the
version of the file
An optional file attribute to specify distinctive
characteristics of a file specification
(Refer to the TOPS-20 User's Guide)
NOTE
LINK is restricted to 6-character filenames and
3-character extensions.
2. You may specify more than one source file in the compilation
command string. These files will be concatenated by the
compiler and treated as one source file. The name of the
last source file is used as the default name of the object
and listing files. If the last source file does not have a
name (such as, TTY:), FORTRAN-OUTPUT is used as the default
filename.
3. More than one program unit may be contained in a single
source file.
4. A program unit may consist of more than one file.
5. If no /LISTING switch is specified (see Section 16.2.3), no
listing is generated.
6. If no extension is given, the defaults are the following for
the respective files:
.LST (listing) if the /CROSSREF switch is not specified
.CRF (cross reference) if the /CROSSREF switch is
specified (see Section 16.2.3)
.REL (relocatable binary)
.FOR (source)
16-8
USING THE FORTRAN COMPILER
16.2.3 TOPS-20 Compiler Commands Switches
Switches to the FORTRAN-20 compiler are accepted anywhere in the
command string. They are totally position and file independent.
Table 16-2 lists the switches.
Table 16-2: FORTRAN-20 Compiler Switches
Switch Meaning Defaults
/ABORT Causes the compiler to exit at the OFF
end of a compilation that contains
errors.
/BINARY[:relfile] Indicates that a relocatable binary ON
file is generated. You can
optionally specify the file
specification.
/CROSS-REFERENCE Generates a file with extension OFF
.CRF that can be input to the
CREF program.
/DEBUG[keys:] Includes debugging information in NONE
your program (see Section 16.3).
/DFLOATING Indicates that double-precision ON
numbers are stored in D-floating
format. (See Section 3.4.)
/ECHO-OPTION Echo switches selected from the OFF
SWITCH.INI file.
/EXPAND Includes the octal-formatted version OFF
of the object file in the listing.
/EXTEND[keys:] Indicates extended addressing. OFF
Programs can have up to 30
sections of code and data (see
Section 16.5).
/F66 The FORTRAN-66 standard rules apply OFF
for DO loops and EXTERNAL state-
ments. (Same function as the /NOF77
switch.)
/F77 The FORTRAN-77 standard rules apply ON
for DO loops and EXTERNAL
statements.
16-9
USING THE FORTRAN COMPILER
/FLAG-NON-STANDARD Invokes the compatibility flagger OFF
(see Section 16.6).
/GFLOATING Indicates that double-precision OFF
numbers are stored in G-floating
format. (See Section 3.4.)
/INCLUDE Compiles a D in card column 1 as OFF
space.
/LISTING[:listfile] Indicates a list file will be OFF
generated. You can optionally
specify the file specification.
/LNMAP Produces a line number/octal OFF
location map in the listing only
if /MACHINE-CODE was not specified.
/MACHINE-CODE Adds the mnemonic translation of OFF
the object code to the listing
file. This command will cause
a default /LISTING.
/NOBINARY Indicates that no relocatable OFF
binary file is generated.
/NOF77 The FORTRAN-66 standard rules apply OFF
for DO loops and EXTERNAL
statements. (Same function as
the /F66 switch.)
/NOFLAG-NON-STANDARD Indicates that no compatibility ON
flagging will be done (see Section
16.6).
/NOERRORS Does not print error messages OFF
on the terminal.
/NOEXTEND Indicates extended addressing ON
is not in effect (see Section 16.5).
/NOWARN Suppresses warning messages (see NONE
Section 16.4).
16-10
USING THE FORTRAN COMPILER
Table 16-2: FORTRAN-20 Compiler Switches (Cont.)
Switch Meaning Defaults
/OPTIMIZE Performs global optimization. OFF
/OPTION[:option] Only read lines from the SWITCH.INI OFF
file that start with FORTRA:option.
/SYNTAX Performs syntax check only. OFF
Each switch must be preceded by a slash (/). Switch names need only
contain those letters that are required to make the switch name
unique. You are encouraged to use at least three letters to prevent
conflict with switches in future implementations.
NOTE
When using switches in control files, you are
encouraged to type the full name of the switch.
Example:
@FORTRA
FORTRAN>SFILE+S2FILE/MAC/LIST:LFILE
The /MAC switch will cause the MACRO code generated for SFILE and
S2FILE to appear in LFILE.LST. An relocatable binary file will be
created with the name S2FILE.REL.
All switches, used or implied, are printed at the top of each listing
page.
16.3 THE /DEBUG SWITCH
The /DEBUG switch tells FORTRAN to compile a series of debugging
features into your program. Several of these features are
specifically designed to be used with the FORTRAN debugging program
(FORDDT). Refer to Chapter 17 for more information. By using the
DEBUG switch arguments listed in Table 16-3, you can include specific
debugging features.
The form of the /DEBUG switch is:
/DEBUG:arg
or
16-11
USING THE FORTRAN COMPILER
/DEBUG:(arg1,arg2,...)
Table 16-3: Arguments to /DEBUG Switch
Arguments Meaning
DIMENSIONS Includes dimension information in .REL file for
FORDDT.
TRACE Generates references to FORDDT required for its
trace features (automatically activates LABELS).
LABELS Generates a label for each statement of the form
<line-number>L. (This option can be used without
FORDDT.)
INDEX Forces DO LOOP indexes to be stored at the
beginning of each iteration rather than held in a
register for the duration of the loop.
In addition, this switch forces all function
values to be stored in memory prior to return from
the function. If this switch is specified, you
can set a FORDDT pause on the RETURN statement
(see Section 13.4.4) and then examine the value to
be returned.
BOUNDS Generates the bounds checking code for all array
references and substring references. Bounds
violations will produce run-time error messages.
Note that the technique of specifying dimensions
of 1 for subroutine arrays will cause bounds check
errors. (You may use this option without FORDDT.)
ARGUMENTS Generates type checking information at load time
for actual argument types and associated dummy
argument types. Type violations will produce
non-fatal load-time error messages. This switch
also performs type checking at compile-time for
statement functions.
NONE Do not include any debug features.
ALL Enable all debugging aids.
16-12
USING THE FORTRAN COMPILER
| NOTE
|
| If the /DEBUG switch is specified without arguments,
| then the defaults are used for all the arguments. The
| /DEBUG switch used without arguments is the same as
| /DEBUG:(ARGUMENTS,BOUNDS,DIMENSIONS,INDEX,LABELS,
| TRACE).
|
| You can invoke a single aspect of debugging without
| affecting the other features controlled by the switch.
| For example, specifying /DEBUG:ARGUMENTS does not
| cause BOUNDS checking to also be invoked. However,
| you can change multiple features of the /DEBUG switch
| in the same command line. For example,
| /DEBUG:ARGUMENTS /DEBUG:BOUNDS would invoke both
| argument checking and bounds checking.
Options available with the /DEBUG arguments are:
1. No debug features - Either do not specify the /DEBUG switch
or include /DEBUG:NONE.
2. All debug features - Either /DEBUG or /DEBUG:ALL.
3. Selected features - Either a series of modified switches,
that is:
/DEBUG:BOU/DEBUG:LAB
or a list of modifiers
/DEBUG:(BOU,LAB,...)
4. Exclusion of features - If you wish all but one or two
modifiers and do not wish to list them all, you can use the
prefix "NO" before the switch you wish to exclude. The
exclusion of one or more features implicitly includes all the
others, that is, /DEBUG:NOBOU is the same as
/DEBUG:(DIM,TRA,LAB,IND,ARG).
If you include more than one statement on a single line, only the
first statement will receive a label (/DEBUG:LABELS) or FORDDT
reference (/DEBUG:TRACE).
NOTE
If a source file contains line sequence numbers that
occur more than once in the same subprogram, the
/DEBUG option cannot be used. Also, the /DEBUG option
and the /OPTIMIZE option cannot be used at the same
time.
16-13
USING THE FORTRAN COMPILER
The following formulas may be used to determine the increases in
program size that will occur as a result of the addition of various
/DEBUG options.
DIMENSIONS For each array, 3+3*N words where N is the number
of dimensions, and up to three constants for each
dimension.
TRACE One instruction per executable statement.
LABELS No increase.
INDEX One instruction per inner loop plus one
instruction for some of the references to the
index of the loop. Also one instruction per
subprogram.
BOUNDS For each array, the formula is the same as
DIMENSIONS.
For each reference to an array element, 5+N words
additional words are generated, where N is the
number of dimensions in the array. If you do not
specify BOUNDS, approximately 1+3*(N-1) words will
be used. For each reference to a substring, add 5
words.
ARGUMENTS No increase.
If the /DEBUG:ARGUMENTS switch argument is specified, type checking is
performed at LINK time for calls to external programs and at compile
time for calls to statement functions. Non-fatal error messages are
issued at LINK time for the following cases:
1. If the number of arguments in the called subprogram and the
calling program unit are not equal.
2. If the length of an array or character scalar actual argument
is less than that of the corresponding dummy argument. (This
is checked only if the length of the actual is known at
compile time.)
3. If the associations of actual argument data types with dummy
argument data types are other than those indicated as legal
in Table 16-4.
4. If a non-routine name is passed where a routine name is
expected, or a routine name is passed where a non-routine
name is expected.
Non-fatal error messages are issued at compile time for the following
cases (only for statement functions):
16-14
USING THE FORTRAN COMPILER
1. If a non-routine name is passed where a routine name is
expected, or a routine name is passed where a non-routine
name is expected.
2. If the length of the actual character expression being passed
to a statement function is less than that of the
corresponding character expression dummy argument.
Table 16-4: Legal Dummy and Actual Argument Associations
16.4 THE /NOWARN SWITCH
The /NOWARN switch is used to suppress compiler warning messages. If
this switch is used with no arguments, all warning messages are
suppressed. The /NOWARN switch may also be used with arguments as
shown in Table 16-5.
Table 16-5: Arguments to /NOWARN Switch
Arguments Meaning
ALL Suppress all warning messages.
NONE Do not suppress warning messages.
xxx Where xxx is the three character error mnemonic
16-15
USING THE FORTRAN COMPILER
for the error message to be suppressed. This is
the three letters that follow %FTN, for example
%FTNABD.
For example,
/NOWARN:LID
will suppress all warnings of an identifier having more than six
characters.
A list of arguments is also allowed. For example,
/NOWARN:(LID,DIM)
would suppress both LID and DIM types of warning messages.
(See Appendix C for a list of all compiler error mnemonics.)
16.5 THE /EXTEND SWITCH (TOPS-20 ONLY)
Support for extended addressing is almost completely transparent; a
program compiled with the /EXTEND switch will use extended addressing
without requiring changes to the FORTRAN source program.
When /EXTEND is specified, arrays and COMMON blocks can extend across
multiple sections. Executable code can also reside in multiple
sections, with the restriction that a single subprogram must not cross
a section boundary.
The /EXTEND switch can be specified without arguments to use the
default extended address space layout. This is suitable for most
applications in which the executable code fits within a single
section, but which may employ data structures that require more than a
section of memory. When such an application is compiled /EXTEND
without further arguments, a default memory layout is used that
depends on the default size settings for arrays and strings:
Table 16-6: /EXTEND Default Memory Layout
Section Pages Contents
1 0-477 Executable code
Argument blocks
Literals
Non-COMMON scalars
Non-COMMON arrays smaller than
16-16
USING THE FORTRAN COMPILER
10,000 words
Non-COMMON strings smaller than
10,000 words
1 500-577 FOROTS
1 600-777 Reserved
2-31 0-777 COMMON blocks
Arrays larger than 10,000 words
Strings larger than 10,000 words
Additional arguments to /EXTEND (COMMON:, DATA:, PSECT:, and CODE), in
conjunction with the /SET switch to LINK, can be supplied to override
these defaults and direct specific placement of COMMON blocks,
non-COMMON arrays and scalars, and executable code. For example, a
decimal argument can be specified for the DATA: keyword, which
overrides the 10,000 word default minimum size for large arrays and
character scalars. /EXTEND:COMMON can be used to direct specific
named COMMON blocks to non-default sections of extended memory.
(Section 16.5.3 describes the /EXTEND arguments.)
|
| NOTE
|
| If the /EXTEND switch is specified without arguments,
| then the defaults are used for all the arguments. The
| /EXTEND switch used without arguments is the same as
| /EXTEND:(DATA:10000,COMMON,NOCODE,PSECT:.DATA.:.CODE.)
| (See Section 16.5.3.)
|
| You can invoke a single aspect of extended addressing
| without affecting the other features controlled by the
| switch. For example, specifying /EXTEND:DATA does not
| cause COMMON blocks to be placed into the large psect,
| which is done with the /EXTEND:COMMON argument.
| However, you can change multiple features of the
| /EXTEND switch in the same command line. For example,
| /EXTEND:CODE:100/EXTEND:COMMON would place all
| non-common data items not less than 100 words long and
| all COMMON blocks into the large psect.
16.5.1 /EXTEND and Applications with Large Arrays
The simplest usage of extended addressing is for applications in which
the executable code fits in one section. These applications may have
very large arrays or common blocks. In many cases, these applications
can be compiled with the /EXTEND switch with no arguments, using the
default memory layout in Table 16-6.
16-17
USING THE FORTRAN COMPILER
In some cases, you may need to use the DATA or COMMON arguments to
/EXTEND to redirect the placement of variables in areas when default
placements cannot be used. Specifying a smaller /EXTEND:DATA size may
be necessary if the total size of non-COMMON scalars and arrays causes
them to overlap FOROTS pages. If such overlap occurs, program
execution will terminate with the error messages:
| "?Can't get FORO11.EXE"
and
"?Can't overlay existing pages"
A smaller DATA size will force these data structures into a non-FOROTS
section.
16.5.2 /EXTEND and Applications with Large Executable Code
A more complex use of extended addressing is one where the
application's executable code is larger than a section. In order to
build an application that has more than one section of executable
code, you have to specify which program units will be linked together
in each section.
When /EXTEND is specified, the extended code will be in three PSECTS,
one analogous to the present hiseg, one analogous to the present
lowseg, and one containing the large variables. If the user does not
specify the extended addressing switch, FORTRAN will generate a TWOSEG
REL file as it always has. The three PSECTS generated under /EXTEND
are:
1. The "large data area" psect (.LARG.) has a maximum size of 30
sections. It will consist of user-specified COMMON blocks,
arrays and character scalars that are larger than a
user-specified size (or default).
There is no restriction on the size of an individual array or
COMMON block, beyond the restriction on the total size of the
large data area.
2. The "small data area" psect (default name .DATA.) of a
program consists of user-specified COMMON blocks, and scalars
and arrays that are smaller than a user-specified size (or
default). If FORDDT is used, it will reside in the .DATA.
psect.
3. The "executable code and sharable data area" psect (default
name .CODE.) of a program consists of all executable code,
argument blocks and literals. Library functions and
16-18
USING THE FORTRAN COMPILER
subroutines used by the program are placed in the .CODE.
psect. This does not include space used by SORT, which
occupies its own section.
For each "executable code area" (code psect) there will be a
corresponding "small data area" (data psect). The combined size of
these two areas must not exceed 256K words. The default psect names
.DATA. and .CODE. can be changed at compile time by the /EXTEND:PSECT
command switch (see Section 16.5.3).
16.5.2.1 /EXTEND PSECT Placement - The three psects will be set up
according to the table below:
Psect Default Attributes
Origin
data 1001000 Single section, Non-zero section,
Concatenated, Writable
code 1300000 Single section, Non-zero section,
Concatenated, Read-only
.LARG. 2000000 Non-zero section, Concatenated, Writable
You can alter the default psect origins when loading programs by
giving a /SET switch to LINK (see the LINK Reference Manual). This
may be necessary if a program has too much code or local data to fit
in the regions allocated for them by the default psect origins. This
would cause the psects to overlap, and would be indicated by a LINK
warning message (%LNKPOV). Altering the defaults is also useful if
the user wants to reserve one or more sections for some purpose (such
as telling the monitor where dynamic libraries should be loaded).
The first page (locations 000-777) of any section that contains code
is reserved for use by FORDDT. The LINK /SET switch should not
specify a psect origin less than 1000 for any such section.
16.5.2.2 Building Large-Code Applications - When compiling large-code
applications, the following considerations apply:
1. The code and small data psects for a single program unit must
always reside together in the same section, since the PC will
not advance across section boundaries, and the small data
area is assumed to be in the same section.
2. You will need to use the /EXTEND:CODE keyword. This
specifies that the object code emitted by the compiler
assumes that all subprograms that it calls may be in a
separate section.
16-19
USING THE FORTRAN COMPILER
3. You must also use the PSECT argument to /EXTEND to specify
the psect names for code and small data. If you wish to link
the program units in several different compilations (source
files) together in the same section, you should use the same
psect names for those program units.
At link-time, you must specify the starting address for each psect
using the /SET switch, according to the following rules:
1. The code and small data psects for a program unit must be
linked in the same section with each other.
2. If a section contains any executable code, page 0 of that
section is reserved for FORDDT and FOROTS.
3. You must always allocate space for the .CODE. and .DATA.
psects, since FORLIB routines will be linked in these psects.
4. Pages 500-577 of the section that contains .CODE. and .DATA.
are reserved for FOROTS.
5. Pages 600-777 are reserved for FOROTS I/O buffers and DDT.
6. You must always allocate space for the .LARG. psect.
16.5.3 Arguments to /EXTEND
By using the /EXTEND switch arguments listed in Table 16-7, you can
include specific extended addressing features.
The form of the /EXTEND switch is:
/EXTEND:arg
or
/EXTEND:(arg1,arg2,...)
Table 16-7: Arguments to /EXTEND Switch
Arguments Meaning
CODE Specifies that the object code produced by the
compiler has to assume that any subprogram that
it calls could be in a separate section. NOCODE
is the default.
16-20
USING THE FORTRAN COMPILER
COMMON[:name] Without a common block name specified, causes
or all common blocks that have not already been
COMMON:(name,...) allocated by /EXTEND:[NO]COMMON to be allocated
in the .LARG. psect. This is the default.
Individual common blocks can be placed
explicitly in .LARG. by putting their names in a
list after COMMON:. When you explicitly place
an individual common block in .LARG., any common
blocks that have not already been allocated by
/EXTEND:[NO]COMMON are placed in the small data
psect.
DATA[:decimal number] Specifies a decimal argument that is the minimum
size (in words) for non-common arrays and
character scalars, which will be allocated to
the .LARG. psect. The default is 10,000.
NOCODE Allows the compiler to assume that all of the
code will be in the same section. A program
compiled with the NOCODE argument cannot call
any subprograms compiled with the CODE argument.
This is the default.
NOCOMMON[:name] Without a common block name specified, causes
or all common blocks to be allocated in the data
NOCOMMON:(name,...) psect. Individual common blocks can be placed
explicitly in the data psect by putting their
names in a list after COMMON:. COMMON is the
default.
NODATA Specifies that all non-common variables will
reside in .DATA. This is equivalent to
DATA:1073741823, which excludes all variables
from .LARG.
PSECT[:[data psect] Allows users to set the code and data psect
[:[code psect]]] names explicitly (the large data psect is always
called .LARG.) If PSECT is specified with one
argument, that argument becomes the name of the
small data area psect. Any second argument
becomes the name of the code psect. This allows
separate program units to be put in separate
psects, then the psect can be placed in
different sections with the /SET switch at LINK
time (see the LINK Reference Manual).
NOTE
When using the PSECT argument, the small data psect
and code psect for any given program unit must be
loaded into the same memory section.
16-21
USING THE FORTRAN COMPILER
16.5.4 Linking With TWOSEG REL Files
If a main program unit compiled with /EXTEND is linked with subprogram
units (FORTRAN or not) that were compiled for non-extended use, then
LINK will automatically place the LOWSEG of non-extended units in the
.DATA. psect, and the HISEG of such units into the .CODE. psect.
A program compiled with /EXTEND can call a subprogram that is not
compiled with /EXTEND; however, it is illegal for a subprogram that is
not compiled with /EXTEND to call a subprogram that is.
Programs that were compiled by old versions of FORTRAN-10/20 (prior to
Version 7) will not work if loaded in a non-zero section.
Most MACRO routines written for non-extended use will require
conversion to run in non-zero sections. Data structures accessed with
18-bit address fields, indexed and indirect words, stack pointers and
some monitor calls may need modification to perform correctly in
extended sections. See the TOPS-20 Monitor Call User's Guide for more
information concerning extended MACRO programs.
16.6 THE /FLAG (/FLAG-NON-STANDARD) SWITCH
The /FLAG switch invokes the compatibility flagger.
NOTE
For TOPS-20 systems, the full switch names are
/FLAG-NON-STANDARD and /NOFLAG-NON-STANDARD; however
/FLAG and /NOFLAG work.
This feature provides warning messages for language elements used that
are the following:
o Extensions to the ANSI FORTRAN-77 standard
o Features not found in VAX FORTRAN
o Features that could cause logically different results when
used on the VAX FORTRAN system
NOTE
| VAX FORTRAN is used on the VAX/VMS and ULTRIX
| operating systems.
This allows the flagging of any element that could cause conversion
problems for programs written on the TOPS-10/20 system that might be
compiled and executed on a VAX/VMS system or an ANSI-compatible
16-22
USING THE FORTRAN COMPILER
system. This includes problems that could occur at object time, as
well as compilation incompatibilities.
By using the FLAG switch arguments listed in Table 16-8, you can
specify which features to flag.
The form of the /FLAG switch is:
/FLAG[:arg]
or
/FLAG[:(arg1,arg2,...)]
Table 16-8: Arguments to /FLAG Switch
Arguments Meaning
ALL Gives warning messages for language elements
incompatible with both FORTRAN-77 and VAX FORTRAN.
ANSI Gives warning messages whenever a language element is
an extension to the FORTRAN-77 standard.
NOANSI Does not flag FORTRAN-77 extensions.
NONE Does not flag.
NOVMS Does not flag VAX incompatibilities.
VMS Gives warning messages whenever a language element is
incompatible with VAX FORTRAN.
If no /FLAG switch is specified, no flagging is done. If no arguments
are given with the /FLAG switch, then flagging is done for both
FORTRAN-77 and VAX incompatibilities.
The /NOFLAG switch indicates that no flagging will be done.
16.7 READING A FORTRAN COMPILER LISTING
When you request a listing from the FORTRAN compiler, it may contain
the following information, depending on the switches used at
compilation time:
1. A printout of the source program plus an internal sequence
number assigned to each line by the compiler. This internal
sequence number is referenced in any error or warning
16-23
USING THE FORTRAN COMPILER
messages generated during the compilation. If the input file
is line-sequenced, the number from the file is used. If code
is added by means of the INCLUDE statement, all INCLUDEd
lines will have an asterisk (*) appended to their
line-sequence number.
2. A summary of the names and relative program locations (in
octal) of scalars and arrays (including unreferenced
character scalars and arrays) in the source program plus
compiler-generated variables.
3. All COMMON blocks and the relative locations (in octal) of
the variables in each COMMON block.
4. A listing of all equivalenced variables or arrays and their
relative locations. Note that all equivalenced variables
that are also in COMMON are listed only as being in COMMON.
5. A listing of the subprograms referenced (both user-defined
and FORTRAN-defined library functions).
6. A summary of temporary locations generated by the compiler.
7. A heading on each page of the listing containing the program
unit name (MAIN., .BLOCK, program, subroutine or function,
principal entry), the input filename, the list of compiler
switches, and the date and time of compilation.
8. If you used the /MACRO switch, a mnemonic printout of the
generated code (in a format similar to MACRO) is appended to
the listing. This section has four fields:
LINE: This column contains the internal sequence number
of the line corresponding to the mnemonic code. It
appears on the first line of the code sequence
associated with that internal sequence number. An
asterisk indicates a compiler inserted line.
LOC: The relative location in the object program of the
instruction.
LABEL: Any program or compiler generated label.
Program labels have the letter "P" appended. Labels
generated by the compiler are followed by the letter
"M". Labels generated by the compiler and associated
with the /DEBUG:LABELS switch consist of the internal
sequence number followed by an "L".
GENERATED CODE: The MACRO mnemonic code.
If you use the /LNMAP switch and do NOT use the /MACRO
switch, a line number/octal location map is appended to the
listing. This section lists the line numbers in increments
16-24
USING THE FORTRAN COMPILER
of 10 on subsequent lines and each number from 0 through 9
for each line in adjacent columns. The numbers appearing
inside the matrix are the relative octal locations of the
statements in the FORTRAN program unit.
For example, to find the relative octal location of line
number 001043, find the row marked 001040 and then column 3
on that line. The number in that place is the desired
relative location. This listing can be very large and sparse
for line-numbered files with large increments, such as those
produced by the editor SOS on TOPS-10 (or the editor EDIT on
TOPS-20).
NOTE
A single FORTRAN line can produce multiple
machine instructions. In this case the line
number map lists only the first location.
9. A list of all argument blocks generated by the compiler. A
zero argument appears first followed by argument blocks for
subroutine calls and function references (in order of their
appearance in the program). Argument blocks for all I/O
operations follow this.
10. FORMAT statement listings.
11. A summary of errors detected or warning messages issued
during compilations.
16.7.1 Compiler-Generated Variables
In certain situations the compiler generates internal variables.
Knowing what these variables represent can help you read the macro
expansion. The variables are of the form:
.letter digit digit digit digit
The function of these variables can be determined by the first letter
of the variable name as described below:
Letter Function of Variable
A Register save area.
D Compile-time constant character descriptor
F Arithmetic statement function formal parameters.
I Result of a DO LOOP initial value expression or
parameter of an adjustable dimensioned array.
16-25
USING THE FORTRAN COMPILER
O Result of a common subexpression or constant
computation.
Q Temporary storage for expression values.
R Result of reduced operator strength expression.
S Result of the DO LOOP step size expression of computed
iteration count for a loop.
For example:
.S0001
You may find these variables on the listing under SCALARS and ARRAYS.
The following examples show listings where all of these features are
pointed out.
16-26
USING THE FORTRAN COMPILER
16-27
USING THE FORTRAN COMPILER
16-28
USING THE FORTRAN COMPILER
16-29
USING THE FORTRAN COMPILER
16-30
USING THE FORTRAN COMPILER
16-31
USING THE FORTRAN COMPILER
16-32
USING THE FORTRAN COMPILER
NOTE
Note that in the scalars and arrays list, 'NO EXPLICIT
DEFINITION' indicates that the variable was never
explicitly defined, as in a TYPE or DIMENSION
statement. Also, 'NOT REFERENCED' indicates that the
variable was declared, but never used, and therefore
was never allocated any storage in the program.
Character variables that are declared, but not
referenced, appear under the scalars and arrays
section of the listing. No storage is allocated for
16-33
USING THE FORTRAN COMPILER
either the character descriptor or the character data.
16.8 ERROR REPORTING
If an error occurs during the initial pass of the compiler (while the
actual source code is being read and processed), an error message is
printed on the listing immediately following the line in which the
error occurred. When pertinent and possible, the error references the
internal sequence number of the incorrect line. The error messages
along with the statement in error are output to the user terminal.
Example:
TYPE DAY.FOR
01000 I=10
01100 IMPLICIT INTEGER (X)
01200 J=I**4
01300 K1
01400 X=I+J+K1
01500 100 CONTNUE
01600 C
01700 TYPE 200,X
01800 200 FORMAT(1X,I8)
01900 END
COMPILE DAY.FOR
FORTRAN:DAY
01100 IMPLICIT INTEGER (X)
%FTNSOD LINE:01100 IMPLICIT statement out of order
01300 K1
?FTNNRC LINE:01300 Statement not recognized
01500 100 CONTNUE
?FTNMSP LINE:01500 Statement name misspelled
01600 ?
?FTNICL LINE:01600 Illegal character C in label field
?FTNFTL MAIN. 3 fatal errors and 1 warning
If errors are detected after the initial pass of the compiler, they
appear in the list file after the end of the source listing. They are
output to your terminal without the statement in error, but they may
reference its internal sequence number.
16.8.1 Fatal Errors and Warning Messages
There are two levels of messages, warning and fatal error. Warning
messages are preceded by "%" and indicate a possible problem. The
16-34
USING THE FORTRAN COMPILER
compilation will continue, and the object program may be correct.
Fatal errors are preceded by a "?". If a fatal error is encountered
in any pass of the compiler, the remaining passes will not be called,
and no relocatable binary file will be generated.
Additional errors that would be detected in later compiler passes may
not become apparent until the first errors are corrected. It is not
possible to generate a correct object program for a source program
containing a fatal error.
The format of messages is:
?FTNxxx Line:n text
or
%FTNxxx Line:n text
where:
? indicates a fatal message
% indicates a warning message
FTN is the FORTRAN mnemonic
xxx is the 3-letter mnemonic for the error message
Line:n is the optional line number where error occurred
text is the explanation of error
The printing of fatal errors and warning messages on your terminal can
be suppressed by the use of the /NOERRORS switch; however, messages
will still appear on the listing. The /NOWARN switch will suppress
warning messages on both the user terminal and in the listing.
Specific warnings can be suppressed by using options to the /NOWARN
switch (see Section 16.4).
16.8.2 Message Summary
At the end of the listing file and on the terminal, a message summary
is printed after each program unit is compiled. This message has two
forms:
1. When one or more messages were issued
?FTNFTL name 1 fatal error and no warnings
name 2 fatal errors and no warnings
%FTNWRN name no fatal errors and 1 warning
name no fatal errors and 2 warnings
or
2. When no messages were issued
16-35
USING THE FORTRAN COMPILER
name [No errors detected]
where name is the program or subprogram name. Appendix C contains a
complete list of fatal errors and warning messages.
16.9 CREATING A SHARABLE HIGH SEGMENT FOR A FORTRAN PROGRAM
For non-extended addressing programs, the FORTRAN compiler always
generates two segment code for a program unit. However, by default,
| LINK loads all FORTRAN code into the low segment to allow the sharable
run-time system to be bound to the program at run-time rather than at
load-time.
| This default action of LINK can be overridden by using the LINK switch
| /OTSEGMENT:NONSHARABLE when loading the program. If this switch is
| given, LINK loads the impure code (the data areas) in the low segment,
loads the pure code (the machine instructions) in the high segment,
and binds a private copy of the run-time system to the program at
load-time.
| On TOPS-10, a program loaded with the /OTSEGMENT:NONSHARABLE switch
| can be saved to produce an executable file with a sharable high
| segment using the TOPS-10 SSAVE command or the TOPS-20 EXEC SAVE
| command. (The LINK switch /SSAVE can also be used to produce the
sharable executable file.) This is an advantage if a large application
program is to be run by several users simultaneously. Both the code
unique to the program and the copy of the FORTRAN run-time system that
is private to the program are shared between all the program's users.
| On TOPS-20, all pure and impure pages of all programs begin as
| sharable pages, however, as impure pages are modified by stores,
| TOPS-20 creates non-sharable copies of the pages. The default action
| of LINK in programs that do not use extended addressing is to load all
| FORTRAN code into the low segment. This results in the impure and
| pure code of each program unit being loaded as one contiguous unit.
|
| Since the presence of impure code on a page will ultimately result in
| the page becoming non-sharable, the effective number of pages that are
| sharable in the program is less that the maximum that could be
| achieved. However, if the /OTSEGMENT:NONSHARABLE switch is used, all
| of the pure code of the program is loaded with a private copy of
| FOROTS into the high segment. Since the pure code in this case is not
| mixed with the impure code, a greater number of pages remain sharable
| in the program (also, the number of page faults may be reduced).
|
| Note that extended addressing programs on TOPS-20 by default have
| impure code and pure code loaded into disjoint areas so that
| /OTSEGMENT:NONSHARABLE does not increase the sharability or decrease
| the number of page faults of these programs. In addition, these
| programs use the system-wide sharable FOROTS, and thus make the best
| use of system resources.
16-36
USING THE FORTRAN COMPILER
| On both TOPS-10 and TOPS-20, the possible benefits gained by the users
of the application program sharing the high segment of their program
containing both user and FOROTS code must be weighed against the loss
of not sharing the common copy of FOROTS with all other users.
| (See the LINK Reference Manual for more information on the /OTSEGMENT
| switch.)
16-37
17-1
CHAPTER 17
USING THE FORTRAN INTERACTIVE DEBUGGER (FORDDT)
FORDDT is an interactive program used to debug FORTRAN programs and
control their execution. By using the symbols created by the FORTRAN
compiler, FORDDT allows you to examine and modify the data and FORMAT
statements in your program, set breakpoints at any executable
statement or routine, trace your program statement-by-statement, and
make use of many other debugging techniques described in this chapter.
Table 17-1 lists all the commands available to the user of FORDDT.
Table 17-1: FORDDT Commands
Command Purpose
Control Commands
CONTINUE Continues execution after a FORDDT
breakpoint.
DDT Enters DDT.
GOTO Transfers control to some program statement
within the open program unit.
NEXT Traces execution of the program.
START Begins execution of the FORTRAN program.
STOP Terminates the program and returns to
monitor mode.
Data Access Commands
ACCEPT Modifies variables or FORMAT statements.
17-1
USING THE FORTRAN INTERACTIVE DEBUGGER (FORDDT)
TYPE Displays variables. Declarative Commands
CHARACTER Defines dimensions of character arrays for
FORDDT references. (This command is
unnecessary if /DEBUG is specified at
compile time. See Table 16-3.)
DIMENSION Defines dimensions of real and integer
arrays for FORDDT references. (This
command is unnecessary if /DEBUG is
specified at compile time. See Table
16-3.)
DOUBLE Defines dimensions of double-precision and
complex arrays for FORDDT references.
(This command is unnecessary if /DEBUG is
specified at compile time. See Table
16-3.)
GROUP Defines indirect lists for TYPE statements.
MODE Specifies format of typeout.
OPEN Accesses program unit symbol table.
PAUSE Sets FORDDT breakpoints.
PAUSE ON ERROR Sets FORDDT breakpoints (for errors such as
arithmetic overflows).
REMOVE Clears FORDDT breakpoints.
REMOVE ON ERROR Clears PAUSE ON ERROR breakpoints.
Other Commands
LOCATE Lists program unit names in which a given
symbol is defined.
STRACE Displays routine traceback of current
program status.
WHAT Displays current DIMENSION, GROUP, and
FORDDT breakpoint information.
The FORDDT commands are described in detail in Section 17.5.
17.1 INPUT FORMAT
FORDDT commands consist of alphabetic FORTRAN-like identifiers and
17-2
USING THE FORTRAN INTERACTIVE DEBUGGER (FORDDT)
need consist of only those characters required to make the command
unique. If you wish to specify parameters, a space is required
following the command name. Comments may be appended to command lines
by preceding the comment with an exclamation point (!).
17.1.1 Variables and Arrays
FORDDT allows you to access and modify the data in your program using
standard FORTRAN symbolic names. Variables are specified simply by
name. For example:
name
where:
name is a variable name.
Array elements are specified in the following formats:
name
name (s1,...,sn)
where:
name is the name of the array
(s1,...,sn) are the subscripts of a particular array. The
subscripts must be integer constants or variables.
You may reference an entire array simply by typing the array name
(without subscripts). You may specify a range of array elements by
typing the first and last element in the chosen range, separated by a
dash (-).
The following examples show the various ways of specifying variables
and arrays to FORDDT:
ALPHA
ALPHA(7)
ALPHA(PI)
ALPHA(2)-ALPHA(5)
17.1.2 Constant Conventions
FORDDT accepts optionally signed numeric data in the standard FORTRAN
input formats:
17-3
USING THE FORTRAN INTERACTIVE DEBUGGER (FORDDT)
1. INTEGER - A string of decimal digits.
2. REAL - A string of decimal digits optionally including a
decimal point. Standard engineering and double-precision
exponent formats are also accepted.
3. OCTAL - A string of octal digits optionally preceded by a
double quote (").
4. COMPLEX - An ordered pair of integer or real constants
separated by a comma and enclosed in parentheses.
5. LOGICAL - A Boolean argument, either .TRUE. or .FALSE.
6. CHARACTER - A string of printable ASCII characters enclosed
by apostrophes.
7. HOLLERITH - A string of alphanumeric and/or special
characters delimited by any alphanumeric or special
character, excluding the space character, which does not
occur with the string itself. Such as, # 12AB#, where # is
the delimiting character.
17.1.3 Statement Labels and Source Line Numbers
FORTRAN statement labels are input and output by straightforward
numeric reference, such as 1234. However, source line numbers must be
input to FORDDT with a number sign (#) preceding them. This mandatory
sign distinguishes statement labels from source line numbers.
PAUSE #3 !This causes a pause at source line number 3.
PAUSE 3 !This causes a pause at the statement labeled 3.
17.2 FORDDT AND THE FORTRAN /DEBUG SWITCH
Most facilities of FORDDT are available without the FORTRAN /DEBUG
features. However, if you do not use the /DEBUG switch when compiling
a FORTRAN program, the trace features (NEXT command) will not be
| available, and several of the other commands will be restricted. In
| addition, the /DEBUG switch must be used if long symbols are to be
| made available to FORDDT. If long symbols are used in your FORTRAN
| program, and you do not use the /DEBUG switch when compiling, only the
| first six characters of each symbol is available to FORDDT.
Using the /DEBUG switch tells FORTRAN to compile extra information for
debugging. (See Chapter 16 for more information.) These features are:
17-4
USING THE FORTRAN INTERACTIVE DEBUGGER (FORDDT)
1. /DEBUG:DIMENSIONS, which generates dimension information in
the .REL file for all arrays dimensioned in the subprogram.
The dimension information is automatically available to
FORDDT if you wish to reference an array in a TYPE or ACCEPT
command. This feature eliminates the need to specify
dimension information for FORDDT by using the DIMENSION
command.
2. /DEBUG:LABELS, which generates labels for every executable
source line in the form <line-number>L. If these labels are
generated, they may be used as arguments with the FORDDT
commands PAUSE and GOTO.
This switch also generates labels at the last location
allocated for a FORMAT statement so that FORDDT can detect
the end of the statement. These labels have the form
<format-label>F. If they are generated, you can display and
modify FORMAT statements by means of the TYPE and ACCEPT
commands.
Note that the :LABELS switch is automatically activated with
the :TRACE switch, since labels are needed to accomplish the
trace features.
3. /DEBUG:TRACE, which generates a reference to FORDDT before
each executable statement. This switch is required for the
trace command NEXT to function.
Note that if more than one FORTRAN statement is placed on a
single input line, only the first statement has a FORDDT
reference and line-number label associated with it. This
also applies to the :LABELS switch.
4. /DEBUG:INDEX, which forces the compiler to store in its
respective data location, as well as a register, the index
variable of all DO loops at the beginning of each loop
iteration. You will then be able to examine DO loops by
using FORDDT. If you modify a DO loop index using FORDDT, it
will not affect the number of loop iterations because a
separate loop count is used.
In addition, this switch forces all function values to be
stored in memory prior to return from the function. If this
switch is specified, you can set a FORDDT pause on the RETURN
statement (see Section 13.4.4) and then examine the value to
be returned.
5. /DEBUG:BOUNDS, which generates the bounds checking code for
all array references. Bounds violations produce run-time
error messages. Note that the technique of specifying
dimensions of 1 for subroutine arrays causes bounds check
errors. (You can use this option without FORDDT.)
17-5
USING THE FORTRAN INTERACTIVE DEBUGGER (FORDDT)
6. /DEBUG:ARGUMENTS, which performs type checking at load time
for actual argument types and associated dummy argument
types. Type violations produce non-fatal, load-time error
messages. This switch also performs type checking at
compile-time for statement functions.
17.3 LOADING AND STARTING FORDDT
1. On TOPS-10, the simplest method of debugging with FORDDT is:
.DEBUG filespec(DEBUG)
On TOPS-20, the corresponding command is:
@DEBUG filespec /DEBUG
On both systems, FORDDT responds with:
STARTING FORTRAN DDT
Program name:
When FORDDT prompts you for a program name, type the same
name specified in the PROGRAM statement of the program being
debugged. If the PROGRAM statement is not used in the
program being debugged, FORDDT uses MAIN., and will not
prompt for a program name.
FORDDT next prints its command prompt:
>>
The angle brackets indicate that FORDDT is ready to receive a
command.
2. If you are on TOPS-20, you can type a question mark to the
prompt to get a list of all FORDDT commands, as follows:
>>? One of the following:
ACCEPT CHARACTER CONTINUE DDT DIMENSION DOUBLE
GOTO GROUP HELP LOCATE MODE NEXT
OPEN PAUSE REMOVE START STOP STRACE
TYPE WHAT
Also on TOPS-20, you can use the ESCape key for recognition
of FORDDT commands. For example:
>>CON<ESC>TINUE
17-6
USING THE FORTRAN INTERACTIVE DEBUGGER (FORDDT)
On both systems, you need only type the unique abbreviation
of a specific FORDDT command.
3. You may wish to load your compiled program and FORDDT
directly with the linking loader. (Loading with LINK is
accomplished implicitly in the DEBUG command string.) The
command sequence is as follows:
On TOPS-10, to start LINK, type:
.R LINK
On TOPS-20, type:
@LINK
On both systems, when LINK prompts you with an asterisk, you
can type a command string in any of the following forms:
*filespec /DEB/G (loads DDT)
*filespec /DEB:{FORDDT}/G (loads FORDDT)
{FORTRA}
*filespec /DEB:(DDT,{FORDDT})/G (loads DDT
{FORTRA} and FORDDT)
*filespec /DEB:({FORDDT},DDT)/G (loads FORDDT
{FORTRA} and DDT)
In the last two command forms shown, the first debugging
program specified (FORDDT or DDT) in the command string is
the one you communicate with after the LINK command string
is executed.
See Section 17.9 for information on loading extended
addressing programs.
17.4 SCOPE OF NAME AND LABEL REFERENCES
Each program unit has its own symbol table. When you initially enter
FORDDT, you automatically open the symbol table of the main program.
All references to names or labels through FORDDT must be made with
respect to the currently open symbol table.
If you have given the main program a name other than MAIN. by using
the PROGRAM statement (see Section 6.4.1), FORDDT asks for the defined
program name. After you enter the program name, FORDDT opens the
appropriate symbol table. At this point, symbol tables in programs
other than the main program can be opened by using the OPEN command.
17-7
USING THE FORTRAN INTERACTIVE DEBUGGER (FORDDT)
References to statement labels, line numbers, FORMAT statements,
variables, and arrays must have labels that are defined in the
currently open symbol table. However, FORDDT will accept variable and
array references outside the currently open symbol table, providing
the name is unique with respect to all program units in the given load
module.
17.5 FORDDT COMMANDS
This section gives a detailed description of all commands in FORDDT.
The commands are given in alphabetical order:
ACCEPT Allows you to change the contents of a FORTRAN
variable, array, array element, array element range, or
FORMAT statement. The command format is:
ACCEPT name[/mode] value
where:
| name is the variable, substring, array, array
element, array element range, or FORMAT
statement to be modified.
mode is the format of the data value to be
entered. The mode keyword must be preceded
by a slash (/) and immediately follows the
name. Intervening blanks are not allowed.
(Note that /mode does not apply to FORMAT
modification.)
value is the new value to be assigned. The format
of the input value must correspond to the
specified mode.
DATA LOCATION MODIFICATION
Data Modes
The following data modes are accepted:
Mode Meaning Example
A ASCII (left-justified) /FOO/
C CHARACTER 'ABC'
D DOUBLE-PRECISION 123.4567890
F REAL 123.45678
I INTEGER 1234567890
O OCTAL 7654321
L LOGICAL .TRUE. or .FALSE.
17-8
USING THE FORTRAN INTERACTIVE DEBUGGER (FORDDT)
R RASCII (right-justified) \BAR\
S SYMBOLIC PSI(2,4)
X COMPLEX (1.25,-78.E+9)
If not specified, the default mode is REAL (F).
1. Two-Word Values
For the data modes ASCII (A), OCTAL (O), RASCII
(R), and SYMBOLIC (S), FORDDT will accept a "/BIG"
modifier on the mode switch. This modifier
indicates that the variable and the value are to be
interpreted as two words long.
Example:
ACCEPT VAR/RASCII/BIG '1234567890'
assumes that VAR is two words long and stores the
given 10-character literal into it.
The /BIG modifier can also be used to display more
than the first 256 characters of long character
strings.
2. Character Variables
A character variable can be initialized by using an
ACCEPT command of the following form:
ACCEPT VAR/C 'string'
| Note that the length of the variable is that which
is specified in the source program. If the string
is longer than the variable, the rightmost
characters are truncated. If the string is shorter
than the variable, it is stored left-justified and
padded on the right with blanks.
3. Initialization of Arrays
If the name field of an ACCEPT contains an
unsubscripted array name or a range of array
elements, all elements of the array or the
specified range are set to the given value.
Example:
ACCEPT ARRAY/F 1.0
or
17-9
USING THE FORTRAN INTERACTIVE DEBUGGER (FORDDT)
ACCEPT ARRAY(5)-ARRAY(10)/F 1.0
Note that this applies only to modes other than
ASCII and RASCII.
For character arrays, if the value has fewer
characters than the length of the array element,
the rightmost character positions of the element
are initialized with spaces. If the value has more
characters than the length of the array element,
the value is truncated to the right.
4. Long Literals
When the value field of an ACCEPT contains an
unsubscripted array name or range of array
elements, and the specified data mode is ASCII, the
value field is expected to contain a long literal
string. ACCEPT stores the string linearly into the
array or array range. If the array is not filled,
the remainder of the array or range is filled with
zeroes. If the literal is too long, the remaining
characters are ignored.
Example:
ACCEPT ARRAY/ASCII
'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
5. FORMAT Statement Modification
When the name field of an ACCEPT contains a label,
FORDDT expects this label to be a FORMAT statement
label and that the value field contains a new
format specification.
Example:
ACCEPT 10 (1H0,F10.2,3(I2))
The new specification cannot be longer than the
space originally allocated to the FORMAT by the
compiler. The remainder of the area is cleared if
the new specification is shorter.
Note that FOROTS performs some encoding of FORMAT
statements when it processes them for the first
time. If any I/O statement referencing the given
FORMAT has been executed, the FORTRAN program has
to be restarted (re-initializing FOROTS).
CHARACTER Defines the dimensions of a character array. The
17-10
USING THE FORTRAN INTERACTIVE DEBUGGER (FORDDT)
result of this command is the same as for the DIMENSION
command except that the array so dimensioned is
understood by FORDDT to be a character array. The
command format is:
CHARACTER arrayname ([L1:]U1[,[L2:]U2,...])
NOTE
This declarator cannot be used to specify
element length. The length specified in the
user program will be used.
CONTINUE Allows the program to resume execution after a FORDDT
pause. After a CONTINUE is executed, the program
either runs to completion or until another pause is
encountered. The command format is:
CONTINUE [n]
where the n is optional and, if omitted, is assumed to
be one. If a value is provided, it can be a numeric
constant or program variable, but it is treated as an
integer. When the value n is specified, the program
continues execution until the nth occurrence of this
pause. For example,
CONTINUE 20
continues execution until the 20th occurrence of the
pause, or until a different pause is encountered.
DDT Transfers control of the program to DDT, the standard
system debugging program. Any files currently opened
by FOROTS are unaffected, and a return to FORDDT is
possible so that program execution may be resumed.
%FDDT is the global symbol used to return control to
FORDDT. The command format is:
%FDDT<ESC>G
Your program will be in the same condition as before
unless you have modified your core image with DDT.
DIMENSION Sets, displays, or removes the user-defined dimensions
of an array for FORDDT access purposes. These
dimensions need not agree with those declared to the
compiler in the source code. FORDDT allows you to
redimension an array to have a larger scope than that
of the source program. If this is done, a warning is
given.
17-11
USING THE FORTRAN INTERACTIVE DEBUGGER (FORDDT)
NOTE
The DIMENSION command cannot be used to declare
double-precision, complex, or character arrays
(see the CHARACTER and DOUBLE commands).
The command format is:
DIMENSION name ([L1:]U1[,[L2:]U2,...])
where:
name is the name of the array
([L1:]U1...) specifies the bounds of the
array, where L is the lower
bound and U is the upper
bound. The default value of L
is 1. The bounds must be
integer constants or
variables.
For example:
DIMENSION ALPHA(7,5:6,10)
FORDDT remembers the dimensions of the array until they
are redefined or removed.
The command:
DIMENSION
gives a full list of all the user-defined dimensions
for all arrays.
DIMENSION ALPHA
displays the current information for the array ALPHA
only.
DIMENSION ALPHA/REMOVE
removes any user-defined array information for the
array ALPHA.
DOUBLE Defines the dimensions of a double-precision or complex
array. The result of this command is the same as for
the DIMENSION command except that the array so
dimensioned is understood by FORDDT to be an array with
two-word elements.
The command format is:
17-12
USING THE FORTRAN INTERACTIVE DEBUGGER (FORDDT)
DOUBLE arrayname ([L1:]U1[,[L2:]U2,...])
GOTO Allows you to continue your program from a point other
than the one at which it last paused. The GOTO allows
you to continue at a statement label or source line
number provided that the /DEBUG:LABELS switch has been
used or the contents of a symbol previously ASSIGNed
during the program execution has been used.
Note that the program must be STARTed before this
command can be used, and also note that a GOTO is not
allowed after the <CTRL/C>, REENTER sequence (see
Section 17.6).
The command format is:
GOTO n
GROUP Sets up a string of text for input to a TYPE command.
You can store TYPE statements as a list of variables
identified by the numbers 1 through 8. This feature
eliminates the need to retype the same list of
variables each time you wish to examine the same group.
Refer to the TYPE command for the proper format of the
list.
The command format is:
GROUP [n list]
where:
n is the group number 1-8
list is a list of group numbers preceded by a
| slash (/) and/or variable names,
| substrings, array elements, and array
| element ranges to be typed when you give
the command: TYPE /n, where n is the
group number. The validity of the list
is not checked.
GROUP
with no arguments causes FORDDT to type out the current
contents of all the groups.
GROUP n
types out the contents of the particular group
requested.
Note that one group may refer to another.
17-13
USING THE FORTRAN INTERACTIVE DEBUGGER (FORDDT)
For example:
GROUP 2 VAR2,VAR3
GROUP 3 /1,/2
LOCATE Lists the program unit names in which a given symbol is
defined. This is useful when the variable you wish to
locate is not in the currently open program unit and is
defined in more than one program unit. The command
format is:
LOCATE n
where n may be any FORTRAN variable, array, label, line
number, or FORMAT statement number.
MODE Defines the display format for succeeding FORDDT TYPE
commands. You need type only the first character of
the mode to identify it to FORDDT because all
characters after the first are ignored. The modes are:
Mode Meaning
C CHARACTER
F REAL
D DOUBLE-PRECISION
X COMPLEX
I INTEGER
O OCTAL
A ASCII (left-justified)
R RASCII (right-justified)
L LOGICAL
Unless the MODE command is given, the default typeout
mode is the REAL (F) format.
The command format is:
MODE list
where list contains one or more of the mode identifiers
separated by commas. The current setting can be
changed by issuing another MODE command. If more than
one mode is given, the values are typed out in the
order: C, F, D, X, I, O, A, R, L.
A typical command string might be:
MODE A,I,OCTAL
NEXT Allows you to cause FORDDT to trace source lines,
statement labels, and entry point names during
execution of your program. This command only provides
17-14
USING THE FORTRAN INTERACTIVE DEBUGGER (FORDDT)
trace facilities if the program is compiled with the
FORTRAN /DEBUG switch. If this switch is not used, the
NEXT command acts as a CONTINUE command. The command
format is:
NEXT [n][/sw]
where:
n is a program variable or integer numeric
value
sw is one of the following switches
/S= statement label
/L= source line
/E= entry point
The default starting value of n is 1, a single
statement trace. The default switch is /L.
The command
NEXT 20/L
traces the execution of the next 20 source line numbers
or until another pause is encountered.
Note that if no argument is specified, the last
argument given is used.
For example:
NEXT /E
changes the tracing mode to trace only subprogram
entries using the numeric argument previously supplied.
OPEN Allows you to open a particular program unit of the
loaded program so that the variables are accessible to
FORDDT. Any previously opened program unit is closed
automatically when a new one is opened. Only global
symbols, symbols in the currently open unit, and unique
locals are available at any one time. Note that
starting FORDDT automatically opens the main program.
The command format is:
OPEN name
where name is the subprogram name. OPEN with no
arguments reopens the main program.
17-15
USING THE FORTRAN INTERACTIVE DEBUGGER (FORDDT)
PAUSE Allows you to place a FORDDT breakpoint at a statement
number, source line number, or subroutine entry point.
Up to ten breakpoints may be set at any one time. When
a breakpoint is encountered, execution is suspended at
that point and control is returned to FORDDT. The
symbol table of that subprogram is also automatically
opened.
The command formats are:
PAUSE
PAUSE p
PAUSE p AFTER n
PAUSE p IF condition
PAUSE p TYPING /g
PAUSE p AFTER n TYPING /g
PAUSE p IF condition TYPING /g
where:
P is the point where the breakpoint is
inserted
n is an integer constant, variable, or
array element
g is a group number
PAUSE 100
sets a breakpoint at statement label 100, causes
execution to be suspended, and causes FORDDT to be
entered on reaching 100 in the program.
PAUSE #245 AFTER MAX(5)
causes a break to occur at source line number 245 after
encountering this point the number of times specified
by MAX(5). Note that AFTER can not be abbreviated.
PAUSE DELTA IF LIMIT(3,1).GT.2.5E-3
causes a FORDDT break to occur if the variable
LIMIT(3,1) is greater than the value 2.5E-3. The IF
can not be abbreviated, and the following FORTRAN
logical connectives are allowed:
.GT., .GE., .LT., .LE., .EQ., .NE.
Double-precision comparisons and arithmetic operations
are not allowed. However, comparisons can be made
between variables, constants, and logical constants
(such as .TRUE. and .FALSE.).
PAUSE 505 TYPING /5
17-16
USING THE FORTRAN INTERACTIVE DEBUGGER (FORDDT)
sets a FORDDT breakpoint at label 505, and the
variables in group 5 are displayed. The TYPING
specification can not be abbreviated.
PAUSE #24 AFTER 16 TYPING /3
causes a break at source line number 24 after 16 times
through; however, the contents of group 3 are displayed
every time.
When the TYPING option is used with the PAUSE command,
control can be transferred to FORDDT at the next
typeout by typing any character on the terminal.
Note that pause requests remain after a <CTRL/C>
REENTER sequence, a START command, or a <CTRL/C> START
sequence.
PAUSE ON ERROR Causes the program to enter FORDDT whenever an error
occurs (such as an arithmetic overflow). It has the
same command format as the PAUSE command.
REMOVE Removes the previously set FORDDT breakpoints. The
command format is:
REMOVE [p]
For example,
REMOVE L#123
removes a breakpoint from the program source line
number 123.
REMOVE ALPHA
removes a breakpoint from the subroutine entry to
ALPHA.
REMOVE with no arguments removes all your FORDDT
breakpoints, and, in this case, no abbreviation of
REMOVE is allowed.
REMOVE ON ERROR Removes a PAUSE ON ERROR breakpoint. It has the same
command format as the REMOVE command.
START Starts your program at the normal FORTRAN main program
entry point. The command format is:
START
STOP Terminates the program, closes all files opened by
FOROTS, and causes an exit to the monitor. The usual
17-17
USING THE FORTRAN INTERACTIVE DEBUGGER (FORDDT)
command format is:
STOP
STOP /RETURN
allows a return to monitor mode without releasing
devices or closing files so that a CONTINUE can be
issued.
STRACE Displays a subprogram level traceback of the current
state of the program. The command format is:
STRACE
| TYPE Displays FORTRAN defined variables, substrings, arrays,
or array elements on your terminal. The command format
is:
TYPE list
| where list may be one or more variables, substrings, or
array references and/or group numbers. These
specifications must be separated by commas, and group
numbers must be preceded by a slash (/). The command
with no arguments uses the last argument list submitted
to FORDDT.
An array element range can also be specified. For
example:
TYPE PI(5)-PI(13)
displays the values from PI(5) to PI(13) inclusive. If
an unsubscripted array name is specified, the entire
array is typed.
There are several methods of choosing the form of
typeout in conjunction with the MODE command:
1. If you do not specify a format, the default is
real.
2. You can specify a format through the MODE command
described in this chapter.
3. You can change the format(s) previously designated
by the MODE command by including print modifiers in
the TYPE or GROUP string. The print modifiers are:
A ASCII(left-justified)
B LONG
C CHARACTER
17-18
USING THE FORTRAN INTERACTIVE DEBUGGER (FORDDT)
D DOUBLE-PRECISION
F REAL
I INTEGER
L LOGICAL
O OCTAL
R RASCII(right-justified)
X COMPLEX
4. If you type a variable in mode CHARACTER (C), the
number of characters printed is equal to the length
declared in the FORTRAN source program, up to a maximum
of 256 characters. The /B switch can be used to
override the 256 character maximum.
The B switch may be used in conjunction with the A, O,
and R switches. This modifier indicates that the
variable is to be interpreted as two words long. The B
switch can also be used with the C switch to display
more than the first 256 characters of long character
strings. The B switch can not be used alone.
The first print modifier specified in a string of
variables determines the mode for the entire string
unless another mode is placed directly to the right of
a particular variable. For example, in:
TYPE /I K,L/O,M,N/A,/2
the typeout mode is integer until another mode is
specified. Therefore,
K, M are integer - the default mode for group 2 is
integer
L is OCTAL
N is ASCII
WHAT Displays on your terminal the name of the currently
open program unit, any currently active breakpoints,
any group specifications, and any user-set array
dimensions. The command format is:
WHAT
17.6 ENVIRONMENT CONTROL
If a program enters an infinite loop, you can recover by typing a
<CTRL/C>(twice) REENTER sequence. This action causes FORDDT to
simulate a pause at the point of reentry and allows you to control
your run-away program.
Most commands can be used once the program has been reentered;
17-19
USING THE FORTRAN INTERACTIVE DEBUGGER (FORDDT)
however, GOTO, STRACE, TYPE, and ACCEPT cause transfer of control to
routines external to FORDDT. No guarantee can be made to ensure that
any of these commands following a <CTRL/C> REENTER sequence will not
destroy the program integrity. The program must be returned to a
stable state before any of these four commands can be issued. In
order to restore program integrity, you should set a pause at the next
label and then CONTINUE to it. If the /DEBUG:TRACE switch is used, a
NEXT 1 command can be issued to restore program integrity.
17.7 FORTRAN /OPTIMIZE SWITCH
You should never attempt to use FORDDT with a program that has been
compiled with the /OPTIMIZE switch. The global optimizer causes
variables to be kept in ACs. For this reason, attempts to examine or
modify variables in optimized programs will not work.
17.8 CALLING FORDDT
FORDDT can be called directly from a user FORTRAN program. The
appropriate statement is:
CALL FORDDT
where no argument is required. FORDDT must be loaded and initialized
before a CALL to FORDDT is made. This is done by starting the program
in debug mode prior to the first call (see Section 17.3, item 1). All
FORDDT commands are allowed. A CONTINUE will resume normal execution
of the user program (similar to a RETURN from a subroutine).
NOTE
Since FORDDT is defined as a global symbol, users
should be careful if they decide to use FORDDT as a
program, subroutine, or function name.
17.9 FORDDT AND FORTRAN-20 EXTENDED ADDRESSING
FORDDT V10 has been modified to be able to run in any section and
access data and code in all sections. The user interface to FORDDT is
the same regardless of whether or not a program uses extended
addressing.
FORDDT V10 is section independent. The same FORDDT.REL will work in
either section 0 or a non-zero section.
If a program is loaded with the /DEBUG:FORDDT option, LINK loads
17-20
USING THE FORTRAN INTERACTIVE DEBUGGER (FORDDT)
FORDDT.REL with the program. FORDDT.REL is a single-segment module
(it has only low segment code); therefore, when loaded with a FORTRAN
object program that was compiled with the /EXTEND switch (see Section
16.5), FORDDT, by default, is redirected to the .DATA. psect.
FORDDT Version 10 will not be guaranteed to work with previous
versions of FORTRAN-10/20.
FORDDT and FORLIB must be in the same section. Since they would by
default go into the .DATA./.CODE. section, the user normally would not
need to be concerned about this. However, you should be cautious when
you use the LINK /REDIRECT switch.
NOTE
The first page of any section that contains code is
reserved for FORDDT and FOROTS.
17-21
18-1
CHAPTER 18
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
This chapter describes the facilities that the FORTRAN Object Time
System (FOROTS) provides for the FORTRAN user. FOROTS implements all
standard FORTRAN I/O operations as set forth in the FORTRAN-77
standard In addition it provides the user with capabilities and
programming features beyond those defined in the ANSI standard.
The primary function of FOROTS is to act as a direct interface between
user-object programs and the TOPS-10 or TOPS-20 monitor during input
and output operations. Other capabilities include:
1. Job initialization
2. Channel and memory management
3. Error handling and reporting
4. File management
5. Formatting of data
6. Mathematical library
7. User library (nonmathematical)
8. Specialized applications packages
9. Overlay facilities
|
| 10. RMS-20 interface (TOPS-20 only)
|
| 11. Network file access (TOPS-20 only)
FOROTS runs on any TOPS-10 or TOPS-20 system. FOROTS interfaces with
all TOPS-10 or TOPS-20 peripheral devices.
18-1
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
18.1 FEATURES OF FOROTS
The following list briefly describes many specific features of FOROTS;
more detailed information concerning the implementation of these
features is given later in this chapter.
1. Your program can run in either batch or timesharing mode
without requiring a program change. All differences between
batch-mode and timesharing-mode operations are resolved by
FOROTS.
2. Your programs can access both directory and nondirectory
devices in the same manner.
3. FOROTS helps provide complete data file compatibility between
all system devices.
4. FOROTS treats devices located at remote stations in the same
way it treats local devices.
5. Programs written for magnetic tape operations will run
correctly on disk under FOROTS supervision. FOROTS simulates
the commands needed for magnetic tape operations.
6. You may change or specify object program device and file
specifications with a FOROTS interactive dialogue.
7. Non-FORTRAN binary data files may be read in IMAGE mode by
FOROTS.
8. FOROTS provides interactive program/operating system
error-processing routines. These routines permit you to
route the execution of the program to specific
error-processing routines whenever designated types of errors
are detected.
9. An error traceback facility for fatal errors provides the
active execution path (by subroutine calls) between the main
program and the subroutine where the fatal error occurred.
10. FOROTS provides a trap-handling system for arithmetic
functions, including default values and error reports.
11. FOROTS permits your program to switch from READ to WRITE on
the same I/O device without loss of data or buffering.
12. Although primarily designed for use with the FORTRAN-10/20
object programs, you can also use FOROTS as an independent
I/O system, and as an I/O system for MACRO object programs.
|
| 13. FOROTS provides an interface to RMS-20 (TOPS-20 Record
| Management Services) for I/O to RMS-20 sequential, relative,
18-2
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
| and indexed file organizations.
|
| 14. FOROTS allows transparent access from TOPS-20 systems to
| remote RMS and non-RMS files residing on other TOPS-20 and
| VMS systems.
18.2 ERROR PROCESSING
Whenever a run-time error is detected, the FOROTS error-processing
system takes control of program execution. This system determines the
class of the error and either outputs an appropriate message at the
controlling terminal or branches the program to a predesignated
processing routine.
18.3 INPUT/OUTPUT FACILITIES
On TOPS-10, FOROTS uses monitor-buffered I/O for SEQUENTIAL, SEQINOUT,
SEQIN, and SEQOUT files access, and uses dump mode I/O for
DIRECT(RANDOM), RANDIN, and dump mode files access.
On TOPS-20, FOROTS uses PMAP monitor calls for disk files access other
than APPEND, and uses monitor-buffered I/O for all other file
accesses.
| On TOPS-20, FOROTS uses the RMS-20 subsystem for disk I/O if the
| ORGANIZATION keyword specifies an RMS file organization, or if the
| file is remote.
The following sections describe I/O data channel and access modes.
18.3.1 Input/Output Channels Used By FOROTS (TOPS-10 Only)
FOROTS uses extended channels starting at channel 20 for I/O
operations. User programs can request I/O channels 0 through 17
through the ALCHN. and FUNCT. routines.
When a request is made for an I/O channel, a table is scanned until a
free channel is found. The first free channel is assigned to the
requesting program. On completion of the assigned transfer, control
of the I/O channel is returned to FOROTS by using the DECHN. routine.
18.3.2 File Access
Data can be transferred between processor storage and peripheral
18-3
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
devices using either sequential or direct (random) access.
18.3.3 Closing Files After Non-standard Termination
When a FORTRAN program is aborted by <CTRL/C> or an error, open files
cannot be closed with the monitor command CLOSE. The following
command should be used:
REENTER
FOROTS then asks if you want the files to be closed. If you answer
YES, then, the files are closed.
18.3.3.1 Sequential Access - In a sequential-access transfer
operation, the records involved are transferred in the same order as
they appear in the source file. Each I/O statement executed transfers
the record immediately following the last record transferred from the
accessed source file.
A type of the sequential access is available for output (write)
operations. This type of access is called APPEND and is specified by
the OPEN statement specifier ACCESS='APPEND' (see Section 11.3.1).
APPEND lets you write a record immediately after the last logical
record of the accessed file. During APPEND transfer, the records
already in the accessed file remain unchanged; the only function
performed is the appending of the transferred records to the end of
the file.
You must specify transfer types (other than SEQINOUT) by setting the
ACCESS option of a FORTRAN OPEN statement to one of several possible
arguments. For the sequential access, the arguments are:
ACCESS='SEQIN' (file is opened for read-only access)
ACCESS='SEQOUT' (file is opened for output)
ACCESS='SEQUENTIAL' (file is opened for input or output)
ACCESS='SEQINOUT' (same as SEQUENTIAL)
ACCESS='APPEND' (sequential append access)
NOTE
A common way to append data to a file opened with
SEQUENTIAL access is to read past the end of file, and
then begin writing. The FORTRAN-77 standard requires
that a BACKSPACE operation be done to back over the
'end file record' preceding the WRITE.
18-4
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
18.3.3.2 Direct (Random) Access Mode - Direct access permits records
to be accessed and transferred from a source file in any desired
order. Direct access can only be used with disk files that have been
set up for direct access. Direct-access files must contain a
specified number of identically sized records that may be individually
accessed by a record number.
Direct-access transfers may be done in either a read/write direction
or a special read-only direction. You must specify random transfer
direction by setting the ACCESS option of an OPEN statement (see
Section 11.3.1) to one of several possible arguments.
ACCESS='DIRECT' (direct read/write access)
ACCESS='RANDOM' (same as DIRECT)
ACCESS='RANDIN' (direct read-only access)
| ACCESS='KEYED' (direct indexed-file read/write access)
18.4 ACCEPTABLE TYPES OF DATA FILES AND THEIR FORMATS
The following sections describe the types of data files that are
acceptable to FOROTS.
18.4.1 ASCII Data Files
Each record within an ASCII data file consists of a set of contiguous
7-bit characters. A vertical paper-motion character (that is, a form
feed, a vertical tab, or a line feed) terminates each set. Logical
records may be split across physical blocks. There is no maximum
length for logical records.
18.4.2 FORTRAN Binary Data Files
Each logical record in a FORTRAN binary data file contains data that
the executing program can reference with either a READ or a WRITE
statement. A logical record is preceded and ended by a control word
and may have one or more control words embedded within it. In FORTRAN
binary data files, there is no relationship between logical records
and physical device block sizes. There is no implied maximum length
for logical records.
18.4.2.1 Format of Binary Files - A FOROTS binary file can contain
three forms of Logical Segment Control Words (LSCW). These LSCWs give
FOROTS the ability to distinguish ASCII files from binary files. The
value in the high-order 9 bits of an LSCW tells what kind of LSCW it
18-5
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
is: START, CONTINUE, or END.
LSCW
START 001+ the number of words in the segment including
the START LSCW word (exclusive of the END
LSCW)
CONTINUE 002+ the number of words in the segment including
the CONTINUE LSCW
END 003+ the number of words in the whole record
including all LSCWs
If the access you specify for a file through the OPEN statement
ACCESS= argument is 'SEQIN', 'SEQOUT', 'SEQUENTIAL', or 'SEQINOUT',
all three LSCWs can appear in a record. If you specify a record size,
all records are of the same length, and there are no CONTINUE LSCWs.
The following examples illustrate the LSCW. The direct-access binary
file contains only 001 and 003 LSCWs.
C LOOK AT A BINARY FILE AND SEE THE LOGICAL SEGMENT
C CONTROL WORDS.
OPEN(UNIT=1,ACCESS='DIRECT',MODE='BINARY',
1 RECORDSIZE=100)
I=5
WRITE(1'1) (I, J=1,10)
J=7
WRITE(1'2) (J,K=1,10)
END
18-6
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
18-7
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
18-8
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
On TOPS-10, in the sequential-access binary file, the second record
crosses the disk block boundary and contains an 002 (CONTINUE) LSCW.
On TOPS-20, the CONTINUE LSCW occurs on buffer boundaries, whose size
is determined by the BUFFERCOUNT keyword in the OPEN statement (see
Section 11.3.5) (default is four pages, 4000 octal words).
C LOOK AT A BINARY FILE AND SEE THE LOGICAL SEGMENT
C CONTROL WORDS.
OPEN(UNIT=1,MODE='BINARY')
I=5
WRITE(1) (I, J=1,100)
J=7
WRITE(1) (J,K=1,100)
END
18-9
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
18-10
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
18-11
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
Image files contain no LSCWs. You can only backspace an IMAGE file
that is created with a record size.
C LOOK AT AN IMAGE MODE FILE AND SEE NO LOGICAL SEGMENT
C CONTROL WORDS.
OPEN(UNIT=1,MODE='IMAGE')
I=5
WRITE(1) (I, J=1,100)
J=7
WRITE(1) (J,K=1,100)
END
18-12
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
18-13
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
18-14
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
The following example illustrates the LSCWs for character data in
binary files.
C LOOK AT BINARY MODE FILE WITH CHARACTER DATA AND SEE THE
C LOGICAL SEGMENT CONTROL WORDS
OPEN (UNIT=1,MODE='BINARY')
WRITE (1) 3, 'ABCDEF',4,'GHIJKL'
WRITE (1) 'MNOPQR','STUVWX'
END
0/ 001000,000007
1/ 000000,000003
2/ 406050,342212
3/ 430000,000000
4/ 000000,000004
5/ 436211,145226
6/ 460000,000000
7/ 003000,000010
10/ 001000,000004
11/ 466351,750242
12/ 512472,452654
13/ 536600,000000
14/ 003000,000005
The following example illustrates the format of character data in
image files. Image files contain no LSCWs.
C LOOK AT IMAGE MODE FILE WITH CHARACTER DATA AND SEE
C NO LOGICAL SEGMENT CONTROL WORDS
OPEN (UNIT=1,MODE='IMAGE')
WRITE (1) 3, 'ABCDEF',4,'GHIJKL'
WRITE (1) 'MNOPQR','STUVWX'
END
0/ 000000,000003
1/ 406050,342212
2/ 430000,000000
3/ 000000,000004
4/ 436211,145226
5/ 462331,647640
6/ 506452,352252
7/ 532573,000000
18-15
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
| 18.4.3 RMS Data Files (TOPS-20 only)
|
| The FOROTS/RMS-20 interface can be used to access RMS-20 (and remote
| VMS RMS-32) files with sequential, relative, or indexed organizations.
|
| An RMS record file consists of a prologue section and a data section.
| The prologue section is the repository of the file's attributes. The
| data section contains data records (and indexes, if applicable).
|
| See the TOPS-20 RMS User's Guide for more information on RMS file
| formats.
18.5 USING FOROTS
FOROTS has been designed to lend itself for use as an I/O system for
programs written in languages other than FORTRAN. Currently, MACRO
programmers may employ FOROTS as a general I/O system by writing
simple MACRO calls that simulate the calls made to FOROTS by a FORTRAN
compiler. The calls made to FOROTS are to routines that implement
FORTRAN I/O statements such as READ, WRITE, OPEN, or CLOSE.
FOROTS will provide automatic memory allocation, data conversion, I/O
buffering, and device interface operations to the MACRO user.
18.5.1 FOROTS Entry Points
FOROTS provides the following entry points for calls from either a
FORTRAN compiler or a non-FORTRAN program. These entry points are
contained in FORLIB.REL.
18-16
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
Table 18-1: FOROTS Entry Points
Entry Point Function
ALCHN. Allocates an I/O channel for use by a MACRO
subroutine (see Section 18.5.3.12)
ALCOR. Allocates memory (see Section 18.5.3.11)
CLOSE. Closes a file. In a FORTRAN program, this call is
made when the CLOSE statement is executed (see
Section 18.5.3.10)
DBMS. DBMS interface.
DEC. DECODE routine. This call, coupled with an IOLIST
call, handles decoding.
DECHN. Deallocates an I/O channel that was obtained from
ALCHN (see Section 18.5.3.12)
DECOR. Deallocates memory that was allocated by an ALCOR
call (see Section 18.5.3.11)
| DELTR. Deletes an RMS relative or indexed file record. In
| a FORTRAN program, this call is made when a DELETE
| statement is executed (see Section 10.13).
ENC. ENCODE routine
EXIT. Closes all files, clears interrupt system, and
terminates program execution. In a FORTRAN
program, this call is made when an END statement is
executed in the main program.
EXIT1. Writes out buffers, closes and unmaps all files
FIN. I/O list termination routine (see Section 18.5.3.9)
FIND. FIND statement
FORER. Error processor
FOROP. Miscellaneous FOROTS utilities
18-17
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
Table 18-1: FOROTS Entry Points (Cont'd)
Entry Point Function
FUNCT. OTS-independent interface to provide common
functions (like memory and I/O channel management)
for programs such as overlay handler and DBMS.
FUNCT. is an interface that works the same way with
FORTRAN, COBOL, and ALGOL run-time systems (see
Section 18.6).
IFI. Internal file input (see Section 18.5.3.2)
IFO. Internal file output (see Section 18.5.3.2)
IN. Formatted input routine (see Sections 18.5.3.1,
18.5.3.5, 18.5.3.6, and 18.5.3.8)
IOLST. I/O list routine (see Section 18.5.3.9)
MTOP. REWIND, BACKSPACE, and ENDFILE statements (see
Section 18.5.3.7).
NLI. NAMELIST input routine (see Section 18.5.3.3)
NLO. NAMELIST output routine (see Section 18.5.3.3)
OPEN. Opens a file. Connects FORTRAN Logical Unit Number
to a file for I/O (see Section 18.5.3.10)
OUT. Formatted output routine (see Sections 18.5.3.1,
18.5.3.5, 18.5.3.6, and 18.5.3.8)
RESET. Job initialization entry
| REWRF. Formatted REWRITE output routine. In a FORTRAN
| program, this call is made when a formatted REWRITE
| statement is executed for RMS files (see Section
| 10.14.1).
|
| REWRU. Unformatted REWRITE output routine. In a FORTRAN
| program, this call is made when an unformatted
| REWRITE statement is executed for RMS files (see
| Section 10.14.2).
| RTB. Binary input routine (see Sections 18.5.3.1 and
| 18.5.3.5)
TRACE. Traces subroutine calls
18-18
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
| UNLOC. UNLOCK record routine for RMS files. (See the
| UNLOCK statement, Section 10.15.)
WTB. Binary output routine (see Sections 18.5.3.1 and
18.5.3.5)
18.5.2 Calling Sequences
You must use the following general form for all calls made to FOROTS:
XMOVEI 16,ARGBLK
PUSHJ 17,Entry Point
(control is returned here)
where:
ARGBLK is the address of a specifically formatted
argument block that contains information needed by
FOROTS to accomplish the desired operation.
Entry Point is an entry point identifier (see Table 18-1) that
specifies the entry point of the desired FOROTS
routine.
With three exceptions, all returns from FOROTS will be made to the
program instruction immediately following the call (PUSHJ 17, entry
point instruction). The exceptions are:
1. An error return to a specified statement number, that is,
READ or WRITE statement ERR=option (see Section 10.4.7),
2. An end-of-file return to a statement number, that is, READ or
WRITE statement END=option (see Section 10.4.6),
3. A fatal error that returns to the monitor.
Sections 18.5.3.1 through 18.5.3.12 give the MACRO calls and required
argument block formats needed to initialize FOROTS and FOROTS I/O
operations.
18.5.3 MACRO Calls for FOROTS Functions
The following sections describe the forms of the MACRO calls to FOROTS
that are made by the FORTRAN compiler. The calls described are
identified by the language statement that they implement. The
following terms and abbreviations are used in the description of the
argument block (ARGBLK) of each call:
18-19
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
= pointer to the second word in the argument block (This
is the address pointed to by the argument ARGBLK in the
calling sequence.)
u = FORTRAN logical unit number
n = count of ASCII characters
f = FORMAT statement address
list = an Input/Output list
name = a NAMELIST name
r = a variable specifying the logical record number for
random access mode
* = list-directed I/O (the FORMAT statement is not used)
type = type specification of a variable or constant
The argument block for all I/O statements is a sequence of keyword
specifiers. Bits 2-8 of each argument specify which argument is being
supplied, as follows:
1 UNIT
2 FMT address
3 FMT size (in words)
4 END= address
5 ERR= address
6 IOSTAT= address
7 REC=
10 NAMELIST table address
11 File-positioning function code
12 ENCODE/DECODE array address
13 Internal record length
| 14 Relational type for indexed READ
| 15 Key number of key for indexed READ
| 16 Key relational value
18-20
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
The format of ARGBLK is:
0-1 2-8 9-12 13 14-17 18-35
(-count - negative of number of words in 0
block not including this one)
ARGBLK: 1 0 kwd type I 0 y
. .
. .
. .
1 0 kwd type I 0 y
where:
I = indirection bit
y = 18-bit address or data
kwd = keyword number
NOTE
Future versions of FOROTS will not support argument
blocks with index registers specified either in the
arguments or in memory locations referenced indirectly
by these arguments. Arguments must not reside in the
ACs. In addition, so-called 'immediate' arguments
(those with a type code of zero) will not be
supported.
18.5.3.1 Sequential-Access Calling Sequences - The READ and WRITE
statements for formatted sequential data transfer operations and their
calling sequences are:
READ(u,f) list
XMOVEI 16, ARGBLK
PUSHJ 17, IN.
and
WRITE(u,f) list
XMOVEI 16, ARGBLK
PUSHJ 17, OUT.
The following arguments must be specified in ARGBLK:
1 UNIT
2 FMT address
3 FMT size
18-21
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
The following may also appear:
4 ERR
5 END
6 IOSTAT
The READ and WRITE statements for unformatted sequential data transfer
operations and their calling sequences are:
READ(u) list
XMOVEI 16, ARGBLK
PUSHJ 17, RTB.
and
WRITE(u) list
XMOVEI 16, ARGBLK
PUSHJ 17, WTB.
The following arguments must be specified in ARGBLK:
1 UNIT
The following may also appear:
4 END
5 ERR
6 IOSTAT
18.5.3.2 Internal File Calling Sequences - The READ and WRITE
statements for formatted sequential data transfer operations using
internal files and their calling sequences are:
READ(u,f) list
XMOVEI 16, ARGBLK
PUSHJ 17, IFI.
and
WRITE(u,f) list
XMOVEI 16, ARGBLK
PUSHJ 17, IFO.
The following arguments must be specified in ARGBLK:
18-22
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
1 UNIT (must be a character scalar or array)
2 FMT address
3 FMT size
The following may also appear:
4 ERR
5 END
6 IOSTAT
18.5.3.3 NAMELIST I/O, Sequential-Access Calling Sequences - The READ
and WRITE statements for NAMELIST-directed sequential data transfer
operations and their calling sequences are:
READ (u, name)
XMOVEI 16, ARGBLK
PUSHJ 17, NLI.
and
WRITE (u, name)
XMOVEI 16, ARGBLK
PUSHJ 17, NLO.
The following arguments must be specified in ARGBLK:
1 UNIT
10 NAMELIST address
The following may also appear:
4 END
5 ERR
6 IOSTAT
The NAMELIST table is generated from the FORTRAN NAMELIST statement.
The first word of the table is the NAMELIST name; following that are a
number of 2 word entries for scalar variables, and a number of (N+4)
word entries for array variables, where N is the dimensionality of the
array.
The names you specify in the NAMELIST statement are stored, in SIXBIT
format, first in the table. Each name is followed by a list of
arguments associated with the name. The NAMELIST table is terminated
by a zero entry. The name argument list can be in either a scalar or
an array form.
18-23
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
18.5.3.4 Array Offsets and Factoring - Address calculations used to
reference a given array element involve factors and offsets. For
example:
Array A is dimensioned
DIMENSION A (L1:U1,L2:U2,L3:U3,...Ln:Un)
The size of each dimension is represented by:
S1 = U1-L1+1
S2 = U2-L2+1
.
.
.
In order to calculate the address of an element referenced by:
A (I1,I2,I3,...In)
the following formula is used:
A+(I1-L1)+(I2-L2)*S1+(I3-L3)*S2*S1+...+(In-Ln)*S[n-1]*...*S2*S1
The terms are factored out depending on the dimensions of the array,
not on the element referenced, to arrive at the formula:
A+(-L1-L2*S1-L3*S2*S1...)+I1+I2*S1+I3*S2*S1...
The parenthesized part of this formula is the offset for a
single-precision array; it is referred to as the Array Offset.
For each dimension of a given array, there is a corresponding factor
by which a subscript in that position will be multiplied. From the
last expression, one can determine the factor for dimension n to be:
S[n-1]*S[n-2]*...*S2*S1
For double-precision and complex arrays, the expression becomes:
A+2*(I1-L1)+2*(I2-L2)*S1+2*(I3-L3)*S2+S1+...
Therefore, the array offset for a double-precision array is:
2*(-L1-L2*S1-L3*S2*S1...)
and the factor for the nth dimension is:
2*S[n-1]*S[n-2]*...*S2*S1
The factor for the first dimension of a double-precision array is
always 2. The factor for the first dimension of a single-precision
18-24
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
array is always 1.
For character arrays, the offset is calculated in bytes instead of
words. The byte offset from the start of a character array whose
elements are of length X is:
X*((I1-L1)+(I2-L2)*S2+...)
This offset is X times the offset of a single-precision numeric array.
NAMELIST Table
0 35
NAMELIST name in SIXBIT
NAMELIST entry 1
NAMELIST entry 2
.
.
.
NAMELIST entry n
4000,,0 (FOROTS FIN. word)
SCALAR ENTRY in a NAMELIST Table
0 1 2-8 9-12 13 14-17 18-35
SIXBIT/SCALAR NAME/
1 0 type 0 I 0 Scalar addr
ARRAY ENTRY in a NAMELIST Table
0-1 2-8 9-12 13 14-17 18-35
18-25
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
SIXBIT/ARRAY NAME/
1 0 #DIMS type I 0 BASE ADDR
ARRAY SIZE
OFFSET
Factor 1
Factor 2
.
.
.
Factor n
18.5.3.5 I/O Statements, Direct-Access Calling Sequences - The READ
and WRITE statements for formatted direct-access data transfers and
their calling sequences are:
READ (u'r,f) list
XMOVEI 16, ARGBLK
PUSHJ 17, IN.
and
WRITE (u'r,f) list
XMOVEI 16, ARGBLK
PUSHJ 17, OUT.
The following arguments must be specified in ARGBLK:
1 UNIT
2 FMT address
3 FMT size
7 REC
The following may also appear:
4 END
5 ERR
6 IOSTAT
The READ and WRITE statements for unformatted direct-access transfers
18-26
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
and their calling sequences are:
READ (u'r)
XMOVEI 16,ARGBLK
PUSHJ P,RTB.
and
WRITE (u'r)
XMOVEI 16,ARGBLK
PUSHJ P,WTB.
The following argument must be specified in ARGBLK:
1 UNIT
7 REC
The following may also appear:
4 END
5 ERR
6 IOSTAT
18.5.3.6 Default Devices Statements, Calling Sequences - The FORTRAN
statements that require the use of a reserved system default device
and their calling sequences are:
Default Device
ACCEPT f, list UNIT=-4 (TTY)
READ f, list UNIT=-5 (CDR)
REREAD f, list UNIT=-6 (REREAD)
XMOVEI 16, ARGBLK
PUSHJ 17, IN.
and
PRINT f, list UNIT=-3 (LPT)
PUNCH f, list UNIT=-2 (PTP)
TYPE f, list UNIT=-1 (TTY)
XMOVEI 16, ARGBLK
PUSHJ 17, OUT.
The arguments for these calls are the same as for the standard
formatted sequential READ and WRITE statements.
18-27
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
18.5.3.7 Statements to Position Files - The formatted and unformatted
FORTRAN statements that can be used to control the positioning of
files and their calling sequences are:
Function FOROTS Code
(FORTRAN Statement)
SKIPFILE (u) 7
BACKFILE (u) 3
BACKSPACE (u) 2
ENDFILE (u) 4
REWIND (u) 0
SKIPRECORD (u) 5
UNLOAD (u) 1
CALL:
XMOVEI 16, ARGBLK
PUSHJ 17, MTOP.
The following arguments must be specified in ARGBLK:
1 UNIT
11 FOROTS code
The following may also appear:
4 END
5 ERR
6 IOSTAT
NOTE
For disk files, UNLOAD is the same as REWIND; BACKFILE
and SKIPFILE are ignored.
18.5.3.8 List-Directed Input/Output Statements - You may write any
form of a sequential I/O statement as a list-directed statement by
replacing the referenced FORMAT statement number with an asterisk (*).
The list-directed forms of the READ and WRITE statements and their
calling sequences are:
READ (u, *) list
XMOVEI 16, ARGBLK
PUSHJ 17, IN.
and
18-28
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
WRITE (u, *) list
XMOVEI 16, ARGBLK
PUSHJ 17, OUT.
The arguments for these calls are the same as for the standard
formatted sequential READ and WRITE statements, except that the FORMAT
statement address and FORMAT statement size must be specified as zero.
18.5.3.9 Input/Output Data Lists - The compiler generates a calling
sequence to the run-time system for the I/O list in a READ or WRITE
statement. The argument block associated with the calling sequence
contains the addresses of the variables and arrays to be transferred
to or from an I/O buffer.
The general form of an I/O list calling sequence is:
XMOVEI 16, ARGBLK
PUSHJ 17, IOLST.
Any number of elements may be included in the ARGBLK. The end of the
argument block is specified by a zero entry or a FIN entry.
Mnemonic Name FOROTS Value
DATA 1
SLIST 2
ELIST 3
FIN 4
F77 SLIST 5
F77 ELIST 6
The elements of an I/O list are:
1. DATA
The DATA element converts one single- or double-precision or
complex item from external to internal form for a READ
statement and from internal to external form for a WRITE
statement. Each DATA element has the following format:
0-1 2-8 9-12 13 14-17 18-35
1 0 DATA type I 0 SCALAR ADDR
18-29
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
2. SLIST
The SLIST argument converts an entire array from internal to
external form or vice versa, depending on the type of
statement (that is, READ or WRITE) involved. An SLIST
consist of a table of arguments that has the following form:
0-1 2-8 9-12 13 14-17 18-35
1 0 SLIST type I 0 #ELEMENTS
1 0 0 type I 0 INCREMENT
1 0 0 type I 0 BASE ADDR1
For example, the sequence:
DIMENSION A(100),B(100)
READ(-,-)A
or
READ(-,-)(A(I),I=1,100) !only when the /OPT switch is used
develops an SLIST argument of the form:
0-1 2-8 9-12 13 14-17 18-35
1 0 2 2 0 0 [144]
1 0 0 2 0 0 [1]
1 0 0 2 0 0 A
0 0 4 0 0 0 0
More than one base address may appear in a SLIST as long as
the increment is the same. The sequence:
DIMENSION A(100), B(100)
WRITE (-,-) (A(I),B(I),I=100) !only when the /OPT
switch is used
develops an SLIST argument of the form:
0-1 2-8 9-12 13 14-17 18-35
1 0 2 2 0 0 [144]
1 0 0 2 0 0 [1]
18-30
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
1 0 0 2 0 0 A
1 0 0 2 0 0 B
0 0 4 0 0 0 0
3. ELIST
The SLIST format permits only a single increment to be
specified for a number of arrays, while the ELIST permits
different increments to be specified for different arrays.
An ELIST consists of a table of arguments that has the
following form:
The format of the ELIST is:
0-1 2-8 9-12 13 14-17 18-35
1 0 ELIST type I 0 No. Elements to
transfer
increment 1
1 0 0 type I 0 Base ADDR 1
increment 2
1 0 0 type I 0 Base ADDR 2
increment N
1 0 0 type I 0 Base ADDR N
For example, the FORTRAN sequence:
DIMENSION IC(6,100), IB(100)
WRITE(-,-) (IB(I),IC(1,I),I=1,100)
produces the ELIST:
0-1 2-8 9-12 13 14-17 18-35
1 0 3 2 0 0 [144]
1 0 0 2 0 0 [1]
1 0 0 2 0 0 IB
1 0 0 2 0 0 [6]
1 0 0 2 0 0 IC
0 0 4 0 0 0 0
The increment may be zero. This could be produced by the
sequence:
WRITE(-,-)(K,I=1,100) !only when the /OPT switch is used
Produces the ELIST:
18-31
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
0-1 2-8 9-12 13 14-17 18-35
1 0 3 2 0 0 [144]
1 0 0 2 0 0 [0]
1 0 0 2 0 0 K
0 0 4 0 0 0 0
4. FIN
The end of an I/O list is indicated by a FIN element. When
the I/O processor interprets this element, it performs a call
to FIN to terminate the I/O. This call must be made after
each I/O initialization call, including calls with a null I/O
list.
The FIN routine may be entered by an explicit call or by an
argument in this I/O list argument block. Both calls can not
be used. The FIN element has the following format:
0-1 2-8 9-12 13 14-17 18-35
0 0 4 0 0 0 0
EXPLICIT CALL:
PUSHJ 17, FIN.
5. F77 SLIST
This is the same as SLIST except that if the number of
elements is less than or equal to zero, no I/O is done.
6. F77 ELIST
This is the same as ELIST except that is the number of
elements is less than or equal to zero, no I/O is done.
18.5.3.10 OPEN and CLOSE Statements, Calling Sequences - The form and
calling sequences for the OPEN and CLOSE FORTRAN statements are:
OPEN statement call:
XMOVEI 16, ARGBLK
PUSHJ 17, OPEN.
18-32
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
CLOSE statement call:
XMOVEI 16, ARGBLK
PUSHJ 17, CLOSE.
where ARGBLK is:
0-1 2-8 9-12 13 14-17 18-35
Negative of
the number
of words in
block not 0
including
this one.
1 0 G type I X H
1 0 G type I X H
1 0 G type I X H
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
1 0 G type I X H
The G field (bits 2 through 8) contains a value that defines the
argument name; the H field (bits 18 through 35) contains an address
that points to the value of the argument. Note that the G field
values for OPEN and CLOSE statements are not the same as those for
other I/O statements.
18-33
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
The numeric codes that may appear in the G field are:
G Field Open Argument G Field Open Argument
01 DIALOG 31 PADCHAR=
02 ACCESS= 32 RECORDTYPE=
03 DEVICE=
04 BUFFERCOUNT= 33 STATUS=
05 BLOCKSIZE= 34 TAPEFORMAT=
06 FILE= 35 READONLY=
07 PROTECTION= 36 UNIT=
10 DIRECTORY= 37 ERR=
| 11 LIMIT= 40 EXIST=
12 MODE= 41 FORMATTED=
13 FILESIZE= 42 NAMED=
| 14 RECORDSIZE= 43 NEXTREC=
| 15 DISPOSE= 44 NUMBER=
| 16 VERSION= 45 OPENED=
| 17 ORGANIZATION= 46 SEQUENTIAL=
| 20 SHARED 47 UNFORMATTED=
21 IOSTAT= 50 NAME=
| 22 ASSOCIATEVARIABLE= 51 KEY=
| 23 PARITY= 52 USEROPEN=
24 DENSITY= 53 DIALOG=
| 25 BLANK= 54 DEFAULTFILE=
| 26 CARRIAGECONTROL= 55 KEYED=
| 27 FORM= 56 NOSPANBLOCKS
| 30 BYTESIZE= 57 MAXREC=
|
18.5.3.11 Memory Allocation Routines - The memory management module
is called to allocate or deallocate memory blocks. There are two
entry points (ALCOR. and DECOR.) that control memory allocation and
deallocation.
When TOPS-20 extended addressing is in effect, ALCOR. and DECOR. can
be used; however, memory will be allocated in FOROT's section instead
of in the user's section. You can use the LINK switch
/OTSEGMENT:NONSHARABLE to put FOROTS in the user's section.
Use the ALCOR. entry to allocate the number of words specified in the
argument block variable. Upon return, AC 0 will contain either the
address of the allocated memory block or -1, which indicates that
memory is not available.
18-34
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
The calling sequence for an ALCOR. call is:
XMOVEI 16, ARGBLK
PUSHJ 17, ALCOR.
where ARGBLK is:
0-1 2-8 9-12 13 14-17 18-35
-1 0
1 0 Reserved type I 0 Address of
number of words
Use the DECOR. entry to deallocate a previously allocated block of
memory; the argument variable must be loaded with the address of the
memory block to be returned.
If the number of desired words is N, ALCOR. actually removes N+2 words
from free storage. The pointer returned points to the third word
(word 2 as opposed to word 0) removed from free storage. The first
two words are used by FOROTS to maintain linked lists of allocated
(using ALCOR.) and free storage, and must not be modified.
The calling sequence for a DECOR. call is:
XMOVEI 16, ARGBLK
PUSHJ 17, DECOR.
where ARGBLK is:
0-1 2-8 9-12 13 14-17 18-35
-1 0
Pointer to word
1 0 Reserved type I 0 containing
address of block
to be returned
18.5.3.12 Channel Allocation and Deallocation Routines - You may
allocate software channels in MACRO programs by means of calls to the
ALCHN. routine and deallocate them by calls to the DECHN. routine.
18-35
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
Values are returned in AC 0.
Use the ALCHN. entry to allocate a particular channel or the next
available channel. The channel to be allocated is passed as an
argument to ALCHN. Zero is passed as an argument to allocate the next
available channel. Allowed channels are 1 through 17 (octal). If the
channel requested is not available, or all channels are in use, ALCHN.
returns with a -1 in AC 0. In normal returns, AC 0 contains the
assigned number.
The calling sequence of an ALCHN. routine is:
XMOVEI 16, ARGBLK
PUSHJ 17, ALCHN.
where ARGBLK is:
0-1 2-8 9-12 13 14-17 18-35
-1 0
Pointer to a word
1 0 Reserved type I 0 containing
the channel #
or zero
Use the DECHN. entry to deallocate a previously assigned channel. The
channel to be released is passed as an argument to DECHN. If the
channel to be deallocated was not assigned by ALCHN. and thus cannot
be deassigned, AC 0 is set to -1 on return.
The calling sequence for a DECHN. routine is:
XMOVEI 16, ARGBLK
PUSHJ 17, DECHN.
where ARGBLK is:
0-1 2-8 9-12 13 14-17 18-35
-1 0
Pointer to a word
1 0 Reserved type I 0 containing
the channel #
to be released
18-36
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
18.6 FUNCTIONS TO FACILITATE OVERLAYS
FOROTS provides a subroutine (FUNCT.) to serve as an interface with
the LINK overlay handler. This subroutine consists of a group of
functions that allow the overlay handler to perform I/O, memory
management, and error message handling. These functions have only one
entry point, FUNCT.; and they are called by the sequence:
XMOVEI 16, ARGBLK
PUSHJ 17, FUNCT.
The format of the ARGBLK is:
-<n+3>,,0
ARGBLK: IFIW 2,address of integer function code
IFIW 17,address of 3-letter ASCII error prefix
IFIW 2,address of status code on return
IFIW type,address of first argument
. . .
IFIW type,address of nth argument
where:
type is the FORTRAN argument type (see Chapter 14)
function code is the number of one of the required functions
error prefix is ignored by FOROTS
status is undefined on the call and set on the return
with one of the values below.
-1 Function not implemented
0 Successful return
1....n Specific error message
When TOPS-20 extended addressing is in effect, FUNCT. can be used;
however, memory will be allocated in FOROTS's section instead of in
the user's section. You can use the LINK switch
/OTSEGMENT:NONSHARABLE to put FOROTS in the user's section.
18-37
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
Table 18-2: Function Numbers and Function Codes
Function
Number Function
(Octal) Mnemonic Function Description
0 ILL Illegal function; returns -1 status
1 GAD Gets a specific segment of memory
2 COR Gets a given amount of memory from
anywhere in the space allocated to the
overlay handler
3 RAD Returns a specific segment of memory
4 GCH Gets an I/O channel
5 RCH Returns an I/O channel
6 GOT Gets memory from the space allocated to
the object-time system
7 ROT Returns memory to the object-time system
10 RNT Gets the initial run time from the
object-time system
11 IFS Gets the initial run time file
specification from the object-time
system
12 CBC Cuts back memory (if possible) to reduce
job size
13 RRS Reads RETAIN status (DBMS)
14 WRS Writes RETAIN status (DBMS)
15 GPG Allocates memory on a page boundary
16 RPG Deallocates memory obtained by function
15
17 GPSI Gets TOPS-20 PSI channel
20 RPSI Returns TOPS-20 PSI channel
21 MPG Gets a contiguous set of pages
22 UPG Returns a contiguous set of pages
Each function of the FUNCT. subroutine is described below. The
arguments described in each of the following functions are what should
be in the addresses pointed to by the argument block described above.
ILL (0) FUNCTION - This function is illegal. The argument block is
ignored, and the status returned is -1.
GAD (1) FUNCTION - This function gets memory from a specific address
in the space allocated to the overlay handler. The arguments are:
arg 1 address of requested memory
arg 2 address of number of words of memory to allocate
A call to GAD with arg 2 equal to -1 requests all available memory.
18-38
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
On return, the status is one of the following:
0 successful allocation
1 not enough memory available
2 memory not available at specified address
3 illegal arguments (such as, address + size is greater
than 256K)
COR (2) FUNCTION - This function gets memory from any available space
allocated to the overlay handler. The arguments are:
arg 1 undefined (address of allocated memory on return)
arg 2 address of size of requested allocation
On return, the status is one of the following:
0 memory allocated
1 not enough memory available
3 illegal argument (that is, size is greater than 256K)
RAD (3) function - This function returns memory at the specified
address within the space allocated to the overlay handler. The
arguments are:
arg 1 address of memory to be return
arg 2 address of size of memory to be returned (in words)
On return, the status is one of the following:
0 successful return of memory
1 memory cannot be returned
3 illegal argument (that is,the address or the size is
greater than 256K)
GCH (4) FUNCTION - This function gets an I/O channel. The arguments
are:
arg 1 undefined (address of channel number allocated on
return)
arg 2 ignored
On return, the status is one of the following:
0 successful channel allocation
1 no I/O channels available
RCH (5) FUNCTION - This function returns an I/O channel. The
arguments are:
arg 1 address of number of channel to be returned
arg 2 ignored
18-39
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
On return, the status is one of the following:
0 channel released
1 invalid channel number
GOT (6) FUNCTION - This function gets memory from the space allocated
to the object-time system. The arguments are:
arg 1 undefined (address of allocated memory on return)
arg 2 address of size of memory requested
On return, the status is one of the following:
0 successful allocation
1 not enough memory available
3 illegal argument (such as, size is greater than 256K)
This function differs from function 1 in that if the object-time
system has two free memory lists, then function 1 is used to allocate
space for links, and this function is used to allocate space for I/O
buffers. Function 1 uses the free memory list for LINK, and function
6 uses the list for the object-time system.
ROT (7) FUNCTION - This function returns memory to the object-time
system. The arguments are:
arg 1 address of memory to be returned
arg 2 address of size of memory to be returned (in words)
On return, the status is one of the following:
0 successful return of memory
1 memory cannot be returned
3 illegal argument (such as, the address or the size is
greater than 256K)
RNT (10) FUNCTION - This function returns the initial run time from
the object-time system. (At the beginning of the program, the
object-time system will have executed a RUNTIM UUO; that result is the
time returned by RNT.) The arguments are:
arg 1 undefined (contains address of initial run time on
return)
arg 2 ignored
On return, the run time is in arg 1, and the status is 0. The status
is 0.
IFS (11) FUNCTION (TOPS-10 only) - This function returns the initial
run-time file specification from the object-time system. (This
initial file specification is the one used to begin the program; that
is, it was given with the system RUN command.) The arguments are:
18-40
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
arg 1 undefined (address of SIXBIT device on return)
arg 2 undefined (address of SIXBIT filename on return)
arg 3 undefined (project-programmer number on return or
address of path block if run from SFD
On return, the status is one of the following:
0 successful return
1 error
This function tells the overlay handler which file to read after the
initial RUN command.
CBC (12) FUNCTION - This function cuts back memory if possible, which
reduces the size of the user job. There are no arguments.
The returned status is:
0 always
RRS (13) FUNCTION
WRS (14) FUNCTION - These functions are reserved for use by DBMS.
GPG (15) FUNCTION - This function gets memory on a page boundary. The
arguments are the same as for FUNCTION 6, GOT.
arg 1 ignored
arg 2 address of number of words of memory to allocate
On return, arg 1 has the address of the allocated memory. It will be
on a page boundary. (That is, it will be a multiple of 1000 octal.)
On return, the status is one of the following:
0 successful
1 not enough memory available
3 illegal argument
RPG (16) FUNCTION - This function returns memory obtained by FUNCTION
15. The arguments are the same as for FUNCTION 7, ROT.
arg 1 address of memory to be returned
arg 2 address of size of memory to be returned (in words)
On return, the status is one of the following:
0 successful return of memory
1 was not allocated
3 illegal argument
GPSI (17) FUNCTION - This function gets the TOPS-20 PSI channel. It
assigns a software interrupt channel number. GPSI provides only
18-41
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
controlled access to the PSI tables. It arranges that the tables
exist and that SIR and EIR have been done, but does not do AIC or any
other JSYS necessary to set up the channel (ATI or MTOPR, for
example).
arg 1 address of channel number to allocate, or -1 to
allocate any user-assignable channel
arg 2 address of level number
arg 3 address of interrupt routine (if the FORTRAN program is
running on a system that supports extended addressing,
the interrupt routine address may be a 30-bit address
in any section, including section 0. Otherwise, the
interrupt address must be an 18-bit address.)
On return, the status is one of the following:
0 allocated OK (arg 1 is the channel number if -1 was
sent)
1 requested channel was already assigned
2 no free channels
3 argument error
RPSI (20) FUNCTION - This function returns the TOPS-20 PSI channel.
It returns a PSI channel allocated by FUNCTION 17. RPSI provides only
controlled access to the PSI tables. It removes the given channel
from the tables. This function does not do DIC or any other JSYS
necessary to remove an interrupt condition from a channel.
arg 1 address of channel number to return
On return, the status is one of the following:
0 OK
1 channel was not allocated
3 argument error
MPG (21) FUNCTION - This function gets a contiguous set of pages. The
pages requested are always allocated from the section FOROTS is in.
The user cannot depend upon this call to either create or destroy the
pages.
arg 1 first page number to allocate. The page number must be
in the range 0 to 777.
arg 2 number of pages to allocate
On return, the status is one of the following:
0 successful allocation of all given pages
1 one or more pages were already allocated
3 illegal argument (bad page number or count)
18-42
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
UPG (22) FUNCTION- This function returns a contiguous set of pages.
The pages returned are considered to be in the section FOROTS is in.
The user cannot depend upon this call to either create or destroy the
pages.
arg 1 first page number to deallocate. The page number must
be in the range 9 to 777
arg 2 number of pages to deallocate
On return, the status is one of the following:
0 successful deallocation of all given pages
1 one or more pages was not allocated by MPG
3 illegal argument (bad page number or count)
18.7 LOGICAL/PHYSICAL DEVICE ASSIGNMENTS
You make FORTRAN logical and physical device assignments at run time,
or standard system assignments are made according to a FOROTS Device
Table, that is, DEVTB. Table 10-3 in Section 10.4.3 shows the
standard assignments contained by the Device Table.
18.8 FOROTS AND INQUIRE BY FILE STATEMENT
See Section 11.7 for a description of the INQUIRE statement.
If no device is given for the FILE= specifier, FOROTS uses DSK: as the
default. If no extension is given, FOROTS uses .DAT. For TOPS-20, if
no generation number is given, FOROTS uses a generation number of 0.
FOROTS determines if the device specified is a disk. If the device is
a disk, the following happens:
o FOROTS determines if a file exists with the file
specification given in the INQUIRE statement. It returns the
answer (either .TRUE. or .FALSE.) in the variable specified
by the EXIST= specifier, if any. If such a file exists,
FOROTS 'expands' the file specification as follows:
o A logical name is translated into a physical device name.
o For TOPS-20, the file specification, which is overlaid by
the user-specified directory, filename, extension, and
generation.
18-43
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
o For TOPS-20, an actual file generation number is
substituted for a generation number of 0, -1, or -2.
The resultant file specification, in string form, is called
the 'full (expanded) file string.'
o FOROTS searches for a match between the file specification
given in the INQUIRE statement and a file specification
associated with a logical unit for which there is a
"connection." This is to determine the values to be returned
for the INQUIRE specifiers OPENED= and NUMBER= (see Section
11.7.3). FOROTS looks at all FORTRAN logical units for which
there is a connection in ascending order, starting with zero.
FOROTS compares the file specification given in the INQUIRE
statement (with FILE= defaults applied) with the exact file
specification given in the OPEN statement (with FILE=
defaults applied) if the following is true:
o The file does not exist on the directory.
o An OPEN statement has been executed and STATUS='UNKNOWN'
and ACCESS='SEQUENTIAL' (see Section 11.3.1).
o No data transfer statements have been executed using the
unit.
If the file exists, FOROTS compares the full file string
associated with the unit with the full (expanded) file string
given in the INQUIRE statement. The file exists if the
following is true:
o An OPEN has been executed with STATUS other than
'UNKNOWN' or ACCESS other than 'SEQUENTIAL'.
o An I/O transfer statement has been executed.
If neither of these two comparisions are successful, FOROTS
returns the current unit number in the variable specified
with the NUMBER= specifier, and returns 'YES' in the variable
specified with the OPENED= specifier. If the same file is
connected on several units, the matching technique described
will return the smallest unit number for which there is a
match.
For non-disk devices specified in the INQUIRE statement file string
specification, FOROTS looks at all the FORTRAN logical units for which
there is a connection in ascending order, starting with zero.
If the device in the file string specified in the INQUIRE statement is
not the user's controlling terminal, FOROTS expands the file
18-44
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
specification given in the INQUIRE statement by translating a logical
name given as the device into its corresponding physical name. It
then compares the device part of this expanded file specification with
the device part of the full (expanded) file string associated with the
logical unit.
If the device is the user's controlling terminal (device 'TTY'),
FOROTS determines if the device associated with the logical unit is
also the user's controlling terminal.
18.9 USEROPEN PROCEDURES
| The USEROPEN keyword in a FORTRAN OPEN statement (see Section 11.3.39)
| provides a way to access RMS-20 facilities that are otherwise not
| available to FORTRAN programs.
|
| The USEROPEN keyword specifies a user-written external procedure that
| controls the opening of a file. It has the form
|
| USEROPEN = procedure-name
|
| where
|
| procedure-name is the symbolic name of a user-written function. The
| procedure must be declared in an EXTERNAL statement.
|
| When an OPEN statement (with or without the USEROPEN keyword) is
| executed on an RMS file, FOROTS uses the OPEN statement keywords to
| establish the RMS File Access Block (FAB), the Record Access Block
| (RAB), and optionally one or more Extended Argument Blocks (XABs).
|
| If a USEROPEN keyword is included in the OPEN statement, FOROTS
| establishes defaults for some of the data structure fields, then calls
| your USEROPEN routine instead of opening the file according to its
| normal defaults. The USEROPEN routine can then provide additional
| parameters to RMS, as well as read values from the FAB, RAB, and XABs
| as returned by RMS.
|
| FOROTS will call a USEROPEN routine with an argument list of the
| following form:
|
| -3,,0
| xM: IFIW TP%INT,address of unit
| IFIW TP%LBL,address of FAB
| IFIW TP%LBL,address of RAB
|
| Using these arguments, the USEROPEN routine can then perform the
| following operations:
|
18-45
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
| 1. Modify the FAB/RAB or XAB(s). (Optional)
|
| 2. Issue the $OPEN or $CREATE RMS service calls (depending on
| whether the file exists or is to be created), followed by the
| $CONNECT RMS service call to prepare the file for record I/O.
| (Required)
|
| 3. Check the status indicators returned by RMS after each of the
| above service calls. Your procedure should return
| immediately with the RMS error code in AC0 if RMS returns a
| failure status. (Required)
|
| 4. Read file attribute information returned by RMS to the FAB,
| RAB, or XAB(s). (Optional)
|
| 5. Return a success or failure status value in AC0 to FOROTS.
| (Required). AC0 must be zero on success.
|
|
|
| 18.9.1 Example of a USEROPEN
|
| The following example shows a FORTRAN OPEN statement calling a
| USEROPEN routine UOPN, which changes the default "No duplicate"
| attribute for the primary index in an indexed file.
|
| EXTERNAL UOPN
| OPEN (UNIT=1,FILE='IDX.DAT',ORGANIZATION='INDEXED',
| 1 STATUS='NEW',KEY=(1:10),RECL=40,
| 1 USEROPEN=UOPN)
|
| A USEROPEN routine may cause a first-time invocation of RMS. To
| ensure that RMS is invoked compatibly with FOROTS, the following code
| must be placed in all USEROPEN and MACRO routines that may invoke RMS:
|
| SEARCH RMSINJ ;RMS/dynamic library universal file
| .REQUIRE SYS:RMSZER ;Dynamic library boot-strap files
| .REQUIRE SYS:RTLZNM
| .REQUIRE SYS:ZERBOO
| .REQUIRE SYS:DYNBOO
|
| The following function UOPN creates an RMS indexed file after setting
| the FLG XAB field in the primary index XAB to allow duplicate primary
| keys:
|
| TITLE UOPN
| SEARCH RMSINJ,MACSYM,MONSYM
| INTERN UOPN
| .REQUIRE SYS:RMSZER
| .REQUIRE SYS:RTLZER
18-46
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
| .REQUIRE SYS:ZERBOO
| .REQUIRE SYS:DYNBOO
| STDAC. ;Standard AC definitions
| T0==0
| UOPN: XMOVEI T1,@1(16) ;Get FAB address
| MOVX T2,FB$SUP ;Get "Supersede existing" bit
| $STORE T2,FOP,<(T1)> ;Set in FAB
| $FETCH T1,XAB,<(T1)> ;Get address of 1st XAB in chain
| MOVX T2,XB$DUP ;Get "allow dupe" bit
| $STORE T2,FLG,<(T1)> ;Set in XAB
| $CREATE @1(16) ;Create the file
| CAIL T2,ER$MIN ;Error?
| JRST BADRET ;Yes
| $CONNECT @2(16) ;CONNECT RAB
| CAIL T2,ER$MIN ;Error?
| JRST BADRET ;Yes
| SETZ T2, ;Return success
| POPJ P,
| BADRET: MOVE T0,T2 ;Return error code in AC0
| POPJ P,
| END UOPN
|
| To allow an existing file to be superseded with a higher generation,
| the routine first turns on the FB$SUP bit in the FAB. It then fetches
| the address of the first XAB in the XAB chain (in this case the only
| XAB) and sets the XB$DUP bit in the FLG field to allow duplicate
| primary keys (the RMS/FOROTS default is to disallow duplicate primary
| keys.)
|
| For local RMS indexed files, the XAB field of the FAB will always
| point to the first key XAB in any XAB chain. For all remote files,
| the XAB field of the FAB points to a CONFIG XAB containing network
| system information; the NXT field of the CONFIG XAB will point to the
| start of the key XAB chain. Refer to the RMS-20 Programmer's
| Reference Manual and the TOPS-20 RMS User's Guide for more information
| of RMS data structures.
|
|
|
| 18.9.2 RMS/FOROTS Data and Control Structures
|
| When RMS is invoked to access a file on a particular unit, FOROTS
| allocates and initializes the following RMS data structures for each
18-47
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
| such unit:
|
| o FAB - File Access Block
|
| o RAB - Record Access Block
|
| o XAB - Extended Attribute Block. One or more are allocated if
| the file is indexed or remote.
|
| In addition, a statically allocated NAM and TYP block are linked to a
| unit's FAB block during OPEN processing.
|
| Values in these control structures are set or defaulted by FORTRAN as
| described below. In addition, RMS may update these control structures
| with information derived from the file after it is opened.
|
| Unless an error intervenes, these data structures are not deallocated
| until the unit is closed. User-written subroutines and USEROPEN
| functions may alter or examine field values in these structures, but
| they must not alter their allocation. Caution should be exercised
| when changing fields that have been set as a result of FORTRAN
| keywords (such as MRS or FAC values), since unpredictable results may
| occur during subsequent I/O. In general, if a desired value can be
| obtained through the use of a FORTRAN keyword, use the keyword.
|
| The following RMS FAB, RAB and XAB fields are either initialized by
| FORTRAN and/or examined upon return from an RMS service call. Fields
| not listed here take the RMS defaults, or are returned by RMS.
|
|
| FAB FIELDS
|
| Field Name FORTRAN OPEN keyword/value
|
|
| F$BSZ Bytesize n if BYTESIZE=n, else 7 for TOPS-20, 8 for
| VMS files
| F$CTX Context Reserved for Digital
| F$FAC File access Set at OPEN depending on STATUS, ACCESS
| and READONLY or SHARED keywords. Set to
| FB$GET for read access files, else to
| FB$GET+FB$PUT+FB$DEL+FB$UPD+FB$TRN
| FB$BRO also for remote non-RMS files
| F$FNA File specification FILE= filename + DEFAULTFILE= file name if
| string address present, else FORnn.DAT if neither given
18-48
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
| F$FOP File-processing options
| FB$SUP Supersede Set at OPEN depending on STATUS and
| ACCESS keywords
| FB$DLT Delete on close Set at CLOSE depending on DISPOSE keyword
| in OPEN or CLOSE, or STATUS keyword in
| CLOSE
| FB$SPL Spool to printer Set at CLOSE depending on DISPOSE keyword
| in OPEN or CLOSE, or STATUS keyword in
| CLOSE
| FB$SCF Submit command Set at CLOSE depending on DISPOSE keyword
| in OPEN or CLOSE, or STATUS keyword in
| CLOSE
| F$MRS Maximum record size For RMS files, set to n if RECORDSIZE=n,
| else to 0
| F$MRN Maximum record number For RMS files, set to n if MAXREC=n, else
| to 0
| F$NAM Name block address Set to address of name block; both the
| expanded and resultant string areas are
| set up
| F$TYP Type block address Set to address of type block for remote
| non-RMS files. T$CLA is set to TY$IMA
| F$ORG File organization FB$IDX if ORGANIZATION='INDEXED'
| FB$REL if ORGANIZATION='RELATIVE'
| FB$SEQ if ORGANIZATION='SEQUENTIAL' or
| omitted
| F$RAT Record attributes
| FB$BLK Do not cross page 1 if NOSPANBLOCKS
| boundaries
| F$RFM Record format FB$FIX if RECORDTYPE='FIXED'
| FB$VAR if RECORDTYPE='VARIABLE'
| FB$STM if RECORDTYPE='STREAM'
| FB$FIX if no RECORDTYPE and ORGANIZATION
| is 'RELATIVE' or 'INDEXED'
| F$SHR File sharing
| FB$PUT Allow other PUTs 1 if SHARED
| FB$GET Allow other GETs 1 if SHARED
18-49
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
| FB$DEL Allow other DELETEs 1 if SHARED
| FB$UPD Allow other UPDATEs 1 if SHARED
| F$XAB Extended attribute 0 if the file is not indexed or is not
| remote. For all remote files, contains the
| address of a CONFIG XAB, whose X$NXT
| points to the beginning of the key XAB
| chain, if any. For local indexed files,
| contains the address of the first key
| XAB.
| RAB FIELDS
|
| Field Name FORTRAN OPEN keyword/value
|
|
| R$BKT Bucket code Set to n during remote non-RMS processing
| R$CTX Context Reserved for DIGITAL
| R$FAB FAB address Set to address of file argument block
| R$KBF Key buffer address Set to address of record number if
| ACCESS='DIRECT' or address of key data
| if ACCESS='KEYED'
| R$KRF Key of reference Set to key of reference for indexed files
| R$KSZ Key size Set to size of key for indexed files
| R$MBF Multibuffer count n if BUFFERCOUNT=n, else 0
| R$RAC Record access mode RB$KEY if ACCESS='DIRECT' or 'KEYED'
| RB$SEQ if ACCESS='SEQUENTIAL', 'APPEND'
| or ACCESS is omitted
| RB$BLK for remote non-RMS files
| R$RBF Record buffer address Set during READ or WRITE
| R$ROP Record-processing options
| RB$EOF End-of-file 1 if ACCESS='APPEND'
| RB$KGE Key .GE. If indexed READ
| RB$KGT Key .GT. If indexed READ
| R$RSZ Record size Set during READ and WRITE
18-50
USING THE FORTRAN OBJECT TIME SYSTEM (FOROTS)
| R$UBF User record area Set during READ and WRITE
| address
| R$USZ User record area size Set during READ and WRITE
|
| The following KEY XAB fields are set by FORTRAN for indexed files:
| XAB FIELDS
|
| Field Name FORTRAN OPEN keyword/value
|
|
| X$DTP Key datatype XB$STG if CHARACTER (default), else
| XB$IN4 if INTEGER
| X$FLG Key options flags XB$DUP!XB$CHG for each secondary index
| X$REF Key of reference Set depending on OPEN KEY= position of
| key specifier
| X$POS Key position From OPEN KEY= specifier
| X$SIZ Key size From OPEN KEY= specifier
| X$NXT Link address Address of next XAB in chain, or 0
18-51
19-1
CHAPTER 19
USING THE FORTRAN REAL-TIME SOFTWARE (TOPS-10 ONLY)
19.1 INTRODUCTION
The FORRTF library subroutines are designed to allow the timesharing
FORTRAN user to do real-time programming on TOPS-10 systems. These
subroutines, described in Section 19.3, are listed below:
LOCK
RTINIT
CONECT
RTSTRT
BLKRW
RTREAD
RTWRIT
STATO
STATI
RTSLP
RTWAKE
DISMIS
DISCON
UNLOCK
With these subroutines, the timesharing job can dynamically connect
real-time devices to the Priority Interrupt (PI) system, respond to
these devices at interrupt level, remove the devices from the PI
system, and change their PI level. Use of these routines requires
that you have real-time privileges and are able to lock your job in
core. The privilege bits required are:
JP.RTT (bit 13) - real-time privileges
JP.LCK (bit 14) - locking privileges
The number of real-time devices that can be handled at one time is an
assembly-time constant (RTDEVN) in the FORRTF source. The
DIGITAL-distributed software has RTDEVN equal to 2, but it can be
changed (up to 6) by editing the statement "RTDEVN==2" in FORRTF.MAC
and reassembling.
19-1
USING THE FORTRAN REAL-TIME SOFTWARE (TOPS-10 ONLY)
The error messages output by FORRTF can be in either full message
format or coded format (refer to Table 19-1). Use of the code and
format saves over 100 words of run-time core. If core is limited,
reassembly of FORRTF.MAC with the assembly-time constant SHORT changed
from the DIGITAL-distributed 0 (full format) to -1 (coded format)
accomplishes the core saving.
On multiprocessor systems, the real-time traps apply only to the
processor specified by the job's CPU specification. If the
specification indicates more than one processor, the specification is
changed to indicate CPU0. Note that the priority interrupt channel is
only for the indicated CPU.
19.2 USING FORRTF
Users of FORTRAN-10 real-time software must consider the following:
1. Use of memory
2. Device control in block or single mode
3. Priority-interrupt levels
4. Masks
19.2.1 Memory
The job being executed must be locked in memory with the LOCK
subroutine (see Section 19.3.1). Any data being read into memory can
only be read into the low segment and above the protected job data
area (the first 140 locations). The BLKRW subroutine (see Section
19.3.5) tests the validity of the locations specified to receive data
in block reading to ensure that no overwritings occur.
However, when in block mode, the block pointer must be reset before
dismissing the end-of-block interrupt; otherwise, all memory could be
overwritten.
19.2.2 Modes
Real-time jobs can control their devices in one of two ways: block
mode or single mode. In block mode, an entire block of data is read
or written before the user-interrupt routine is run; whereas, in
single mode, the user-interrupt program is run every time the device
interrupts.
19-2
USING THE FORTRAN REAL-TIME SOFTWARE (TOPS-10 ONLY)
There are two types of block mode: fast-block mode and normal-block
mode. A device in fast-block mode requires that a PI channel be
dedicated entirely to itself.
19.2.3 Priority-Interrupt Levels
Priority-interrupt levels 1 through 6 are legal depending on the
system configuration. The lower the number of the level, the higher
the priority of that level. Programs that execute for a long time
should not be put on high-priority interrupt levels, since they could
cause other real-time programs on lower levels to lose data.
Specification of the PI level as zero for a particular device causes
the device to be removed from the PI system.
19.2.4 Masks
For a description of the bits included in the startmsk and intmsk
parameters of RTSTRT and the status word in STATO and STATI, see the
DECsystem-10 Hardware Reference Manual.
19.3 SUBROUTINES
Each of the 14 subroutines associated with FORTRAN real-time software
is described briefly in Sections 19.3.1 through 19.3.14. These
subroutines have been programmed to be compatible with programs
written according to the TOPS-10 Monitor Calls Manual.
19.3.1 LOCK
LOCK locks the job in memory and allocates and initializes the
internal controlling tables for all real-time devices. LOCK must be
called before any of the other real-time routines, and must be called
exactly once.
The form of the LOCK subroutine is:
CALL LOCK
19.3.2 RTINIT
RTINIT initializes the internal tables controlling a real-time device.
RTINIT must be called for each individual device being used.
19-3
USING THE FORTRAN REAL-TIME SOFTWARE (TOPS-10 ONLY)
The form of the RTINIT subroutine is:
CALL RTINIT (unit, dev, pi, trpadr, intmsk)
where:
unit is the real-time device unit number (any number from 1
to RTDEVN). This number is not connected in any way
with the FORTRAN logical unit number.
dev is the device code for the real-time device (see the
DECsystem-10 Hardware Reference Manual).
pi is the priority-interrupt level on which the real-time
device is to be run. Each individual device in
fast-block mode must have a level dedicated to itself.
If the level is equal to zero, the device will be
removed from the priority-interrupt system altogether.
If it is necessary to connect one device to several
levels simultaneously, a negative value for PI tells
the system not to remove any other occurrences of the
device from any other (or the same) PI level. (Note
that this counts as another real-time device.)
trpadr is the address of a FORTRAN entry to which real-time
interrupts are to trap. This can be a function or
subroutine subprogram. Any variables that must be
shared between the user-level code and the
interrupt-level routine must be passed by means of
COMMON. Passing them as parameters causes disastrous
results.
intmsk is the mask of all interrupting flags for the real-time
device. This is actually set up by RTSTRT and should
be zero whenever the real-time device is inactive (that
is, in a call to RTINIT, except in the case of
fast-block mode). In fast-block mode, intmsk must be
set to -1.
19.3.3 CONECT
CONECT tells the system to connect a real-time device to the proper PI
level and sets up several elements of the device-controlling tables.
Every device must be CONNECTED.
The form of the CONECT subroutine is:
CALL CONECT (unit, mode)
19-4
USING THE FORTRAN REAL-TIME SOFTWARE (TOPS-10 ONLY)
where:
unit is the real-time device unit number (see RTINIT).
mode is either:
-2, write a block of data, fast mode; then interrupt.
-1, write a block of data, normal mode; then interrupt.
0, interrupt every word
+1, read a block of data, normal mode; then interrupt.
+2, read a block of data, fast mode; then interrupt.
19.3.4 RTSTRT
RTSTRT can be used to start a real-time device, as well as to stop it
and zero its interrupt mask. A device must be started to be used and
should be stopped before it is disconnected. The form of the RTSTRT
subroutine is:
CALL RTSTRT (unit, startmsk, intmsk)
where:
unit is the real-time device unit number (see RTINIT).
startmsk is the flags necessary to start the device (see
the DECsystem-10 Hardware Reference Manual). If
the device is being stopped, this parameter should
be zero.
intmsk is the mask of all interrupting bits for the
particular device (see the DECsystem-10 Hardware
Reference Manual). If the device is in fast-block
mode and being started, intmsk should equal -1;
if, however, the device in any mode is being
stopped, the parameter must be 0.
19.3.5 BLKRW
BLKRW is used with either of the block modes. It sets up the size and
starting address of the data block being handled. A new count and
starting address must be set up each time the current one runs out.
The form of the BLKRW subroutine is:
CALL BLKRW (unit, count, blkadr)
where:
19-5
USING THE FORTRAN REAL-TIME SOFTWARE (TOPS-10 ONLY)
unit is the real-time device unit number (see RTINIT).
count is the number of words to be read or written.
blkadr is the array into which the data is to be written or
from which it is to be read.
19.3.6 RTREAD
RTREAD, used with a device in single mode, reads a single word of data
from the device.
The form of the RTREAD subroutine is:
CALL RTREAD (unit, datadr)
where:
unit is the real-time device unit number (see RTINIT).
datadr is the address of the location in which to store the
data read.
19.3.7 RTWRIT
RTWRIT sends a single word of data to a real-time device in single
mode.
The form of the RTWRIT subroutine is:
CALL RTWRIT (unit, datadr)
where:
unit is the real-time device unit number (see RTINIT).
datadr is the location of the data word to be sent to the
device.
19.3.8 STATO
STATO sends the specified status word to the status register of a
real-time device.
The form of the STATO subroutine is:
19-6
USING THE FORTRAN REAL-TIME SOFTWARE (TOPS-10 ONLY)
CALL STATO (unit, statadr)
where:
unit is the real-time device unit number (see RTINIT).
statadr is the location of the word of status bits to be sent
to the real-time device.
19.3.9 STATI
STATI reads the current device status bits into the location specified
for inspection by the FORTRAN program.
The form of the STATI subroutine is:
CALL STATI (unit, adr)
where:
unit is the real-time device unit number (see RTINIT).
adr is the location into which the device status bits are
to be read.
19.3.10 RTSLP
RTSLP is called from the timesharing level and causes the FORTRAN job
to sleep until RTWAKE is called from interrupt level. The program
goes to sleep for the specified number of seconds (up to 60). When it
wakes up, it checks to see if RTWAKE has been called from interrupt
level. If RTWAKE has been called, RTSLP returns to the calling
program; otherwise the job goes back to sleep again.
The form of the RTSLP subroutine is:
CALL RTSLP (time)
where:
time is the length of sleep time in seconds.
19.3.11 RTWAKE
RTWAKE is called at interrupt level to wake up the FORTRAN program.
19-7
USING THE FORTRAN REAL-TIME SOFTWARE (TOPS-10 ONLY)
The form of the RTWAKE subroutine is:
CALL RTWAKE
19.3.12 DISMIS
DISMIS dismisses the interrupt currently being processed. The
user-interrupt routine must be sure to dismiss the interrupt that
causes its execution to begin.
The form of the DISMIS subroutine is:
CALL DISMIS
19.3.13 DISCON
DISCON disconnects a real-time device from its PI level. All devices
should be disconnected through calls to DISCON before the job is
terminated.
The form of the DISCON subroutine is:
CALL DISCON (unit)
where:
unit is the real-time device unit number (see RTINIT).
19.3.14 UNLOCK
UNLOCK unlocks the job from core. When execution of a job is
complete, the job is automatically unlocked before the return to the
monitor. The UNLOCK subroutine provides a method to unlock a job
before execution is complete. Note that all real-time device handling
must be finished before the job is unlocked.
The form of the UNLOCK subroutine is:
CALL UNLOCK
19.3.15 Error Messages
Table 19-1 lists real-time software error messages, including the code
format, the full message format, and the subroutine in which the
19-8
USING THE FORTRAN REAL-TIME SOFTWARE (TOPS-10 ONLY)
message occurs.
19-9
USING THE FORTRAN REAL-TIME SOFTWARE (TOPS-10 ONLY)
Table 19-1: Error Messages - Code Format and Full Message Format
Subroutine in
which message
Code Format Full Message Format occurs
1 ?ILLEGAL UNIT NUMBER. "RTDEVN"
TO HANDLE MORE DEVICES,
REASSEMBLE FORRTF WITH A
LARGER
A ?ERROR COMES FROM THE
SUBROUTINE "subroutine name"
2 ?RTINIT MUST BE CALLED BEFORE CONECT
CONECT
3 ?CONECT MUST BE CALLED BEFORE RTSTRT,BLKRW
RTSTRT OR BLKRW
4 ?REAL TIME BLOCK OUT OF BOUNDS
A ?END OF BLOCK TOO HIGH BLKRW
[such as, overwrites some program
or in high segment]
B ?END OF BLOCK TOO LOW,
such as, start address less
than 140
5 ?JOB CANNOT BE LOCKED IN LOCK
CORE
A ?JOB NOT PRIVILEGED
B ?NOT ENOUGH CORE AVAILABLE
FOR LOCKING
6 ?APR ERROR AT INTERRUPT
LEVEL
A ?PDL OVERFLOW
B ?ILLEGAL MEMORY REFERENCE
7 ?RTTRP ERROR
realtime trap error of the
following sort
A ?ILLEGAL PI NUMBER
PI channel not available
B ?TRAP ADDRESS OUT OF BOUNDS
C ?SYSTEM LIMIT FOR REALTIME
DEVICES EXCEEDED
D ?JOB NOT LOCKED IN CORE OR NOT
PRIVILEGED
E ?DEVICE ALREADY IN USE BY
ANOTHER JOB
19-10
USING THE FORTRAN REAL-TIME SOFTWARE (TOPS-10 ONLY)
0 ?OCCURRED IN THE DISCON DISCON
ROUTINE
1 ?OCCURRED IN THE CONECT CONECT
ROUTINE
8 A ?NOT ENOUGH CORE AVAILABLE
FOR THE CONTROL BLOCKS LOCK
B ?NOT ENOUGH CORE AVAILABLE
19-11
A-1
APPENDIX A
SUMMARY OF FORTRAN STATEMENTS
This appendix summarizes the forms of all FORTRAN statements and
provides a section reference where each statement is described in
detail.
A-1
SUMMARY OF FORTRAN STATEMENTS
A-2
SUMMARY OF FORTRAN STATEMENTS
A-3
SUMMARY OF FORTRAN STATEMENTS
A-4
APPENDIX B
ASCII-1968 CHARACTER CODE SET
The character code set defined in the X3.4-1968 Version of the
American National Standard for Information Interchange (ASCII) is
given in this appendix.
B-1
ASCII-1968 CHARACTER CODE SET
B-2
ASCII-1968 CHARACTER CODE SET
B-3
ASCII-1968 CHARACTER CODE SET
B-4
APPENDIX C
COMPILER MESSAGES
The FORTRAN compiler issues two types of messages: warning and fatal
error. While compiling the program, if the compiler encounters a
situation that does not prevent it from completing the compilation,
but does warrant your knowing about, it prints a warning message and
continues compilation. If, however, the problem in your program is
such that compilation cannot continue, the compiler prints a
fatal-error message and stops compilation of the program. Whenever a
fatal error is generated a relocatable object module will not be
produced.
Compiler messages are printed in the following form:
?FTNxxx LINE:n text
or
%FTNxxx LINE:n flag: text
where:
? indicates a fatal message
% indicates a warning message
FTN is the FORTRAN mnemonic
xxx is the 3-letter mnemonic for the error message
Line:n is the optional line number where the error occurred
text is the explanation of error
flag: is the prefix for warning messages generated when the
compatibility flagger is invoked. This prefix describes
the type of incompatibility the message refers to, and can
be one of the following:
o Extension to Fortran-77:
o VMS incompatibility:
o Fortran-77 and VMS:
See Section 16.6 for more information on the compatibility flagger.
C-1
COMPILER MESSAGES
Square brackets ([ ]) in this appendix signify variables and are not
output on the terminal.
Fatal Errors
Each fatal error in the following list is preceded by ?FTN on the user
terminal and on listings. They are presented here in alphabetical
order.
ABD [symbolname] has already been defined [definition]
The usage given conflicts with current information about the
symbol. For example, a symbol defined in an EQUIVALENCE
statement cannot be referenced as a subprogram name.
AHE IF at line [number] already has ELSE
AOA Assumed-size arrays only allowed in subprograms
ASA Assumed-size arrays cannot be used
ATL ARRAY [name] too large
The total amount of memory necessary to accommodate this
array is greater than 512P.
AWN Array reference [name] has wrong number of subscripts
The array was defined to have more or fewer dimensions than
the given reference.
BOV Statement too large to classify
To determine statement type, some portion of the statement
must be examined by the compiler before actual semantic and
syntactic analysis begins. During this classification, the
entire portion of the required statement must fit into the
internal statement buffer (large enough for a normal 20-line
statement).
This error message is issued when the portion of a given
statement required for classification is too large to fit in
the buffer. Once FORTRAN-10/20 has classified a statement,
there is no explicit restriction on its length.
CER Compiler error in routine [name]
Submit an SPR for any occurrence of this message.
CEL Character entry points must have the same length
C-2
COMPILER MESSAGES
CEN Character expression used where numeric expression required
CEX Constant or constant expression required
CFF Cannot find file
The file referenced in an INCLUDE statement was not found.
CFL Reference to character function [name] must have a fixed
length
CNE Character and numeric entry points cannot be mixed
CPE Checksum or parity error in [source/listing/object] file
[name]
CQL No closing quote in character constant
CSA Can't split string across numeric and character variables
CSF Illegal statement function reference in CALL statement
DDA [symbolname] is duplicate dummy argument
DDN DO loops too deeply nested - reduce nesting
DFC Variable dimension [name] must be scalar, defined as formal
or in COMMON
DFD Double [type] name illegal
Duplicate fields were encountered in an INCLUDE file
specification.
DIA DO index variable [name] is already active
In any nest of DO loops, a given index variable may not be
defined for more than one loop.
DID Cannot initialize a dummy parameter in DATA
DLN Optional data value list not supported
The extended FORTRAN statement form that allows data values
to be defined in type specification statements is not
supported by FORTRAN-10/20.
DNL Implied DO specification without associated list of
variables
DPR Dummy parameter [name] referenced before definition
C-3
COMPILER MESSAGES
DSF Argument [name] is same as FUNCTION name
DTI The dimensions of [arrayname] must be of the type integer
DVE Cannot use dummy variable in EQUIVALENCE
ECS [variable] EQUIVALENCE-d to COMMON is illegal in SAVE
statement
ECT Attempt to enter [symbolname] into COMMON twice
EDN Expression too deeply nested to compile
EID ENTRY statement illegal inside a block IF or DO loop
EIL Expression illegal in an input list
EIM ENTRY statement illegal in main program
ENF Label [number] must refer to an executable statement, not a
FORMAT
ETF Enter failure [number] [filespec]
EXB EQUIVALENCE extends COMMON block [name] backwards
FEE Found [symbol] when expecting either [symbol] or [symbol]
General syntax error message.
FER [file error text]
An error has occured when processing a command file
specification.
FID Can't initialize character function name
FNE Label [number] must refer to a FORMAT, not an executable
statement
FWE Found [symbol] when expecting [symbol]
IAC Illegal ASCII character [character] in source
IAL Incorrect argument type for library function [name]
IAN Illegal assignment between character and numeric data
IBD Illegal substring bound in DATA statement
IBK Illegal statement in BLOCK DATA subprogram
C-4
COMPILER MESSAGES
ICL Illegal character [character] in label field
ICN Illegal combination of character and numeric data
IDN DO loop at line: [number] is illegally nested
You are attempting to terminate a DO loop before terminating
one or more loops defined after the given one.
IDS Implicit DO indices may not be subscripted
IDT Illegal or misspelled data type
IDV Implied DO index is not a variable
IED Inconsistent EQUIVALENCE declaration
The given EQUIVALENCE declaration would cause some symbolic
name to refer to more than one physical location.
IFD INCLUDEd files must reside on disk
IFE [INCLUDE file error]
This error occured while trying to open the specified
INCLUDE file on the DECSYSTEM-20.
IFS Illegal format specifier
IID Non-integer implied DO index
IIP Illegal implicit specification parameter
IIS Incorrect INCLUDE switch
ILF Illegal statement after logical IF
Refer to Section 9.2.2 for restrictions on logical IF object
statements.
IND Improper nesting: DO at line [number] has not terminated
INI Improper nesting: IF at line [number] has not terminated
INN INCLUDE statements may not be nested
IOC Illegal operator for character data
IOD Illegal statement used as object of DO
ION Numeric operand of concatenation operator
C-5
COMPILER MESSAGES
IOR Substring bound out of range
IQB INQUIRE - both UNIT and FILE keywords were specified
IQN INQUIRE - neither UNIT nor FILE keywords were specified
ISD Illegal subscript expression in DATA statement
Subscript expressions may be formed only with implicit DO
indexes and constants combined with +, -, *, or /.
ISN [symbolname] is not [symboltype]
The symbol cannot be used in the attempted manner.
ISS [variable] illegal in SAVE statement
ITL Illegal transfer into loop to label [number]
IUT Program units may not be terminated within INCLUDEd files
IVC Invalid character constant
IVH Invalid hollerith constant
IVP Invalid PPN
IXM Illegal mixed mode arithmetic
Complex and double-precision cannot appear in the same
expression.
IXS Illegal [OPEN specifier] specifier
IZM Illegal [datatype] size modifier [number]
KA FORTRAN will not run on a KA
KAS FORTRAN can not compile for a KA
LAD Label [number] already defined at line: [number]
LED Illegal list directed [statement type]
LFA Label arguments illegal in FUNCTION or array reference
LGB Lower bound greater than upper bound for array [name]
LLS Label too large or too small
Labels cannot be 0 or greater than five digits.
C-6
COMPILER MESSAGES
LND Label [number] must refer to a [statement], not a
declaration
LNI List directed I/O with no I/O list
LTL Too many items in list - reduce number of items
In rare instances, a combination of long lists in a single
statement can exhaust the syntax stack.
MCE More than 1 COMMON variable in EQUIVALENCE group
MSP Statement name misspelled
MST [OPEN specifier] must be [integer or array]
MWL Attempt to define multiple RETURN without formal label
arguments
NCC Can't store numeric constant in character variable
NCF Not enough core for the file specs. Total K needed =
[number]
NEX No exponent after D or E in constant
NFS No filename specified
The INCLUDE statement requires a filename.
NGS Cannot get segment [segment name] - error code [GETSEG error
code]
This message means the system is unable to GETSEG one of the
compiler segments on the DECsystem-10.
NIF No matching IF
NIO NAMELIST directed I/O with I/O list
NIR Repeat count must be an unsigned integer
NIU Non-integer unit number in I/O statement
NLF Wrong number of arguments for library function [name]
NLS [variable] may not be declared length star
NMD No matching DO
NNA NAMELIST not allowed in ENCODE, DECODE, and REREAD
C-7
COMPILER MESSAGES
NNF No statement number on FORMAT
NNN NML= must specify a NAMELIST
NRC Statement not recognized
NUO .NOT. is a unary operator
NWB Numeric variable must be aligned on word boundary
NWD Incorrect use of * or ? in [filespec]
NYI Not yet implemented
OAG Octal or logical argument illegal to generic function
OBO [variable] may only be specified once
OPW OPEN/CLOSE parameter [name] is of wrong type
OUB Only upper bound of last dimension of [arrayname] may be
asterisk
PD6 FORTRAN will not run on PDP6
PIC The DO parameters of [index name] must be integer constants
PN4 Project number must be 4 in ppn
This error is for DECsystem-10 file specifications on the
DECSYSTEM-20.
PRF Protection failure [number] [filespec]
PTL Program too large
The program unit takes up more than 512P.
QEF Quota exceeded or disk full [number] [filespec]
RDE Rib or directory error [number] [filespec]
RFC [function name] is a recursive function call
RIC Complex constant cannot be used to represent the real or
imaginary part of a complex constant
RUS Relational expression illegal as UNIT specifier
SAD Array [name] - signed dimensions may appear only as constant
range limits
C-8
COMPILER MESSAGES
SMC Size modifier conflict for variable [name]
SNC Substring of non-character variable
SNL [statement name] statements may not be labeled
SOR Subscript out of range
STD Statement [number] is a declaration
TDO [symbol type] type declaration out of order
TFL Too many FORMAT labels specified
UCE User core exceeded at location [address] in phase [segment]
while processing statement [number]
UEC Label [number] previously used in executable context
UFC Label [number] previously used in FORMAT context
UKW Unrecognized keyword
UMP Unmatched parentheses
UNS UNIT may not be specified
USI [symbol type] [symbol name] used incorrectly
The given symbol cannot be used in this way.
VNA Subscripted variable in EQUIVALENCE, but not an array
VSE EQUIVALENCE subscripts must be integer constants
VSO Variable dimension allowed in subprograms only
WIF [I/O type] is illegal with internal files
ZLD Zero-trip DO loop illegal in DATA statement
Warning Messages
Each warning message in the following list is preceded by %FTN on the
user terminal and on listings. They are presented here in
alphabetical order.
ACB Argument out of range of CHAR, high order bits ignored
ADS Variable [name] already declared in SAVE statement
C-9
COMPILER MESSAGES
AGA Opt - object variable, of assigned GOTO without optional
list, was never assigned
AIL Illegal length argument for ICHAR, first character used
AIS Extension to Fortran-77: Apostrophe in I/O specifier
ANS VMS incompatibility: ASSOCIATEVARIABLE not set by VMS on
OPEN
CAI COMPLEX expression used in arithmetic IF
CAO Consecutive arithmetic operators illegal
CAP Extension to Fortran-77: Consecutive arithmetic operators
CCC Fortran-77 and VMS: Carriage control character
CCN CHARACTER constant used where numeric expression required
CIS Conflicting INCLUDE switches
CNM Character and numeric variables mixed
CNS Extension to Fortran-77: Concatenation with variable of
non-specific length
COS Extension to Fortran-77: Comment on statement
COV Extension to Fortran-77: Assigned variable appears in
character expression
CSM Extension to Fortran-77: Comma field separator is missing
CTR Complex terms used in a relational other than EQ or NE
The result of the other relational operators with complex
operands is undefined.
CUO Constant underflow or overflow
This message is issued when overflow or underflow is
detected as the result of building constants or evaluating
constant expressions at compile time.
DEB Extension to Fortran-77: DEBUG lines
DFN VMS incompatibility: Default file name on VMS differs from
Fortran-10/20
DII Previous declaration of intrinsic function is ignored
C-10
COMPILER MESSAGES
DIM Possible DO index modification inside loop
A program that does this may be incorrectly compiled by the
optimizer, since it assumes that indexes are never modified.
Note that the number of iterations is calculated at the
beginning of the loop and is never affected by modification
of the index within the loop.
DIS Opt - program is disconnected - optimization discontinued
Submit an SPR if this message occurs.
DOW Extension to Fortran-77: DO WHILE statement
DPE VMS incompatibility: Different precedence in exponentiation
DWE Fortran-77 and VMS: Default widths with edit descriptor
[descriptor]
DWL Extension to Fortran-77: DO without statement label
DXB DATA statement exceeds bounds of array [name]
EDD Extension to Fortran-77: END DO statement
EDS Extension to Fortran-77: DECODE statement
EDS Extension to Fortran-77: ENCODE statement
EDX Fortran-77 and VMS: FORMAT edit descriptor [descriptor]
EOC Fortran-77 and VMS: Exponential operator ^
EXD Extension to Fortran-77: Transfer of control into DO loop at
label [label]
FAR Extension to Fortran-77: Format in numeric array
FIF Extension to Fortran-77: [function name] is not an intrinsic
function in Fortran-77
FIN Extension to Fortran-77: FIND statement
FMR Multiple RETURNs defined in a FUNCTION
FMT VMS incompatibility: Keyword FMT instead of NML
FNA A function without an argument list
FNG Extension to Fortran-77: [function name] is not a generic
function in Fortran-77
C-11
COMPILER MESSAGES
FNS Extension to Fortran-77: [name] is not a FORTRAN-77
subroutine
FOO Statement function declared out of order or array not
dimensioned
HCP VMS incompatibility: Hollerith constant padded with spaces
HCN Hollerith constant used where numeric expression required
HCU Extension to Fortran-77: Hollerith constant
IAT Illegal type for argument [number] for statement function
ICC Illegal character, continuation field of initial line
Continuation lines cannot follow comment lines.
ICD Inaccessible code. Statement deleted
The optimizer will delete statements that cannot be reached
during execution.
ICS Illegal character in line sequence number
IDN Opt - illegal DO nesting - optimization discontinued
A GO TO within a DO loop goes to the ending statement of an
inner, nested DO loop. The line number printed out with the
warning message is that of the OUTER DO.
DO 20
.
.
.
GO TO 10
.
.
.
DO 10
.
.
.
10 CONTINUE
.
.
.
20 CONTINUE
IFL Opt - infinite loop. Optimization discontinued
IMN IMPLICIT NONE
C-12
COMPILER MESSAGES
INC Extension to Fortran-77: INCLUDE statement
INS VMS incompatibility: /NOCREF switch
INS VMS incompatibility: /CREF switch
INS VMS incompatibility: Default for VMS is /NOLIST
IUA Illegal use of an array - use scalar variable instead
KIS Obsolete switch /KI
KWU Fortran-77 and VMS: Keyword [keyword name]
KWV Fortran-77 and VMS: Keyword value for [keyword name]
LID Identifier [name] more than six characters
The remaining characters are ignored.
LNC Fortran-77 and VMS: Non-numeric operand in numeric context
LNE VMS incompatibility: Logical and numeric variables
EQUIVALENCE-d
LOL VMS incompatibility: List of labels
LSP Extension to Fortran-77: [data type] length specifier
MBD IMPLICIT NONE - [variable] must be explicitly declared
MLN Fortran-77 and VMS: Mixing logical and numeric
MSL Fortran-77 and VMS: Multi-statement line
MVC Number of variables [is less than/is greater than] the
numbers of constants in DATA statement
NAM Extension to Fortran-77: NAMELIST statement
NDP Fortran-77 and VMS: No decimal places with edit descriptor
NEC Extension to Fortran-77: Numeric expression in character
context
NED No END statement in program
NIB Extension to Fortran-77: Non-integer substring bounds
NIG Extension to Fortran-77: Non-integer as index to computed
GOTO
C-13
COMPILER MESSAGES
NIK Extension to Fortran-77: Non-integer used with [keyword]
NIS Extension to Fortran-77: Non-integer subscript
NIX Extension to Fortran-77: Non-integer as index to RETURN
NLC Fortran-77 and VMS: Non-logical operand in logical context
NLK Extension to Fortran-77: Use of NAMELIST
NOD Global optimization not supported with /DEBUG - /OPT ignored
NOF No output file given
NPC VMS incompatibility: Null padding before [symbolic name]
NPP Extension to Fortran-77: No parentheses around PARAMETER
list
NSC Fortran-77 and VMS: Non-standard character in column 1
OCU Fortran-77 and VMS: Octal constant
OHC Octal or hexadecimal constant
OIO Extension to Fortran-77: [statement name] statement
OIO Fortran-77 and VMS: [statement name] statement
PAV PARAMETER used as associative variable
PLP PARAMETER list must be enclosed in parentheses
PPS PROGRAM statement parameters ignored
Used for compatibility purposes.
PSR Pound sign (#) in random access - use REC= or apostrophe (')
instead
PWS Fortran-77 and VMS: PRINT (Specifiers) statement
RDI Attempt to redeclare implicit type
RIM RETURN statement illegal in main program
RLC Extension to Fortran-77: & used with return label
RLC Fortran-77 and VMS: $ used with return label
RLX Fortran-77 and VMS: Return label [label]
C-14
COMPILER MESSAGES
SBC Extension to Fortran-77: Substring bounds not constant
SEP VMS incompatibility: [symbolic name] is the same as program
name or entry point
SID Slash (/) in dimension bound - use colon (:) instead
SMD Extension to Fortran-77: Single subscript with
multi-dimensioned array [array name]
SNN VMS incompatibility: [symbolic name] is the same as NAMELIST
name
SOD [name] statement out of order
SOR Fortran-77 and VMS: Subscript out of range for array [array
name]
SPN VMS incompatibility: [symbolic name] is the same as
PARAMETER name
SRO Fortran-77 and VMS: Symbolic relational operator [operator]
SVN VMS incompatibility: [symbolic name] is same as variable or
function name
TLF Fortran-77 and VMS: Two-branch logical IF
TSI Type of symbolic constant ignored
VAI [name] already initialized
VFS VMS incompatibility: [function name] is a Fortran-supplied
routine on VMS
VGF VMS incompatibility: [function name] is a generic function
on VMS
VIF VMS incompatibility: [function name] is an intrinsic
function on VMS
VND FUNCTION return value is never defined
VNF VMS incompatibility: [function name] is not an intrinsic
function on VMS
VNG VMS incompatibility: [function name] is not a generic
function on VMS
VNI Opt - variable [name] is not initialized
The optimizer analysis determined that the given variable
C-15
COMPILER MESSAGES
was never initialized prior to its use in a calculation.
VNS VMS incompatibility: [subroutine name] is not a VMS-supplied
subroutine
VSD VMS incompatibility: Subroutine [subroutine name] may differ
WDU Fortran-77 and VMS: WRITE with default unit
WNA Wrong number of arguments for statement function
WOP Opt - warnings given in Phase 1. Optimized code may be
incorrect
One or more of the messages issued prior to this message
resulted from situations that violate assumptions made by
the optimizer, and thus may cause it to generate code that
does not execute as desired.
XCR Extraneous carriage return
Carriage return was not immediately preceded or followed by
a line termination character.
XEN Fortran-77 and VMS: [* or &] with external name
XOR Extension to Fortran-77: Logical .XOR. operator
ZMT Size modifier [number] treated as [data type]
This message is issued when one of the data type size
modifiers that is accepted only for compatibility is used.
Internal Compiler Errors
An internal compiler error is an attempt by either the compiler or the
monitor to document an error inside the FORTRAN compiler. An
occurrence of an internal compiler error signifies that something is
wrong with the FORTRAN compiler.
Monitor-detected internal errors are of the form:
? Internal compiler error
? [message] at location [address] in phase [segment]
? While processing statement [line-number]
where [message] can be one of the following for TOPS-10:
Illegal memory reference
A read or write was attempted to a non-existent page
C-16
COMPILER MESSAGES
Stack exhausted
Monitor detected PDL overflow
Memory protection violation
Illegal reference to high segment
or where [message] can be one of the following for TOPS-20:
Illegal memory reference
A read was attempted to a non-existent page
Non-existent memory write
A write was attempted to a non-existent page
Illegal memory read
A memory read failed
Illegal memory write
A memory write failed
Stack exhausted
Monitor detected PDL overflow
Compiler-detected errors are of the form:
? Internal compiler error-processing statement [line-number]
? Call to [routine-name] from [address]
Submit an SPR if you receive an internal compiler error.
At the end of program unit compilation, the compiler prints an error
summary line, which is one of the following:
[ No error detected ]
%FTNWRN no warning(s)
%FTNWRN [warning count] warnings(s)
?FTNFTL [fatal count] fatal error(s) and no warning(s)
?FTNFTL [fatal count] fatal error(s) and [warning count]
warning(s)
C-17
D-1
APPENDIX D
FOROTS ERROR MESSAGES
Errors detected at run time by FOROTS fall into the following
categories:
1. System errors (SYS) - errors internal to FOROTS
2. Open errors (OPN) - I/O errors that occur during a file OPEN
and CLOSE
3. Arithmetic fault errors (APR) - errors in numeric
calculations
4. Library errors (LIB) - errors generated by FORLIB library
routines
5. Data errors (DAT) - errors in data conversion on I/O
6. Device errors (DEV) - I/O hardware errors
7. Compatibility errors (COM) - errors generated by the
compatibility flagger
|
| 8. RMS-returned errors - errors returned by RMS-20 to FOROTS
The messages generated by FOROTS contain the following elements:
1. A 3-letter code that identifies the type of message (TOPS-10
only)
2. The message itself, which describes what FOROTS has
encountered
3. For I/O errors, two integer values which are retrieved by the
ERRSNS subroutine
4. For compatibility errors, a prefix precedes the message that
describes the type of incompatibility the messages refers to;
one of the following:
D-1
FOROTS ERROR MESSAGES
o Extenstion to FORTRAN-77:
o VMS incompatibility:
o FORTRAN-77 and VMS:
See Section 16.6 for more information on the compatibility
flagger.
|
| 5. For RMS errors, the RMS STS and STV codes, where available,
| are included in the error message itself, and can be
| retrieved by the ERRSNS subroutine.
The 3-letter code (TOPS-10 only) and the message are, by default,
printed at your terminal when an error occurs; the two ERRSNS values
are stored within the arguments you have supplied for the ERRSNS
subroutine. If you do not include a call to the ERRSNS subroutine in
your program, your program cannot have access to the two ERRSNS
values.
| When an RMS-detected error occurs, the second ERRSNS value contains
| the STS code from RMS (a number between 300000 and 377777 octal). The
| STV code, which further amplifies the reason for an RMS error, is
| available to your program through an additional argument to the ERRSNS
| subroutine. For instructions on how to use the ERRSNS subroutine, see
Section 13.4.1.15.)
Table D-1 contains a list of all the 3-letter message codes and the
ERRSNS values that are generated by FOROTS.
D-2
FOROTS ERROR MESSAGES
Table D-1: FOROTS Error Codes
1st 2nd
Value Value(5) Code(1) Meaning
0 No error detected
0 No error detected
1 Arithmetic trap
n (7) IDC (3) Integer divide check
2 Input Conversion Error
n (7) IOV (3) Integer overflow
3 Input Conversion Error
n (7) FOV (3) Floating overflow
4 Arithmetic trap
n (7) FOV (3) Floating overflow
5 Arithmetic trap
n (7) FDC (3) Floating divide check
6 Arithmetic trap
n (7) FUN (3) Floating underflow
7 Input Conversion Error
n (7) FUN (3) Floating underflow
9 Output Conversion Error
0 FTS (3) Output field width too
small
21 FORLIB errors and warnings
104 IDU DIVERT: illegal to divert
to unit
105 UNO DIVERT: unit not open
106 NOF DIVERT: unit not open for
formatted I/O
107 CWU DIVERT: Can't write to
unit
108 CLE Concatenation result longer
than expected
109 ICE Illegal length character
expression
110 NCS No character stack
allocated
D-3
FOROTS ERROR MESSAGES
Table D-1: FOROTS Error Codes (Cont'd)
1st 2nd
Value Value(5) Code(1) Meaning
112 AQS First argument of SORT must
be a quoted string
113 SSE (3) Substring range error
114 SRE (3) Subscript range error
115 TMA Too many arguments in call
to SORT
116 CGP Can't get pages 600:677 for
SORT
117 CRP (1) Can't return pages 600:677
after call to SORT
118 NSS (2) No free section available
for SORT
119 CFS (2) Can't find SYS:SORT.EXE
120 CGS (2) Can't get SYS:SORT.EXE
121 CPP (3) Can't preallocate pages
600:677 for SORT
122 IPN Illegal page number
123 CCS Not enough memory for
creating character stack
124 ECS Not enough memory for
expanding character stack
125 ALZ Argument less than or equal
to zero
126 DMA (2,3) Must give lower and upper
bounds to dump in non-zero
sections
22 I/O warnings
509 ETL (3) Attempt to WRITE beyond
fixed-length record
532 ARC (3) Ambiguous repeat count
583 FVM (3) Format and variable type do
not match
584 RIF (3) Reading into FORMAT
non-standard
590 DQW (2,3) Disk full or quota exceeded
- Please EXPUNGE, then type
CONTINUE
23 FORLIB bounds check
warnings
113 SSE (3) Substring range error
114 SRE (3) Subscript range error
24 End of file
-1 EOF End of file
D-4
FOROTS ERROR MESSAGES
Table D-1: FOROTS Error Codes (Cont.)
1st 2nd
Value Value(5) Code(1) Meaning
25 Record or record number
error
302 BBF Bad format binary file
510 RNR Attempt to read a record
that has not been written
512 IRN Illegal record number
517 RTL Record too large - memory
full
536 CBI Cannot backspace image file
with no RECORDSIZE
536 CSI Cannot skiprecord image
file with no RECORDSIZE
570 ICD Non-digit in record
delimiter
572 RSM Record size different from
that specified in OPEN
573 FCL Unexpected continuation
LSCW found
576 WBA Attempt to WRITE beyound
variable or array
577 SLN Record length negative or
zero
26 OPEN/CLOSE warnings
502 CSF (2,3) Can't set FORTRAN carriage
control attribute
535 BSI (3) BLOCKSIZE ignored: device
is not a magnetic tape
541 UOA (3) Unknown OPEN keyword,
ignored
542 NCK (3) OPEN-only keyword specified
in CLOSE, ignored
550 CQF (1,3) Cannot QUEUE file
595 OGX (1,3) Galaxy version 2 not
supported
| 609 NNI(1) Node name ignored
28 CLOSE error
J CLF (2) Cannot CLOSE file
J RNM (2) Cannot RENAME file
250+n CLS (1) "Close" FILOP. error n (4)
250+n DEL (1) "Delete" FILOP. error n (4)
250+n RNM (1) "Rename" FILOP. error n (4)
| 610 UDO (2) Unsupported /DISPOSE option
| for RMS files
D-5
FOROTS ERROR MESSAGES
Table D-1: FOROTS Error Codes (Cont.)
1st 2nd
Value Value(5) Code(1) Meaning
30 OPEN error
J APP (2) Cannot set up to append to
magnetic tape file
240 FRR /RECORDTYPE:FIXED requires
/RECORDSIZE
240 RR1 Random I/O requires
RECORDSIZE specifier in
OPEN statement
240 RRR Random I/O requires
/RECORDSIZE
242 NFC (1) Too many OPEN units
243 CIR /CARRIAGECONTROL:TRANSLATED
illegal with this
/RECORDTYPE
244 RLB /RECORDSIZE larger than
/BLOCKSIZE
245 NSD No such device
248 IAC Specified ACCESS illegal
for this device
249 IDM Specified MODE is illegal
for this device
250+n OPN (1) Cannot OPEN file
405 PPN (2) JSYS error - PPN cannot be
translated
503 CEF (2) End of command file
encountered
506 ICA Incompatible attributes
540 SDO Same device open on another
unit with conflicting
specifiers
569 TFM Tape format conflicts with
OPEN statement or default
585 IAV Illegal value for OPEN
specifier
D-6
FOROTS ERROR MESSAGES
Table D-1: FOROTS Error Codes (Cont.)
1st 2nd
Value Value(5) Code(1) Meaning
| 600 ATC (2) File's attribute different
| from that specified in OPEN
| 601 URT (2) RECORDTYPE value not
| supported for this file
| type
| 602 URS (2) Unsupported remote system
| 603 BME (2) Bytesize must be 8
| 604 MEU (2) Missing EXTERNAL for
| USEROPEN routine
| 606 KER (2) Missing required KEY=
| 607 TKS (2) Too many KEY= specifiers
| 608 RMS (2) RMS file requries
| ORGANIZATION=
| 611 DFR (2) Default /RECORDTYPE:FIXED
| requires /RECORDSIZE
| 612 KDB (2) KEY datatype CHARACTER
| conflicts with BYTESIZE
| 613 RIR (2) New RELATIVE or INDEXED
| file requires /RECL
| 615 RNA (2) RMS not available on SYS:
31 Mixed ACCESS modes
315 CDR Can't do direct I/O to
sequential file
315 CDS Can't do sequential I/O to
direct file
593 POI Illegal for DIRECT (RANDOM)
files
594 CDF Can't determine whether
formatted or unformatted
| 605 KRI(2) Can't do keyed I/O to this
| file type
| 614 SIF(2) Statement illegal for this
| type of access
32 Illegal logical unit number
239 IUN Illegal unit number
D-7
FOROTS ERROR MESSAGES
Table D-1: FOROTS Error Codes (Cont.)
1st 2nd
Value Value(5) Code(1) Meaning
33 Compatibility error
321 CFC (3) FORTRAN-77 and VMS:
Carriage control character
322 CFF (3) VMS incompatibility:
Intrinsic routine invoked
incompatibly
323 CFR (2,3) FORTRAN-77 extension:
FORTRAN-20 supplied routine
invoked
323 CFX (2,3) FORTRAN-77 and VMS:
FORTRAN-20 supplied routine
invoked
323 CFR (1,3) FORTRAN-77 extension:
FORTRAN-10 supplied routine
invoked
323 CFX (1,3) FORTRAN-77 and VMS:
FORTRAN-10 supplied routine
invoked
324 CFK (3) FORTRAN-77 and VMS: Keyword
[keyword]
325 CFT (3) FORTRAN-77 and VMS:
Trailing spaces in output
record
326 CFO (3) FORTRAN-77 extension:
Overlap of character
assignments
327 CFG (3) FORTRAN-77: and VMS: G
format descriptor used with
character
39 REREAD error
310 RBR REREAD not proceeded by
READ
D-8
FOROTS ERROR MESSAGES
Table D-1: FOROTS Error Codes (Cont.)
1st 2nd
Value Value(5) Code(1) Meaning
45 OPEN/CLOSE statement syntax
errors
241 ESV Unknown or ambiguous
keyword
241 USW (1) Unknown switch
241 ASW (1) Ambiguous switch
533 DLT Dialog string too long
539 EDS/EDA (2) Error parsing DIALOG string
544 NDI (1) No device specified with
":"
545 IPP (1) Illegal PPN
546 TMF (1) Too many SFDs
547 NSI (1) Null SFD
548 IDD (1) Illegal character in DIALOG
string
551 NQS (1) PADCHAR must be single
character in double quotes
47 WRITE on READ-only file
263 CDT Cannot WRITE to READ-only
file
554 CWL Cannot write a file with
MODE=LINED
62 Syntax error in FORMAT
301 ILF Illegal character in FORMAT
306 DLF Data in I/O list but not in
FORMAT
524 RIC Reading into character
format illegal
538 IRC Illegal repeat count
552 IHC Illegal Hollerith constant
553 IFW Illegal field width
575 UDT Undefined data type or
internal FOROTS error
583 FVF Format and variable type do
not match
64 Input conversion error
307 ILC Illegal character in data
81 FOROTS calling errors
501 UNS Unit not specified
508 IOL Bad I/O list
D-9
FOROTS ERROR MESSAGES
Table D-1: FOROTS Error Codes (Cont.)
1st 2nd
Value Value(5) Code(1) Meaning
574 IMV Illegal MTOP value
579 IDI (1) Illegal DUMP mode I/O list
581 DLL (1) Dump mode I/O list too long
582 IWI Illegal to initiate another
I/O statement
599 ICE Illegal length for
character expression
96 Error in magnetic tape
operations
J ILM (2) Unexpected MTOPR% error (2)
J UMO (2,3) Error trying to set tape
530 UTE (1) Unexpected TAPOP. error
537 UTO (1) Unexpected TAPOP. error
trying to set parameters
537 UTO (1,3) Unexpected TAPOP. error
trying to set parameters
587 ITE (1) Tape is not usable by your
job
97 NAMELIST data errors
309 VNN Variable not in namelist
513 NEQ "=" not found in namelist
data
514 NRP Missing right paren
515 ILN Variable or namelist does
not start with letter
516 ILS Illegal subscript
519 CCC Cannot convert constant to
correct type
521 RPE Illegal repeat count
522 SNV Sign with null value
580 NLS Null string illegal
596 NEC Found character when
expecting ":"
597 ISS Substring descriptor
illegal
598 SNQ String not within single
quotes
D-10
FOROTS ERROR MESSAGES
Table D-1: FOROTS Error Codes (Cont.)
1st 2nd
Value Value(5) Code(1) Meaning
98 Unclassifiable device
errors
J ISW (2) Cannot switch to input
J IOE (2) General purpose I/O error
J OSW (2) Cannot switch to output
250+n ISW (1) Cannot switch to input
250+n OSW (1) Cannot switch to output
400 IOE (1) General-purpose I/O error
586 MFU Memory full
590 DQE (2) Disk full or quota exceeded
No ERRSNS values
BLK (3,6) Blocks allocated but not
deallocated
CCP (1,6) Cannot create page
CDP (1,6) Cannot destroy page
CGD (6) Can't get DBMS
DBM (6) DBMS not loaded
DST (1,6) Error in dialog string
EFS (6) Enter correct file specs
FFX (6) FOROP function code exceeds
range
IEM (6) Error in memory management
IJE (2,6) "Impossible" JSYS error
MFU (6) Memory full
NOR (3,6) Error number out of range
PAG (3,6) Pages allocated but not
deallocated
PGD (6) Deallocating more pages
than allocated
POV (6) PDL overflow
SNH (6) Internal FOROTS error
TDT (6) Trap occured during trap
processing
D-11
FOROTS ERROR MESSAGES
Table D-1: FOROTS Error Codes (Cont.)
(1) TOPS-10 only
(2) TOPS-20 only
(3) This is a warning, not an error. The error cannot be
trapped with an ERR= branch, but IOSTAT and ERRSNS will be
set.
(4) See the TOPS-10 Monitor Calls Manual for the list of
FILOP. error codes and their meanings.
(5) "J" means the TOPS-20 JSYS error code. This number will
be between 600000 and 610000 (octal).
(6) No ERRSNS values
(7) Where n is the number of times the error occurs
APR and LIB errors are usually reported as warnings, and the program
continues. The number of APR and LIB errors listed on the user's
terminal can be changed by the FORTRAN Library Subroutine ERRSET (see
Section 13.4.1.14). The I/O errors either cause messages to be
printed on the terminal or can be trapped by an error exit argument
(ERR=statement number) on OPEN, READ, WRITE, and CLOSE.
The FORTRAN Library Subroutine ERRSNS (see Section 13.4.1.15) allows
you to find out which I/O error occurred. When called, ERRSNS returns
one or two integer values that describe the status of the last I/O
operation performed by FOROTS. (The second integer value is
optional.) For example,
CALL ERRSNS (I,J)
calls this subroutine. J, the second integer value, is optional.
D.1 ALPHABETICAL DESCRIPTION OF FOROTS MESSAGES
This section contains alphabetical descriptions of each warning and
fatal error message that is generated by FOROTS during program
execution. Each message is first listed; then is followed by a brief
description of how it is generated; followed by, in some cases, a
recovery procedure; and finally, where applicable, followed by the
ERRSNS values associated with the message.
ALZ ? Argument less than or equal to zero
D-12
FOROTS ERROR MESSAGES
Cause: An argument (such as a memory size) was specified with
a value less than or equal to zero.
Recovery: Specify the correct value for the argument.
ERRSNS values: First Value = 21 Second Value = 125
APP ? Can't setup to append to magtape file <JSYS error> (TOPS-20
only)
Cause: The MTOPR% JSYS failed trying to position the magnetic
tape with the function .MOFWF or .MOBKR.
Recovery: Use the information provided to determine a recovery.
ERRSNS values: First Value = 30 Second Value = JSYS error
number
AQS ? First argument to SORT must be a quoted string
Cause: The SORT routine detected that the first argument was
of type CHARACTER, but the string was not word aligned.
Recovery: If the first argument to the SORT program is of type
CHARACTER, it must be word aligned and terminated by an
ASCII null. The most reliable way to generate such an
argument is to use a character constant.
ERRSNS values: First Value = 21 Second Value = 112
ARC % Ambiguous repeat count
Cause: In a FORMAT statement, a number between two format
specifiers can be considered belonging to either one.
Recovery: Insert a comma before or after the number, depending on
which specifier the number belongs with.
ERRSNS values: First Value = 22 Second Value = 532
ASW ? Ambiguous switch /<sw> (TOPS-10 only)
Cause: In dialog mode, a switch was specified, but not enough
of the switch was given to uniquely specify which
switch was intended.
Recovery: Retype the line, completely specifying which switch you
mean.
D-13
FOROTS ERROR MESSAGES
ERRSNS values: First Value = 45 Second Value = 241
| ATC ? File's <attribute> conflicts with OPEN statement or default
| (TOPS-20 only)
|
| Cause: You opened an RMS file with RECORDTYPE or ORGANIZATION
| attributes in your OPEN statement, which conflict with
| the actual attributes of the file.
|
| Recovery: Specify the correct attributes, or omit them from OPEN
| to use the file's attributes.
|
| ERRSNS values: First Value = 30 Second Value = 600
BBF ? Bad format binary file
Cause: The control information stored in a binary file is
incorrect. The file cannot be read using
MODE='BINARY'. This error can be caused when the file
you are reading was not written by FORTRAN using
MODE='BINARY'.
Recovery: Make sure that you are using the correct file and data
mode. Any file can be read with MODE='IMAGE'. (See
| Section 11.3.24)
ERRSNS values: First Value = 25 Second Value = 302
BLK % Pages allocated but not deallocated
Cause: Internal FOROTS error in memory management.
Recovery: Submit an SPR and include your program.
| BME ? Bytesize must be eight (TOPS-20 only)
|
| Cause: You specified a BYTESIZE= other than 8 when accessing a
| VMS RMS file.
|
| Recovery: Change BYTESIZE=, or omit the specifier to default VMS
| files to 8.
|
| ERRSNS values: First Value = 30 Second Value = 603
BSI % Blocksize ignored: device is not a magnetic tape
Cause: A BLOCKSIZE specifier was given in an OPEN statement
D-14
FOROTS ERROR MESSAGES
(see Section 11.3.4) but was not used because the
device being opened is not a magnetic tape.
ERRSNS values: First Value = 26 Second Value = 535
CBI ? Can't BACKSPACE IMAGE file with no RECORDSIZE
Cause: An OPEN statement with the MODE='IMAGE' specifier (but
not the RECORDSIZE= specifier) was executed prior to a
BACKSPACE statement that referred to the open unit.
Recovery: If you are using fixed-length records, specify the
RECORDSIZE parameter in the OPEN statement (see Section
| 11.3.33). Otherwise, the BACKSPACE cannot be done.
ERRSNS values: First Value = 25 Second Value = 536
CCC ? Can't convert constant to correct type
Cause: In NAMELIST input, a variable was assigned a value that
does not match. For example, if C is a complex
variable, the input:
C=.TRUE.
is in error, since .TRUE. is not a legal complex
number.
Recovery: Correct the error in the source program.
ERRSNS values: First Value = 97 Second Value = 519
CCP ? Can't create page <n> (PAGE. error <n>) (TOPS-10 only)
Cause: FOROTS attempted to use a page of memory for some task,
but was unable to. The monitor error code gives the
reason. This can be caused by erroneous MACRO
subroutines. If no such cause is found, it is an
internal FOROTS error.
CCS ? Not enough memory for creating character stack
Cause: A character stack was requested that was larger than 36
sections (larger that the maximum virtual memory
available).
Recovery: Specify correct call argument.
D-15
FOROTS ERROR MESSAGES
ERRSNS values: First Value = 21 Second Value = 124
CDF ? Can't determine whether formatted or unformatted
Cause: The specified file has had both formatted and
unformatted I/O operations (or OPENs) performed on it.
Recovery: Use I/O operations and OPENs with the same FORM=
specifier.
ERRSNS values: First Value = 31 Second Value = 594
CDP ? Can't destroy page <n> (PAGE. error <n>) (TOPS-10 only)
Cause: FOROTS attempted to use a page of memory for some task,
but was unable to. The monitor error code gives the
reason. This can be caused by erroneous MACRO
subroutines. If no such cause is found, it is an
internal FOROTS error.
CDR ? Can't do direct I/O to sequential file
Cause: An attempt was made to perform I/O to a file that is
already open in a conflicting mode.
Recovery: Open file in the appropriate mode.
ERRSNS values: First Value = 31 Second Value = 315
| CDS ? Can't do sequential I/O to direct file
Cause: An attempt was made to perform I/O to a file that is
already open in a conflicting mode.
Recovery: Open file is the appropriate mode.
ERRSNS values: First Value = 31 Second Value = 315
CDT ? Can't <read/write> an <input/output>-only file
Cause: An attempt was made to perform I/O to a file, but the
file is not open for I/O in the appropriate direction.
Recovery: Open the file with ACCESS='SEQINOUT' or 'RANDOM', as
appropriate. It is not possible to open a file for
APPEND access and then read from it. (See Section
11.3.1.)
D-16
FOROTS ERROR MESSAGES
ERRSNS values: First Value = 47 Second Value = 263
CEF ? End of command file encountered (TOPS-20 only)
Cause: An indirect file was specified as a DIALOG argument,
and the end of the file was encountered before a
terminator character (line-feed).
Recovery: Edit the file and insert a line-feed.
ERRSNS values: First Value = 30 Second Value = 503
CFC % Fortran-77 and VMS: Carriage control character
Cause: A carriage-control character was used that is
incompatible with ANSI FORTRAN and VAX FORTRAN.
Recovery: If you want the program to be compatible with ANSI
FORTRAN or VAX FORTRAN, use a compatible
carriage-control character.
ERRSNS values: First Value = 33 Second Value = 321
CFF % VMS incompatibility: Intrinsic routine invoked incompatibly
Cause: An intrinsic routine was invoked in a method
incompatible with VAX FORTRAN (such as use of an
EXTERNAL statement for an intrinsic function).
Recovery: If you want the program to be compatible with VAX
FORTRAN, change to a method of invoking intrinsic
routines that is compatible with VAX.
ERRSNS values: First Value = 33 Second Value = 322
CFG % Fortran-77 and VMS: G format descriptor used with character
Cause: The G format descriptor was used with character data,
which is an extension to ANSI FORTRAN and VAX FORTRAN.
Recovery: If you want the program compatible with ANSI FORTRAN or
VAX FORTRAN, do not use the G format descriptor to edit
character data.
ERRSNS values: First Value = 33 Second Value = 327
CFK % Fortran-77 and VMS: Keyword [keyword]
D-17
FOROTS ERROR MESSAGES
Cause: An OPEN or CLOSE keyword was used that is incompatible
with ANSI FORTRAN and VAX FORTRAN.
Recovery: If you want the program compatible with ANSI FORTRAN or
VAX FORTRAN, use a compatible OPEN or CLOSE keyword.
ERRSNS values: First Value = 33 Second Value = 324
CFO % Fortran-77 extension: Overlap of character assignments
Cause: A character assignment statement was used in which the
character positions defined in the character variable,
array element or substring on the left of the equal
sign are referenced in the character expression on the
right of the equal sign. This is incompatible with
ANSI FORTRAN.
Recovery: If you want the program to be compatible with ANSI
FORTRAN, use a character assignment statement that does
not overlap the character expression and the character
variable, array element, or substring.
ERRSNS values: First Value = 33 Second Value = 326
CFR % Fortran-77 extension: FORTRAN-20 supplied routine invoked
(TOPS-20 only)
CFR % Fortran-77 extension: FORTRAN-10 supplied routine invoked
(TOPS-10 only)
Cause: A FORTRAN-10/20-supplied subroutine was invoked that is
not available with ANSI FORTRAN.
Recovery: If you want your program to be compatible to ANSI
FORTRAN, use a compatible subroutine.
ERRSNS values: First Value = 33 Second Value = 323
CFS ? Can't find SYS:SORT.EXE - <JSYS error> (TOPS-20 only)
Cause: The file SORT.EXE cannot be found on SYS:. A monitor
supplied error message will give more detail.
Recovery: Use the information provided by the monitor to
determine the proper course of action.
ERRSNS values: First Value = 21 Second Value = 119
CFT % Fortran-77 and VMS: Trailing spaces in output record
D-18
FOROTS ERROR MESSAGES
Cause: Your program contains a FORMAT that specifies trailing
blanks (X format and $ format). In this case,
FORTRAN-10/20 preserves the trailing spaces.
Recovery: If you want the program compatible with ANSI FORTRAN
and VAX FORTRAN, do not use this form of the FORMAT
statement.
ERRSNS values: First Value = 33 Second Value = 325
CFX % Fortran-77 and VMS: FORTRAN-20 supplied routine invoked
(TOPS-20 only)
CFX % Fortan-77 and VMS: FORTRAN-10 supplied routine invoked (TOPS-10
only)
Cause: A FORTRAN-10/20-supplied subroutine was invoked that is
not available with ANSI FORTRAN or VAX FORTRAN.
Recovery: If you want the program to be compatible with ANSI
FORTRAN or VAX FORTRAN, use a compatible subroutine.
ERRSNS values: First Value = 33 Second Value = 323
CGP ? Can't get pages 600:677 for SORT
Cause: The SORT subroutine brings the SORT program into core
in pages 600 through 677. Some of these pages were
already occupied by programs or data at the time that
SORT was called.
Recovery: Decrease the size of your program. Having fewer files
open or using a BUFFERCOUNT=1 specifier in OPEN
statement may help (see Section 11.3.5). If this does
not help, you can segment the program by using LINK's
overlay facility (see the LINK Reference Manual).
ERRSNS values: First Value = 21 Second Value = 116
CGS ? Can't get SYS:SORT.EXE - <JSYS error> (TOPS-20 only)
Cause: The file SORT.EXE was found on SYS:, however for some
reason it could not be merged into your program in
order to sort files. A monitor supplied error message
will give more detail.
Recovery: Use the information provided by the monitor to
determine the proper course of action.
ERRSNS values: First Value = 21 Second Value = 120
D-19
FOROTS ERROR MESSAGES
CIR ? /CARRIAGECONTROL:TRANSLATED illegal with this /RECORDTYPE
Cause:
Recovery:
ERRSNS values: First Value = 30 Second Value = 243
CLE ? Concatenation result larger than expected
Cause: The specified substring bounds are out of range.
Recovery: Specify legal substring bounds.
ERRSNS values: First Value = 21 Second Value = 108
CLS ? CLOSE failed, <I/O error message> (TOPS-10 only)
Cause: A CLOSE UUO. or FILOP. CLOSE function failed.
Recovery: Use the information provided to determine a recovery.
ERRSNS values: First Value = 28 Second Value = 250+n
CPP % Can't preallocate pages 600:677 for SORT
Cause: A call to the SRTINI subroutine was unable to
preallocate SORT's pages because they were already
allocated.
Recovery: Decrease the size of your program. Having fewer files
open or using a BUFFERCOUNT=1 specifier in the OPEN
statement may help (see Section 11.3.5).
ERRSNS values: First Value = 21 Second Value = 121
CQF % Can't queue file: QUEUE. UUO ERROR <N> (TOPS-10 only)
Cause: This error may occur when executing a CLOSE statement
in which the DISPOSE specifier is given with one of the
values: 'LIST', 'PRINT', or 'PUNCH', and GALAXY
release 4 is running. (See Section 11.5.4.)
Recovery: Refer to the TOPS-10 Monitor Calls Manual for an
explanation of the QUEUE. error number <n>.
ERRSNS values: First Value = 26 Second Value = 550
D-20
FOROTS ERROR MESSAGES
CRP ? Can't return pages 600:677 after call to SORT (TOPS-10 only)
Cause: Before the SORT subroutine returns to the user, it
tries to deallocate the pages that the SORT program
resides in. The pages could not be deallocated. This
is not expected to occur.
Recovery: Submit an SPR.
ERRSNS values: First Value = 21 Second Value = 117
CSF % Can't set FORTRAN carriage control attribute (TOPS-20 only)
Cause: You are running a TOPS-20 system that does not have
Edit 2981, which allows support for the FORTRAN
carriage-control attribute.
Recovery: Autopatch the monitor to include Edit 2981.
ERRSNS values: First Value = 26 Second Value = 502
CSI ? Can't skiprecord image file with no RECORDSIZE
Cause: A SKIPRECORD statement was executed for a file opened
with MODE=IMAGE, and the file did not have a
RECORDSIZE(RECL) specified. Since there are no record
markers in IMAGE mode files, FOROTS cannot determine
how far to skip.
| Recovery: Add a RECL= specifier (see Section 11.3.33) to the OPEN
statement.
ERRSNS values: First Value = 25 Second Value = 536
CWL ? Can't write a file with MODE='LINED'
Cause: The program attempted to execute an output operation
such as a WRITE statement after an OPEN statement for
the same unit. The OPEN statement contained a
MODE='LINED' specifier.
Recovery: Change the OPEN statement specifier to MODE='ASCII'.
| (See Section 11.3.24.)
ERRSNS values: First Value = 47 Second Value = 554
CWU ? DIVERT: Can't write to unit <n>
D-21
FOROTS ERROR MESSAGES
Cause: DIVERT file is not opened for output.
Recovery: Open DIVERT file for output.
ERRSNS values: First Value = 21 Second Value = 107
DBM ? DBMS not loaded
Cause: A DBMS call to a sharable FOROTS was attempted without
DBMS.
Recovery: The system manager must build DBMS into sharable FOROTS
or remove the file from FORLIB that directs the DBMS
call to the sharable FOROTS.
DEL ? Can't delete file:<FILOP. error message> (TOPS-10 only)
Cause: The "DELETE" FILOP. failed. The file is not deleted.
Recovery: Usually you can correct the problem when the program is
finished and delete the file with the monitor DELETE
command.
ERRSNS values: First Value = 28 Second Value = 250+n
| DFR ? Default RECORDTYPE:FIXED requires /RECORDSIZE (TOPS-20 only)
|
| Cause: You attempted to create a new RMS relative or indexed
| file with a default /RECORDTYPE of FIXED, but did not
| specify /RECORDSIZE.
|
| Recovery: Specify /RECORDSIZE.
|
| ERRSNS values: First Value = 30 Second Value = 611
DLF % Data in IO list but not in format
Cause: An I/O statement has requested data to be transferred,
but the FORMAT statement does not specify any
descriptor that would translate the data.
Recovery: Fix the FORMAT statement. It must contain one of the
following descriptors:
A,B,E,F,G,I,L,O,Q,R,Z
ERRSNS values: First Value = 62 Second Value = 306
D-22
FOROTS ERROR MESSAGES
DLL ? DUMP mode I/O list too long (TOPS-10 only)
Cause: The I/O list specified for a DUMP mode READ or WRITE
statement is too long for the FOROTS internal DUMP mode
control list.
Recovery: Split the I/O list across two or more READ or WRITE
statements.
ERRSNS values: First Value = 81 Second Value = 581
DMA % Must give lower and upper bounds to dump in non-zero sections
(TOPS-20 only)
Cause: A call to PDUMP or DUMP was made without specifying
memory bounds. In section zero, this is interpreted as
'all of memory'. For extended addressing, lower and
upper bounds must be specified.
Recovery: Specify lower and upper bounds for memory.
ERRSNS values: First Value = 21 Second Value = 126
DQE ? Disk full or quota exceeded
Cause: The disk quota for the disk on which a file is being
written is exhausted, or the entire disk structure is
full. If this error is encountered while running under
batch, the program is aborted and an attempt is made to
close all files. If this error is encountered while
timesharing, the user is requested to type an EXPUNGE
command and then a CONTINUE command.
Recovery: EXPUNGE or create more room on the specified disk
structure.
ERRSNS values: First Value = 98 Second Value = 590
DQW % Disk full or quota exceeded - Please EXPUNGE, then type CONTINUE
(TOPS-20 only)
Cause: The file or files being written on the disk have either
exhausted your disk quota or filled the structure.
Recovery: FOROTS leaves the terminal at EXEC level so that you
have more options to use to provide space on the disk
structure. You can type CONTINUE to resume processing
if you don't reset the current fork.
D-23
FOROTS ERROR MESSAGES
ERRSNS values: First Value = 22 Second Value = 590
DSS % DISPOSE='SAVE' assumed - device is not a disk
Cause: A DISPOSE value other than 'SAVE' was specified for a
file on a device other than disk. (See Section
| 11.3.15.)
ERRSNS values: First Value = 26 Second Value = 549
DST ? Error in dialog string (TOPS-10 only)
Cause: A syntax error in the DIALOG= specifier.
Recovery: Correct the error in the program or in DIALOG mode.
(See Section 11.5.3.)
DTL % Dialog string too long
Cause: The argument to DIALOG= cannot be parsed because it is
too long.
Recovery: Use a shorter string.
ERRSNS values: First Value = 45 Second Value = 533
ECS ? Not enough memory for expanding character stack
Cause: More memory than is available on a KL10 was requested
by either a dynamic concatenation (concatenation of
character variables of length*) or by a call to the
ALCCHR subroutine.
Recovery: Reduce the size of your concatenation or argument to
ALCCHR. If you are running extended addressing, you
can present parts of the character stack by invoking
SORT and dynamic libraries at the beginning of the
program.
ERRSNS values: First Value = 21 Second Value = 124
EDS/EDA ? Error in DIALOG string - <message> (TOPS-20 only)
Cause: A syntax error in the DIALOG= specifier. (See Section
11.5.3.)
Recovery: Retype the specifier correctly in DIALOG mode.
D-24
FOROTS ERROR MESSAGES
ERRSNS values: First Value = 45 Second Value = 539
EFS [ Enter correct file specs ]
Cause: Dialog mode. You should respond to this message by
entering any information you wish to change about the
indicated file. This can include the device, filename,
directory, or any OPEN parameter. The form of a
response is:
TOPS-10 DEV:FILE.EXT[DIRECTORY] /SWITCH:VAL /SWITCH:VAL
TOPS-20 DEV:<DIRECTORY>FILE.EXT.GEN /SWITCH:VAL /SWITCH:VAL
All parts of this specification are optional.
EOF ? End of file
Cause: An input statement has attempted to read more data than
the file contains.
Recovery: Use an END= specifier in the READ statement, or
lengthen the file.
ERRSNS values: First Value = 24 Second Value = -1
ESV ? <unknown/ambiguous> keyword value /<switch>:<value> (TOPS-20
only)
Cause: A switch entered in dialog mode was not recognized or
was not specified uniquely.
Recovery: Retype the line, specifying the correct switch.
ERRSNS values: First Value = 45 Second Value = 241
ETL % Attempt to write beyond fixed-length record
Cause: In an ENCODE statement, the format specified more
characters than the string will hold. The excess
characters are ignored. (See Section 10.12.)
Recovery: Shorten the format or lengthen the string.
ERRSNS values: First Value = 22 Second Value = 509
FCL ? Found unexpected continuation LSCW
D-25
FOROTS ERROR MESSAGES
Cause: A RECL(RECORDSIZE) has been specified in an OPEN
statement, and FOROTS has encountered a continuation
(type 2) logical segment control word (LSCW). This
type LSCW is never written in fixed-length binary
records.
Recovery: Remove the RECL(RECORDSIZE) specification in the OPEN
statement.
ERRSNS values: First Value = 25 Second Value = 573
FDC % Floating divide check
Cause: The program contains a floating-point division in which
the divisor is too small compared to the dividend to
yield a result that is in the floating-point range.
Recovery: Correct program so that division is within
floating-point range.
ERRSNS values: First Value = 5 Second Value = n
where n is
the number
of times the
error occurs
FFX ? FOROP. function code exceeds range
Cause: A library routine has called for an operation that is
not available. This can be caused by using a
mismatched FOROTS and FORLIB, or by an erroneous MACRO
subroutine.
Recovery: Make sure the versions of FOROTS.EXE and FORLIB.REL
that you are loading from are matching versions. If
this doesn't help, find the subroutine causing the
problem and alter or remove the erroneous call.
FOV % Floating overflow
Cause: A REAL or DOUBLE PRECISION number was read that is too
large in magnitude (see Chapter 3). This is only a
warning and does not stop execution of the program.
The results of a calculation that overflows are set to
the largest representable number with the sign of the
correct result.
Recovery: Modify the data so that its values fall in the range of
values that can be represented for the data type.
D-26
FOROTS ERROR MESSAGES
ERRSNS values: First Value = 3 or 4 Second Value = n
where n is
the number
of times the
error occurs
FRR ? /RECORDTYPE:FIXED requries /RECORDSIZE
Cause: A RECORDTYPE='FIXED' was specified in an OPEN statement
without a RECORDSIZE (RECL) specifier.
Recovery: Specify RECL in the OPEN statement (see Section
| 11.3.33).
ERRSNS values: First Value = 30 Second Value = 240
FTS % Output field width too small
Cause: The field width specified in a FORMAT statement was not
large enough to allow the printing of the value being
output. For example, this error would occur if the
number 100 is output with the format specifier "I2".
ERRSNS values: First Value = 9 Second Value = 0
FUN % Floating underflow
Cause: A REAL or DOUBLE PRECISION number was read that is too
small in magnitude (see Chapter 3). This only a
warning and does not stop execution of the program.
The result of a calculation that underflows is set to
zero.
Recovery: Modify the data so that its values fall in the range of
values that can be represented for the data type.
ERRSNS values: First Value = 6 or 7 Second Value = n
where n is
the number
of times the
error occurs
FVF ? Format and variable type do not match
Cause: An attempt was made to READ or WRITE character data
with other than A or G format.
Recovery: Specify A or G edit descriptors when reading character
D-27
FOROTS ERROR MESSAGES
data.
ERRSNS values: First Value = 62 Second Value = 583
FVM % Format and variable type do not match
Cause: An I/O statement has been executed that uses a format
edit descriptor with a type that does not match the I/O
list item being processed.
Recovery: Specify the appropriate format edit descriptor for the
I/O list item.
ERRSNS values: First Value = 22 Second Value = 583
IAC ? /ACCESS illegal for this device
Cause: An attempt was made to OPEN a device for which the
access specified (or implied) is illegal.
Recovery: Change the ACCESS specifier in the OPEN statement or
data transfer statement. (See Section 11.3.1.)
ERRSNS values: First Value = 30 Second Value = 248
IAV ? Illegal value for OPEN specifier
Cause: An OPEN statement specifier has a value illegal for
that specifier.
Recovery: Specify a legal value for that OPEN specifier.
ERRSNS values: First Value = 30 Second Value = 585
ICA ? Incompatible attributes
Cause: An illegal combination of open attributes has been
specified.
Recovery: Change one or more of the conflicting specifiers.
ERRSNS values: First Value = 30 Second Value = 506
ICD ? Non-digit in record delimiter
Cause: The format of the tape being read is not 'D'
(DELIMITED). The Record Control Word (RCW) contained a
D-28
FOROTS ERROR MESSAGES
non-digit, or the data on the tape is incompatible.
Recovery: Specify the correct TAPEFORMAT in the OPEN statement.
ERRSNS values: First Value = 25 Second Value = 570
ICE ? Illegal length for character expression
Cause: A program has specified a zero length or negative
length character substring as an I/O list element.
Recovery: Fix program to specify a positive length substring.
ERRSNS values: First Value = 81 Second Value = 599
IDC % Integer divide check
Cause: Program contains an integer division by 0.
Recovery: Correct division in program.
ERRSNS values: First Value = 1 Second Value = n
where n is
the number
of times the
error occurs
IDD ? Illegal character <chr> (TOPS-10 only)
Cause: An illegal character was encountered in dialog mode.
Recovery: Retype the response without illegal characters.
ERRSNS values: First Value = 45 Second Value = 548
IDI ? Illegal DUMP mode I/O list (TOPS-10 only)
Cause: An I/O list entry has been specified whose entry size
(number of words) is different from its increment.
This can only happen if an implied DO loop is specified
for the I/O list, the index increment is set to a value
other than 1, and the program is compiled with
/OPTIMIZE.
Recovery: Use an index increment of 1, or do not compile the
program with /OPTIMIZE.
ERRSNS values: First Value = 81 Second Value = 579
D-29
FOROTS ERROR MESSAGES
IDM ? /MODE:<mode> illegal for this device
Cause: Not all devices can do I/O in all modes. For example,
terminals cannot do binary I/O.
Recovery: Change the MODE= specifier or the device. (See Section
| 11.3.24.)
ERRSNS values: First Value = 30 Second Value = 249
IDU ? DIVERT: illegal to divert to unit <n>
Cause: Unit specified is an input-only device.
Recovery: Specify a unit for which output is legal.
ERRSNS values: First Value = 21 Second Value = 104
IEM ? FOROTS internal error in memory management
Cause: This is an internal error that is not expected to
occur. It means that the memory management routines
have detected a problem with their control information.
Recovery: Submit an SPR.
IFW ? Illegal field width
Cause: An illegal (negative) field width was specified in a
FORMAT statement.
Recovery: Specify a legal field width in the FORMAT statement.
ERRSNS values: First Value = 62 Second Value = 553
IHC ? Illegal Hollerith constant
Cause: A format specification contains an H edit descriptor
that is not preceded by a length or does not contain
enough characters.
Recovery: Use the correct format for an H edit descriptor. (See
Section 12.4.2.)
ERRSNS values: First Value = 62 Second Value = 552
IJE ? "Impossible" JSYS error at <PC> - <JSYS ERROR> (TOPS-20 only)
D-30
FOROTS ERROR MESSAGES
Cause: This is an internal FOROTS error that is not expected
to occur. A monitor call failed that was not expected
to. A monitor-supplied error message may be of
assistance in avoiding the problem.
Recovery: Submit an SPR.
ILC ? Illegal character in data
Cause: A format descriptor that requires a number found a
nonnumeric character.
Recovery: Fix the input data or FORMAT statement.
ERRSNS values: First Value = 64 Second Value = 307
ILF ? Illegal character in format
Cause: A format specification contains a character with no
defined meaning.
Recovery: Correct the error in the format list and rerun the
program.
ERRSNS values: First Value = 62 Second Value = 301
ILM ? Unexpected MTOPR% ERROR (TOPS-20 only)
Cause: An error was encountered during a file operation that
FOROTS did not expect.
Recovery: This type of error should not happen. Please submit an
SPR.
ERRSNS values: First Value = 96 Second Value = JSYS error
number
ILN ? Variable or namelist does not start with letter
Cause: NAMELIST input contains something other than a legal
variable or NAMELIST name in a context where a variable
or NAMELIST name is required.
Recovery: Correct the source program with a legal variable or
NAMELIST name. (See Section 12.6.)
ERRSNS values: First Value = 97 Second Value = 515
D-31
FOROTS ERROR MESSAGES
ILS ? Illegal subscript
Cause: In NAMELIST I/O, an illegal subscript was given for an
array.
ERRSNS values: First Value = 97 Second Value = 516
IMV ? Illegal MTOP value
Cause: A MARCO program has issued an MTOP call to FOROTS with
an illegal value for the function.
Recovery: Specify a legal function value in the call.
ERRSNS values: First Value = 81 Second Value = 574
IOE ? <IO error message>
Cause: An I/O error has occurred. The monitor error code is
given, along with an interpretation of the probable
meaning of the error bits. This message normally
indicates that the data recorded on an external device
has been damaged and cannot be read correctly.
ERRSNS values: First Value = 98 Second Value = 400 (TOPS-10)
JSYS error
number
(TOPS-20)
IOL ? Bad format IO list
Cause: The code generated by the compiler for an I/O list is
not understood by this version of FOROTS. The
erroneous entry in the I/O list is ignored. This
probably indicates an internal error in the compiler or
in FOROTS.
Recovery: Locate the problem area of the I/O list and simplify
it.
ERRSNS values: First Value = 81 Second Value = 508
IOV % Integer overflow
Cause: An attempt was made to read data that was out of range
for an integer variable.
D-32
FOROTS ERROR MESSAGES
ERRSNS values: First Value = 2 Second Value = 0
IPP ? Illegal PPN (TOPS-10 only)
Cause: A directory specification starts with something that is
not a legal PPN specification. The forms of legal PPNs
are:
[n,n], [n,], [,n], or [,]
where n represents a 1- to 6-digit octal number.
Recovery: Use a legal directory specification.
ERRSNS values: First Value = 45 Second Value = 545
IPN ? Illegal page number <n>
Cause: A call to TOPMEN or SRTINI has specified a page number
outside the range 1:777.
Recovery: Specify a correct page number
ERRSNS values: First Value = 21 Second Value = 122
IRC ? Illegal repeat count
Cause: An illegal repeat count was given in a FORMAT
statement.
Recovery: Correct the FORMAT statement.
ERRSNS values: First Value = 62 Second Value = 538
IRN ? Illegal record number <n>
Cause: A direct-access I/O statement has specified a record
number that is zero or negative.
Recovery: Correct the invalid record number in the program.
ERRSNS values: First Value = 25 Second Value = 512
ISS ? Illegal substring descriptor
Cause: An I/O statement refers to an illegal substring
delimiter (substring not within bounds of string).
D-33
FOROTS ERROR MESSAGES
Recovery: Correct the substring specifier.
ERRSNS values: First Value = 97 Second Value = 597
ISW ? Can't switch to input
Cause: A file that was being written cannot be open for
output. The file is either protected against reading,
or has been deleted before the OPEN for read is
executed.
Recovery: Specify correct protection for OPEN write.
ERRSNS values: First Value = 98 Second Value = 250+n
(TOPS-10)
JSYS error
number
(TOPS-20)
ITE ? Tape is not usable by your job (TOPS-10 only)
Cause: A tape unit was specified or implied that is not owned
by your job, and is probably owned by another job.
Recovery: ASSIGN the drive or MOUNT the tape.
ERRSNS values: First Value = 96 Second Value = 587
IUN ? Illegal unit number <n>
Cause: An I/O statement has specified a unit number that is
negative or too large.
Recovery: Change the UNIT specifier value and rerun the program.
ERRSNS values: First Value = 32 Second Value = 239
IWI ? Illegal to initiate another I/O statement while processing
<I/O statement)
Cause: An I/O statement, STOP statement, or PAUSE statement
has been initiated while processing another I/O
statement (such as in a function reference used as an
I/O list element), or while within a subroutine called
as a result of an I/O error through ERRSET.
Recovery: Remove the offending I/O statement, STOP statement, or
D-34
FOROTS ERROR MESSAGES
PAUSE statement.
ERRSNS values: First Value = 81 Second Value = 582
| KDB ? KEY datatype CHARACTER conflicts with BYTESIZE (TOPS-20 only)
|
| Cause: You specified or defaulted a KEY= datatype to
| CHARACTER, but specified a BYTESIZE not equal to 7
| (TOPS-20 file) or 8 (VMS file).
|
| Recovery: Specify correct BYTESIZE or omit to use system default.
|
| ERRSNS values: First Value = 30 Second Value = 612
|
|
| KER ? New indexed file requires KEY= (TOPS-20 only)
|
| Cause: You attempted to create a new RMS indexed file without
| specifying a primary index
|
| Recovery: Specify one or more KEY= specifiers in your OPEN.
|
| ERRSNS values: First Value = 30 Second Value = 606
|
|
| KRI ? Can't do keyed I/O to <sequential/relative> file (TOPS-20 only)
|
| Cause: You attempted a keyed (indexed) READ to an RMS
| sequential or relative file.
|
| Recovery: Correct the invalid READ statement in the program.
|
| ERRSNS values: First Value = 31 Second Value = 605
|
|
| MEU ? Missing EXTERNAL declaration in a call to USEROPEN routine
| (TOPS-20 only)
|
| Cause: You specified a USEROPEN routine but did not declare it
| EXTERNAL in the program.
|
| Recovery: Supply the EXTERNAL declaration.
|
| ERRSNS values: First Value = 30 Second Value = 604
MFU ? Memory full
Cause: There is insufficient memory to complete execution of
the program.
D-35
FOROTS ERROR MESSAGES
Recovery: Some memory can be saved by opening fewer files at a
time, by using BUFFERCOUNT=1 in OPEN statements, and by
using minimal tape block sizes. If these techniques do
not help, you can segment the program using LINK's
overlay facility (see the LINK Reference Manual).
NCA ? No memory available for character stack
Cause: For non-overlay programs, this message indicates that
the memory manager has allocated all available space
between the user's low segment and FOROTS. For overlay
programs, this messages indicates that /SPACE:0 has
been specified to LINK.
Recovery: For non-overlay programs, LINK with /OTS:NONSHARE. For
overlay programs, specify at least 1000 to the /SPACE
switch in LINK (see the LINK Reference Manual).
ERRSNS values: First Value = 21 Second Value = 111
NCK % <keyword> in CLOSE is meaningless - ignored
Cause: Options have been included in the CLOSE statement that
are meaningless for closing the file.
Recovery: Use valid CLOSE options. (See Section 10.17.)
ERRSNS values: First Value = 26 Second Value = 542
NCS ? No character stack allocated - compiler error
Cause: An internal compiler error has occurred.
Recovery: Submit an SPR.
ERRSNS values: First Value = 21 Second Value = 110
NDI ? No device specified with ":" (TOPS-10 only)
Cause: An OPEN statement has specified a null device name.
ERRSNS values: First Value = 45 Second Value = 544
NEC ? Found "<chr>" when expecting ":"
Cause: Substring parameters not separated by ":"
D-36
FOROTS ERROR MESSAGES
Recovery: Insert a ":" between substring parameters.
ERRSNS values: First Value = 97 Second Value = 596
NEQ ? Found "<chr>" when expecting "="
Cause: NAMELIST input found an illegal character in a context
that requires an equal sign.
Recovery: Replace illegal character with equal sign.
ERRSNS values: First Value = 97 Second Value = 513
NFC ? Too many open units (TOPS-10 only)
Cause: On TOPS-10 monitors before version 7.00, at most, only
16 units can be open at the same time.
Recovery: Arrange the program so that it never needs to have more
than 16 simultaneously open units.
ERRSNS values: First Value = 30 Second Value = 242
NLS ? Null string illegal
Cause: An attempt was made to input to a zero length string
during list-directed input.
Recovery: Insert characters into the string, or remove the string
delimiting quotes.
ERRSNS values: First Value = 97 Second Value = 580
| NNI % Node name ignored (TOPS-10 only)
|
| Cause: Remote file access is not supported on TOPS-10.
|
| Recovery: Omit the node specification from the filespec.
|
| ERRSNS values: First Value = 26 Second Value = 609
NQS ? PADCHAR must be single char in double quotes (TOPS-10 only)
Cause: In dialog mode, the PADCHAR specifier must be followed
by the pad character in double quotes.
ERRSNS values: First Value = 45 Second Value = 551
D-37
FOROTS ERROR MESSAGES
NRP ? Missing right paren
Cause: In NAMELIST or list-directed complex input, the closing
right parenthesis that ends a complex number was not
found.
ERRSNS values: First Value = 97 Second Value = 514
NSD ? No such device <dev>
Cause: The specified device does not exist.
Recovery: Change the device name to one that does exist.
ERRSNS values: First Value = 30 Second Value = 245
NSI ? Null SFD (TOPS-10 only)
Cause: A directory specification contains a null SFD.
ERRSNS values: First Value = 45 Second Value = 547
NSS ? No free section available for SORT (TOPS-20 only)
Cause: SORT runs it its own section on machines that support
extended addressing. There are no free sections
available.
Recovery: There are 31 sections normally available when a simple
FORTRAN program runs. If your application is not
trying to use extended addressing, this error should
not occur, and you should submit an SPR.
ERRSNS values: First Value = 21 Second Value = 118
OGX % Galaxy version 2 not supported (TOPS-10 only)
Cause: Your system is using an unsupported version of GALAXY.
Recovery: Inform the system administrator to upgrade to the
supported version of GALAXY.
ERRSNS values: First Value = 26 Second Value = 595
OPN ? Can't OPEN file
Cause: The specified file could not be opened. The reason
D-38
FOROTS ERROR MESSAGES
given is taken from the monitor error code (see the
TOPS-10 Monitor Calls Manual).
ERRSNS values: First Value = 30 Second Value = 250+n
OSW ? FILOP. error n - can't switch to output
Cause: An attempt to open a file for write access which has
previously been open for read-only access failed.
Recovery: Change protection code; remove other file access.
ERRSNS values: First Value = 98 Second Value = 250+n
(TOPS-10)
JSYS error
number
(TOPS-20)
PAG % Pages allocated but not deallocated
Cause: Internal FOROTS error in memory management.
Recovery: Submit an SPR and include your program.
PGD ? Deallocating more pages than allocated
Cause: Internal FOROTS error in memory management.
Recovery: Submit an SPR and include your program.
POI ? <file positioning operation> Illegal for DIRECT (RANDOM) file
Cause: A file positioning operation (such as REWIND or
BACKSPACE) was attempted on a file open for
DIRECT(RANDOM) access.
Recovery: Remove the file positioning statement.
ERRSNS values: First Value = 31 Second Value = 593
PPN ? <JSYS error> (TOPS-20 only)
Cause: A TOPS-20 OPEN statement has specified a PPN instead of
a directory name, but the PPN has no matching
directory.
D-39
FOROTS ERROR MESSAGES
Recovery: Specify the correct PPN, or better yet, specify the
directory name instead.
ERRSNS values: First Value = 30 Second Value = 405
RBR ? REREAD not preceded by READ
Cause: A REREAD statement was encountered before any READ
statement. A READ must be executed first so there is
something to reread.
Recovery: Cause a READ statement to be executed first.
ERRSNS values: First Value = 39 Second Value = 310
RLB ? /RECORDSIZE larger than /BLOCKSIZE
Cause: A RECORDSIZE was specified in an OPEN statement that is
larger than the specified or implied BLOCKSIZE.
Recovery: Correct either RECORDSIZE or BLOCKSIZE, or specify
BLOCKSIZE if it is not specified.
ERRSNS values: First Value = 30 Second Value = 244
RIC ? Reading into character format illegal
Cause: An attempt was made to READ into a character format.
Recovery: Correct program to avoid this construct. READ into a
character variable and use this variable (perhaps
concatenated with other character expressions) for a
modifiable format.
ERRSNS values: First Value = 62 Second Value = 524
RIF % Reading into FORMAT nonstandard
Cause: A READ statement was executed that reads data into a
Hollerith or quoted string in a FORMAT statement. This
is a practice contrary to the ANSI standard and is
likely not to work in future releases of FORTRAN-10/20.
Recovery: READ into character variables and use (perhaps
concatenated with character constants) as the FORMAT.
ERRSNS values: First Value = 22 Second Value = 584
D-40
FOROTS ERROR MESSAGES
| RIR ? New RELATIVE or INDEXED file requires /RECORDSIZE (TOPS-20
| only)
|
| Cause: You tried to create (STATUS='NEW') an RMS relative or
| indexed file without specifying a record length.
|
| Recovery: Specify /RECORDSIZE.
|
| ERRSNS values: First Value = 30 Second Value = 613
|
|
| RMS ? RMS file requires ORGANIZATION in OPEN statement (TOPS-20 only)
|
| Cause: The OPEN statement did not specify an RMS file by means
| of ORGANIZATION=, but the file you tried to open is an
| RMS file.
|
| Recovery: Supply an ORGANIZATION attribute.
|
| ERRSNS values: First Value = 30 Second Value = 608
|
|
| RNA ? RMS not available on SYS:
|
| Cause: Your program tried to invoke RMS (an OPEN specified a
| remote or RMS file, or an INQUIRE-by-file specified a
| remote file) when RMS is not available on your system.
|
| Recovery: Make sure your system supports RMS V3 and/or RMSFAL V1.
|
| ERRSNS values: First Value = 30 Second Value = 615
RNM ? Can't rename file
Cause: An attempt to rename the specified file failed.
Recovery: Change file protection, remove other file access.
ERRSNS values: First Value = 28 Second Value = 250+n
(TOPS-10)
JSYS error
number
(TOPS-20)
RNR ? Record <n> has not been written
Cause: In direct-access input, an attempt was made to read a
record that was never written. This may indicate the
use of an incorrect record number.
D-41
FOROTS ERROR MESSAGES
Recovery: Make sure you are requesting the correct record.
ERRSNS values: First Value = 25 Second Value = 510
RPE ? Illegal repeat count
Cause: In NAMELIST or list-directed input, a repeated constant
was found, but the repeat count is not a positive
integer.
Recovery: Correct the input and try again.
ERRSNS values: First Value = 97 Second Value = 521
RR1 ? Random I/O requires RECORDSIZE specifier in OPEN statement
Cause: Direct-access I/O was attempted to a file that has not
been opened with the RECL or RECORDSIZE specifier to
give the size of the record(s).
Recovery: Specify a record size. The record size is in
characters for formatted files, words for unformatted
| files. (See Section 11.3.33.)
ERRSNS values: First Value = 30 Second Value = 240
RRR ? Random IO requires /RECORDSIZE
Cause: An OPEN statement was attempted that specified
ACCESS=DIRECT(RANDOM) with no record size specified
Recovery: Specify a record size.
ERRSNS values: First Value = 30 Second Value = 240
RSM ? Record size different from that specified
Cause: A record size found in a binary record is different
than that specified in the OPEN statement.
Recovery: Specify the correct record size in the OPEN statement.
ERRSNS values: First Value = 25 Second Value = 572
SDO ? Same device open on unit with conflicting specifiers
Cause: An OPEN statement was attempted for a device for which
D-42
FOROTS ERROR MESSAGES
another OPEN or data transfer statement had been
already executed, and the file specifications were in
conflict.
Recovery: Change file specifications
ERRSNS values: First Value = 30 Second Value = 540
| SIF ? <statement> illegal for this file type or access (TOPS-20 only)
|
| Cause: Your program attempted to execute a statement on a
| non-RMS file, which is legal only for RMS files; or a
| file-positioning, DELETE, UNLOCK or REWRITE statement
| was attempted on an RMS file when either /ACCESS or
| /ORGANIZATION does not permit the operation.
|
| Recovery: Correct the invalid statement in the program.
|
| ERRSNS values: First Value = 31 Second Value = 614
SLN ? Record length negative or zero
Cause: An ENCODE or DECODE statement was initiated that has a
negative or zero value for the record (string) length.
Recovery: Correct program to specify a legal record length.
ERRSNS values: First Value = 25 Second Value = 577
SNH ? Internal FOROTS error at <PC>
Cause: This error is not expected to occur. An internal
consistency check has found a bug.
Recovery: Please submit an SPR if you get this message.
SNQ ? String not within single quotes
Cause: A character data item read as list-directed or NAMELIST
input is not enclosed in single quotes.
Recovery: Enclose character data item in single quotes.
ERRSNS values: First Value = 97 Second Value = 598
SNV ? Sign with null value
D-43
FOROTS ERROR MESSAGES
Cause: List-directed or NAMELIST input contains a + or - sign
not followed by a value.
Recovery: Correct the input and try again.
ERRSNS values: First Value = 97 Second Value = 522
SRE % Subscript range error - subscript <n> of array <name> on line
<n>
Cause: An illegal subscript or range has been specified for an
array reference.
Recovery: Specify a legal array reference.
ERRSNS values: First Value = 23 Second Value = 114
SSE % Substring range error <var(bound)> on line <n>
Cause: An illegal substring bound or range has been specified
in a character expression.
Recovery: Specify a legal reference.
ERRSNS values: First Value = 23 Second Value = 113
TFM ? Tape format conflicts with OPEN statement or default
Cause: The actual format of the tape (either CORE-DUMP or
INDUSTRY) conflicts with the format specified in the
OPEN statement or by the monitor. At this point, the
file is already opened in the wrong format.
Recovery: Specify the correct TAPEFORMAT in the OPEN statement or
with the EXEC.
ERRSNS values: First Value = 30 Second Value = 569
| TKS ? Too many KEY specifiers (TOPS-20 only)
|
| Cause: RMS allows a maximum of 255 indexes for an indexed
| file.
|
| Recovery: Reduce the number of KEY= specifiers.
|
| ERRSNS values: First Value = 30 Second Value = 607
D-44
FOROTS ERROR MESSAGES
TMA ? Too many arguments in call to SORT
Cause: When the first argument in a call to SORT is a
character constant, the argument list must be copied in
order to convert the argument to a Hollerith constant.
At most, 10 arguments can be copied.
Recovery: Change the first argument to a Hollerith constant, or
use less than 10 arguments.
ERRSNS values: First Value = 21 Second Value = 115
TMF ? Too many SFDs (TOPS-10 only)
Cause: A directory specification contains more than five SFDs.
Recovery: Specify the correct directory.
ERRSNS values: First Value = 45 Second Value = 546
| UDO ? Unsupported /DISPOSE:<option> for RMS files (TOPS-20 only)
|
| Cause: PRINT, LIST, PUNCH, SUBMIT or PLOT was specified for a
| TOPS-20 RMS file; or PUNCH or PLOT specified for a VMS
| RMS file.
|
| Recovery: Correct the specifier.
|
| ERRSNS values: First Value = 28 Second Value = 610
UDT ? Undefined data type or internal FOROTS error
Cause: Internal FOROTS error.
Recovery: Submit an SPR.
ERRSNS values: First Value = 62 Second Value = 575
UME ? Unexpected MTCHR error <n> (TOPS-10 only)
Cause: This message is not expected to occur. It indicates
that a MTCHR UUO has failed. The monitor-supplied
error code may give some indication of the reason.
Recovery: Submit an SPR.
ERRSNS values: First Value = 96 Second Value = 531
D-45
FOROTS ERROR MESSAGES
UMO % <JSYS error> trying to set tape <density/parity/data mode>
(TOPS-20 only)
Cause: It was not possible to set the indicated parameter of
the tape. The monitor error message gives the reason.
Recovery: Make sure you are using a drive that supports the
requested operations.
ERRSNS values: First Value = 96 Second Value = JSYS error
number
UNO ? DIVERT: unit <n> is not open
Cause: The file to which error messages are diverted must be
opened for output before DIVERT is called.
Recovery: Open the file for output before calling DIVERT.
ERRSNS values: First Value = 21 Second Value = 105
UNS ? Unit not specified
Cause: A call was made to FOROTS which did not contain a unit
number.
Recovery: Correct calling code.
ERRSNS values: First Value = 81 Second Value = 501
UOA % Unknown OPEN keyword <n>, ignored
Cause: The compiler has generated an OPEN call that contains
an unknown keyword. The keyword is ignored.
Recovery: Make sure you are using the correct versions of the
compiler, FORLIB, and FOROTS.
ERRSNS values: First Value = 26 Second Value = 541
| URS ? Unsupported remote system (TOPS-20 only)
|
| Cause: A remote file access specified a remote system that is
| not either TOPS-20 or VMS.
|
| Recovery: Specify a TOPS-20 or VMS node.
|
| ERRSNS values: First Value = 30 Second Value = 602
D-46
FOROTS ERROR MESSAGES
| URT ? Recordtype <type> not supported for this file type (TOPS-20
| only)
|
| Cause: /RECORDTYPE:STREAM was specified for a TOPS-20 RMS
| file; or RMS returned a recordtype other than STREAM,
| VARIABLE or FIXED for an existing remote file.
|
| Recovery: Correct the invalid /RECORDTYPE.
|
| ERRSNS Values: First Value = 30 Second Value = 601
USW ? Unknown switch /<sw> (TOPS-10 only)
Cause: In dialog mode, an unknown switch was specified.
Recovery: Retype the line, specifying the correct switch.
ERRSNS values: First Value = 45 Second Value = 241
UTE ? Unexpected TAPOP error <n> (TOPS-10 only)
Cause: This message is not expected to occur. It indicates
that a TAPOP UUO has failed. The monitor-supplied
error code may give some indication of the reason.
Recovery: Submit an SPR.
ERRSNS values: First Value = 96 Second Value = 530
UTO % Unexpected TAPOP. error <n> trying to set <density/parity/data
mode/blocksize> (TOPS-10 only)
Cause: It is not possible to set the indicated parameter of
the tape. The monitor error message gives the reason.
Recovery: Make sure you are using a drive that supports the
requested operation.
ERRSNS values: First Value = 96 Second Value = 537
VNN ? Variable <var> not in namelist
Cause: NAMELIST input contains an assignment to a variable
that is not in the namelist.
Recovery: Correct the input and try again.
ERRSNS values: First Value = 97 Second Value = 309
D-47
FOROTS ERROR MESSAGES
WBA ? Attempt to WRITE beyond variable or array
Cause: An attempt was made to write beyond the end of a
character variable or array with an internal file WRITE
statement.
Recovery: Correct program to stay within limits of character
variable or array.
ERRSNS values: First Value = 25 Second Value = 576
D-48
APPENDIX E
INTERACTIVE DEBUGGER (FORDDT) ERROR MESSAGES
FORDDT responds with two levels of messages - fatal error and warning.
Fatal error messages indicate that the processing of a given command
has been terminated. Warning messages provide helpful information.
The format of these messages is:
?FDTxxx text
or
%FDTxxx text
where:
? indicates a fatal message
% indicates a warning message
FDT is the FORDDT mnemonic
xxx is the 3-letter mnemonic for error message
text is the explanation of error
Square brackets ([ ]) in this section signify variables and are not
output on the terminal.
Fatal Errors
The fatal errors in the following list are each preceded by ?FDT on
the user terminal. They are listed in alphabetical order.
BDF [symbol] is undefined
[symbol] is multiply defined
BOI Bad octal input
An illegal character was detected in an octal input value.
CCN Cannot continue
A pause has been placed on some form of skip instruction
causing FORDDT to loop; should never be encountered in
FORTRAN-compiled programs.
E-1
INTERACTIVE DEBUGGER (FORDDT) ERROR MESSAGES
CFO Core file overflow
The storage area for GROUP text has been exhausted.
CNU The command [name] is not unique
More letters of the command are required to distinguish it
from the other commands.
CSH Cannot START here
The specified entry point is not an acceptable FORTRAN main
program entry point.
DNA Double-precision comparisons not allowed
DTO Dimension table overflow
FORDDT does not have the space to record any more array
dimensions until some are removed.
FCX Format capacity exceeded
An attempt was made to specify a FORMAT statement requiring
more space than was originally allocated by the FORTRAN
compiler.
FNI Formal not initialized, please retype
There was a reference to a formal parameter of some
subprogram that was never executed.
FNR [array name] is a formal and may not be redefined
Formal parameters may not be DIMENSIONed.
IAF Illegal argument format [rest of user line]
The parameters to the given command were not specified
properly. Refer to the documentation for correct format.
IAT Illegal argument type = [number]
An unrecognized subprogram argument type was detected.
Submit an SPR if this message occurs.
ICC Comparison of two constants is not allowed
A conditional test involves two constants.
IER Internal FORDDT error [number]
E-2
INTERACTIVE DEBUGGER (FORDDT) ERROR MESSAGES
Internal FORDDT error - please report through an SPR.
IGN Invalid group number
Group numbers must be integers and in the range one through
eight.
INV Invalid value [rest of user line]
A syntax error was detected in the numeric parameter.
IPN Illegal program name
IRS Illegal range specification
The particular range specified for an array is not defined.
ITM Illegal type modifier - S
The mode S is only valid for ACCEPT statements.
IWI I/O within I/O error
An attempted TYPE or ACCEPT command cannot be executed
because a fatal "I/O within I/O" error from FOROTS would
result, since the user program is currently processing an
IOLST call.
JSE [JSYS error message]
Error reading program name (on TOPS-20 or some other FORDDT
input).
LGU [array name] lower subscript .GE. upper
The lower bound of any given dimension must be less than or
equal to the upper bound.
LNF [label] is not a FORMAT statement
MCD Compile program with the DEBUG switch to type a FORMAT
statement
MLD [array name] multi-level array definition not allowed
The same array cannot be dimensioned more than once (by
means of the [dimensions] construct) in a single command.
MSN More subscripts needed
The array is defined to have more dimensions than were
specified in the given reference.
E-3
INTERACTIVE DEBUGGER (FORDDT) ERROR MESSAGES
NAL Not allowed
An attempt has been made to modify something other than data
or a FORMAT.
NAR Not after a reenter
The given command is not allowed until program integrity has
been restored by means of a CONTINUE or NEXT command.
NDT DDT not loaded
NFS Cannot find FORTRAN start address for [program name]
Main program symbols are not loaded.
NFV [symbol] is not a FORTRAN variable
Names must be 6-character alphanumeric strings beginning
with a letter.
NGF Cannot GOTO a FORMAT statement
NPH Cannot insert a PAUSE here
An attempt has been made to place a breakpoint at other than
an executable statement or subprogram entry point.
NSP [symbol] no such PAUSE
An attempt has been made to REMOVE a breakpoint that was
never set up.
NUD [symbol] not a user-defined array
An attempt has been made to remove dimension information for
an array that was never defined.
PAR Parentheses required, please retype
Parentheses are required for the specification of FORMAT
statements and complex constants.
PRO Too many PAUSE requests
The PAUSE table has been exhausted. The maximum limit is
10.
RGR Recursive group reference
A group may not reference itself.
E-4
INTERACTIVE DEBUGGER (FORDDT) ERROR MESSAGES
SER Subscript error
The subscript specified is outside the range of its defined
dimensions.
STL [array name] size too large
An attempt has been made to define an array larger than
256K.
TMS Too many subscripts [dimensions]
The array is defined to have fewer dimensions than are
specified in the given element reference.
URC Unrecognized command [command]
Warning Messages
Each warning message is preceded by %FDT on your terminal. The
warning messages are listed here in alphabetical order.
ABX [array name] compiled array bounds exceeded
FORDDT has detected another symbol defined in the specified
range of the array. Note that this will occur in certain
EQUIVALENCE cases and can be ignored at that time.
CAB Cannot allocate buffer for help file
CHI Characters ignored: "[text]"
The portion of the command string included in "text" was
thought to be extraneous and was ignored.
ECI Buffer full - excess characters ignored
EOH Error opening help file
IOE I/O error reading help file
IWI I/O within I/O
FORDDT has PAUSEd at a breakpoint while the user program is
currently processing an IOLST call. TYPE and ACCEPT
commands cannot be processed at this breakpoint.
NAA [symbol] is not an array
NHF Cannot find help file; I'm sorry I can't help you
E-5
INTERACTIVE DEBUGGER (FORDDT) ERROR MESSAGES
NSL No symbols loaded
FORDDT cannot find the symbol table.
NST Not STARTed
The specified command requires that a START be previously
issued to ensure that the program is properly initialized.
POV Program overlayed by [program name]
Program overlayed by ***
The symbol table is different from the last time FORDDT had
control. The program name is printed only if it has
changed, otherwise '***' is printed.
SCA Supersedes compiled array dimension
The FORTRAN generated dimension is being superseded for the
given array.
SPO Variable is single-precision only
WSP Writing to shared page
XPA Attempt to exceed program area with [symbol name]
An attempt has been made to access memory outside the
currently defined program space.
E-6
APPENDIX F
FORTRAN-SUPPLIED PLOTTER SUBROUTINES
The FORTRAN subroutine library contains a set of subroutines that are
used with plotting devices. To successfully use these routines, a
plotter must be connected to your system. The FORTRAN software
contains the following plotter subroutines:
PLOTS The PLOTS subroutine initializes the plotter or reports if
the plotter is not available. This must be the first
plotter subroutine specified. (See Section F.1.)
AXIS The AXIS subroutine draws an axis with tic marks and scale
values at 1-inch increments. An identifying label may also
be plotted along the axis. (See Section F.2.)
CAXIS The CAXIS subroutine performs the same functions as the AXIS
subroutine. (See Section F.3.)
LINE The LINE subroutine draws a line through the points
specified. (See Section F.4.)
MKTBL The MKTBL subroutine specifies a special character set.
(See Section F.5.)
NUMBER The NUMBER subroutine causes floating-point numbers to be
plotted as text. (See Section F.6.)
PLOT The PLOT subroutine moves the plotter pen to a new position.
Raising and lowering the pen is also specified in the PLOT
subroutine. (See Section F.7.)
SCALE The SCALE subroutine selects scale values for the AXIS or
CAXIS subroutine. (See Section F.8.)
SETABL The SETABL subroutine specifies a character set. (See
Section F.9.)
SYMBOL The SYMBOL subroutine raises the plotter pen, moves it to
the position specified by x and y, and plots a string of
F-1
FORTRAN-SUPPLIED PLOTTER SUBROUTINES
characters. (See Section F.10.)
WHERE The WHERE subroutine reports on the current position of the
plotter pen. (See Section F.11.)
PLOTS
Subroutine
F.1 PLOTS SUBROUTINE
The PLOTS subroutine initializes the plotter or reports if the plotter
is not available. This must be the first plotter subroutine
specified.
The form of the PLOTS subroutine is:
CALL PLOTS(i[,steps])
where:
i is an integer variable, which is set to -1 if the
plotter is not available, or set to 0 if the plotter is
available.
The plotter may not be available because: the system
does not have a plotter; the plotter is in use by
another user; the plotter is turned off; or the plotter
is being spooled, but you are trying to write to it
directly.
steps is an optional floating-point variable or constant that
specifies the number of steps (per inch) used by the
plotter. The default is 100 steps per inch, and may be
changed by the installation. Commonly, plotters plot
100 steps per inch, 200 steps per inch, or 100 steps
per centimeter (about 254 steps per inch).
AXIS
Subroutine
F-2
FORTRAN-SUPPLIED PLOTTER SUBROUTINES
F.2 AXIS SUBROUTINE
The AXIS subroutine draws an axis with tic marks and scale values at
1-inch increments. An identifying label may also be plotted along the
axis.
NOTE
The AXIS subroutine is provided for compatibility with
previous versions of FORTRAN-10/20. The AXIS
subroutine uses a numeric array to contain the label
that is plotted along the axis. The CAXIS subroutine
(see Section F.3) allows a character expression to
contain the label.
The form of the AXIS subroutine is:
CALL AXIS(x,y,asc,nasc,size,theta,xmin,dx)
where:
x,y is a variable or constant pair that specifies the
starting point of the axis.
asc is the name of a numeric array that contains a label
that is plotted along the axis.
nasc is an integer constant or variable that specifies the
number of characters contained in array asc. If nasc
is negative, the label in the array is placed on the
clockwise side of the axis. If nasc is positive, the
tic marks, label, and scale values are placed on the
counterclockwise side of the axis.
size is a constant or variable that specifies the length of
the axis in inches.
theta is a constant or variable that specifies the angle at
which the axis is plotted. The value of theta is
usually 0.0 or 90.0.
xmin is a variable or constant that specifies the value of
the scale at the beginning of the axis.
dx is a variable or constant that specifies the change in
scale for a 1-inch increment.
NOTE
The proper values for xmin and dx may be
determined by calling the SCALE subroutine (see
F-3
FORTRAN-SUPPLIED PLOTTER SUBROUTINES
Section F.8).
CAXIS
Subroutine
F.3 CAXIS SUBROUTINE
The CAXIS subroutine draws an axis with tic marks and scale values at
1-inch increments. An identifying label may also be plotted along the
axis.
The form of the CAXIS subroutine is:
CALL CAXIS(x,y,asc,sign,size,theta,xmin,dx)
where:
x,y is a variable or constant pair that specifies the
starting point of the axis.
asc is the name of a character expression that contains a
label that is plotted along the axis.
sign If nasc is negative, the label in the array is placed
on the clockwise side of the axis. If nasc is
positive, the tic marks, label, and scale values are
placed on the counterclockwise side of the axis.
size is a constant or variable that specifies the length of
the axis in inches.
theta is a constant or variable that specifies the angle at
which the axis is plotted. The value of theta is
usually 0.0 or 90.0.
xmin is a variable or constant that specifies the value of
the scale at the beginning of the axis.
dx is a variable or constant that specifies the change in
scale for a 1-inch increment.
F-4
FORTRAN-SUPPLIED PLOTTER SUBROUTINES
NOTE
The proper values for xmin and dx may be
determined by calling the SCALE subroutine (see
Section F.8).
LINE
Subroutine
F.4 LINE SUBROUTINE
The LINE subroutine draws a continuous line through a set of points.
The form of the LINE subroutine is:
CALL LINE(x,y,n,k)
where:
x is the name of an array that contains the floating-point
x-coordinates of the points to be plotted.
y is the name of an array that contains the floating-point
y-coordinates of the points to be plotted.
n is an integer constant or variable that specifies the total
number of points to be plotted.
k is an integer constant or variable that equals the number of
elements of x and y. Since single-precision one-dimensional
arrays are usually used, this value is usually 1.
MKTBL
Subroutine
F.5 MKTBL SUBROUTINE
The MKTBL subroutine defines a special character set to be used when
F-5
FORTRAN-SUPPLIED PLOTTER SUBROUTINES
plotting; the SETABL subroutine (see Section F.9) enables you to use
the character set defined by the MKTBL subroutine.
The form of the MKTBL subroutine is:
CALL MKTBL(setnumber,tableaddress)
where:
setnumber is an integer variable from 1 to 10 that specifies
the numeric identifier of the character set, for
example, the number of the ASCII character set is
1. If the character set cannot be defined by a
call to MKTBL, a value of zero is returned in this
variable.
tableaddress is a constant or variable that specifies the
starting address of a character table that has 128
(200 octal) consecutive words. Each character
table word contains the number of strokes (line
segments) for the character in the left half, and
the address of the table of strokes in the right
half. See Section F.5.1 for a description of
these tables.
F.5.1 Character Tables
The next sections describe how to define and organize a character set
table. The character set, called by the MKTBL subroutine, enables you
to create and use a character set other than the default character set
that is used to plot characters. (Usually the default character set
is ASCII.)
To create your own character set, you need to create a character table
and a character stroke table. These two tables are described in
Sections F.5.1.1 and F.5.1.2, respectively.
F.5.1.1 Creating a Character Table - A character table contains 128
entries (200 octal). Each entry in the character table, regardless of
whether the table is defined in the plotter subroutine library or by
you through a call to the MKTBL subroutine, indicates the character to
be plotted for the ASCII character that has that numerical value.
Figure F-1 is a diagram of an entry word in a character table.
F-6
FORTRAN-SUPPLIED PLOTTER SUBROUTINES
Figure F-1: Plotter Character Table Entry
As shown in Figure F-1, each entry in the character table contains the
number of strokes (line segments) required to plot the character in
its left half and an address reference in the right half of the word.
The address in the right half of the entry references an entry in the
character stroke table for the character set. The character stroke
table is described in the next section.
F.5.1.2 Creating a Stroke Table - Each character in the character
table has a corresponding character stroke table. The purpose of the
character stroke table is to define the number and type of strokes
(drawn line segments) it takes to produce a character in the character
table.
Figure F-2 is a diagram of an entry in a character stroke table.
Figure F-2: Character Stroke Table Entry
As shown in Figure F-2, each stroke is described in the character
stroke table by three 5-bit bytes. The possible values for these
three bytes are:
Byte Value and Meaning
1 0 pen is raised (off the paper)
1 pen is lowered (on the paper)
2 x-coordinate value at end of stroke
F-7
FORTRAN-SUPPLIED PLOTTER SUBROUTINES
3 y-coordinate value at end of stroke
When determining the height and width of each character to be plotted,
consider the following conventions:
1. Characters are drawn within a grid that is 15 units high by
eight units wide.
2. Characters are generally plotted six units above the base
line. Two units are generally left blank to the right of
each character; one unit is generally left blank on top of
each character. The spacing above, below, and on either side
of each character provides adequate spacing between
characters and between lines.
3. The plotter starts drawing each character at the lower left
corner of the character grid. If the grid is set up in the
conventional manner, the lower left corner is grid position
(0,6). Normal width characters end at the lower right corner
of the character grid after allowing spacing between
characters.
The last coordinate in each character grid is usually (8,6).
The character grid for the next character has as its origin
(0,0) at the ending coordinate in the previous grid (8,6).
4. Accents, circumflexes, underscores, and other characters that
are to be plotted in the same character grid as another
character should end at the same grid position as they began.
By doing this, for example, the ASCII character that
represents the accent character is plotted before the
character that is the letter to be accented.
F.5.1.3 Sample Character Stroke Table - In this sample, you want to
plot the Greek letter beta as a normal sized character. When plotted,
the letter is drawn on a 15 x 8 unit grid above the base line,
allowing for spacing between characters and between lines.
The strokes (line segments) for beta, including the invisible
segments, are then determined. The character will be plotted more
smoothly if as many of the line segments as possible are connected,
and if doubled segments are avoided. Note that stroke 9 (the return
stroke for the crossbar of the beta) and stroke 15 (moving the pen to
ending point (8,6) are not visible; the pen is raised.
F-8
FORTRAN-SUPPLIED PLOTTER SUBROUTINES
Figure F-3: Sample Character Stroke Table
If the address at the beginning of the table that includes the
character in Figure F-3 is called GREEK, then the FORTRAN call to set
up the table could be:
IGREEK=4
CALL MKTBL (IGREEK, GREEK)
The above call to the MKTBL subroutine defines the GREEK character
table to be the fourth character table. To use the GREEK table for
plotting, use the FORTRAN call:
CALL SETABL (IGREEK, IFLAG)
The entry in the character table for beta is:
RADIX ^ D10 ;VALUES IN DECIMAL
BETA: 15,,TBETA ;CHARACTER TABLE ENTRY FOR BETA
Note that the character table entry for beta contains the starting
address of the character stroke table (TBETA) in its right half.
The character stroke table for beta is:
F-9
FORTRAN-SUPPLIED PLOTTER SUBROUTINES
SEEN==1 ;IF 'SEEN' THEN THE STROKE MARKS THE PAPER
UNSEEN==0 ;IF 'UNSEEN' THEN THE STROKE IS INVISIBLE
RADIX ^D10 ;ALL VALUES ARE IN DECIMAL
TBETA: BYTE(5) SEEN,2,8,SEEN,2,13
BYTE(5) SEEN,3,14,SEEN,5,14
BYTE(5) SEEN,6,13,SEEN,6,12
BYTE(5) SEEN,5,11,SEEN,2,11
BYTE(5) UNSEEN,5,11,SEEN,6,10
BYTE(5) SEEN,6,9,SEEN,5,8
BYTE(5) SEEN,3,8,SEEN,2,9
BYTE(5) UNSEEN,8,6
F.5.1.4 FORTRAN- and User-Defined Character Sets - The standard ASCII
character set is always defined and is character set 1 for calls to
the SETABL subroutine, unless character set 1 is redefined by a user
call to the MKTBL subroutine. If SETABL is not called, the ASCII
character set is the default.
The Cyrillic (Russian) character set is available as character set 2,
and the Feanorian character set is available as character set 3
(unless character sets 2 or 3 has been redefined by a user call to the
MKTBL subroutine). In order to use these character sets, the user
program must contain an EXTERNAL statement for variable PLOTF
(Feanorian) or PLOTC (Cyrillic).
User-defined character sets should use character sets 4 through 10 to
avoid conflicts with the standard character sets.
NUMBER
Subroutine
F.6 NUMBER SUBROUTINE
The NUMBER subroutine causes floating-point numbers to be plotted as
text.
The form of the NUMBER subroutine is:
CALL NUMBER(x,y,size,fnum,theta,ndigit)
where:
F-10
FORTRAN-SUPPLIED PLOTTER SUBROUTINES
x,y are variables or constants that specify the x and y
coordinates of the point to be plotted. The specified
point is the lower left corner of the first character
to be plotted.
size is a variable or constant that specifies the size (in
inches) of the digits to be plotted. The specified
value should be a multiple of .08 inches (or
centimeters if plotter is metric) if a small value is
used.
fnum is a variable or constant that is the floating-point
number to be plotted.
theta is a variable or constant that specifies the direction
(in degrees) of the base line on which the characters
are plotted.
ndigit is a variable or constant that specifies the number of
digits to be plotted to the right of the decimal point.
If ndigit is negative, only the integer part of the
number is plotted; the resulting integer is rounded.
PLOT
Subroutine
F.7 PLOT SUBROUTINE
The PLOT subroutine moves the plotter pen to a new position. Raising
and lowering the pen is also specified in the PLOT subroutine.
NOTE
The plotter is not released after completion of the
specified movement.
The form of the PLOT subroutine is:
CALL PLOT(x,y,penup/down)
where:
x,y are the variables or constants that specify the x
and y coordinates for the point to which the pen
will be moved.
F-11
FORTRAN-SUPPLIED PLOTTER SUBROUTINES
penup/down is an integer constant or variable that specifies
whether the pen is on the paper or above the
paper. The possible values for this variable are:
3 = raise pen before movement
2 = lower pen before movement
1 = leave pen in current state (raised or lowered)
-1, -2, or -3 = same as corresponding positive
values except that on completion
of the indicated motion, the new
pen position is taken as a new
origin and the output buffer is
sent to the plotter. Using the
negative values is helpful if you
are plotting consecutive
characters in the same program.
SCALE
Subroutine
F.8 SCALE SUBROUTINE
The SCALE subroutine scales values for the AXIS subroutine.
The form of the SCALE subroutine is:
CALL SCALE(x,n,s,xmin,dx)
where:
x is an array name of a one-dimensional floating-point
array to be scaled for the AXIS subroutine.
n is an integer constant or variable that specifies the
length of the array in words (36-bit).
s is a constant or variable that specifies the length (in
inches) of the desired axis.
xmin is a constant or variable that specifies the smallest
element in array x. The value of xmin will be the
value of the scale at the beginning of the axis.
dx is a constant or variable that equals the change in
F-12
FORTRAN-SUPPLIED PLOTTER SUBROUTINES
scale for a 1-inch interval so that array x can be
plotted in inches.
SETABL
Subroutine
F.9 SETABL SUBROUTINE
The SETABL subroutine enables you to select the character set that is
used to plot characters.
The form of the SETABL subroutine is:
CALL SETABL (setnum,status)
where:
setnum is an integer constant or variable that equals the
number of the character set. The standard ASCII
character set is defined to be set 1 and is the
default. Character sets are defined by the MKTBL
subroutine (see Section F.5).
status is an integer variable whose value after the call to
the SETABL subroutine is either 0, if the character set
specified in setnum is valid, or -1, if the character
set specified by setnum is invalid.
NOTE
If you use a character set other than the
character sets defined by default in the
plotter subroutine library, you must call the
MKTBL subroutine before calling the SETABL
subroutine.
SYMBOL
Subroutine
F-13
FORTRAN-SUPPLIED PLOTTER SUBROUTINES
F.10 SYMBOL SUBROUTINE
The SYMBOL subroutine plots a specified string of characters (from
either the default character set or the character set specified by the
last successful call to the SETABL subroutine).
The form of the SYMBOL subroutine is:
CALL SYMBOL(x,y,size,asc,theta[,nasc])
where:
x is a constant or variable that equals the x coordinate
of the lower left corner of the first character to be
plotted.
y is a constant or variable that equals the y coordinate
of the lower left corner of the first character to be
plotted. The plotter pen is raised and moved to
position x,y before the string of characters is
plotted.
size is a constant or variable that specifies the height (in
inches) of the character to be plotted. The specified
value should be a multiple of .08 inches (or
centimeters if you have a metric plotter).
asc is the name of a character expression or numeric array
that contains the ASCII characters to be plotted.
theta is a constant or variable that specifies the direction
(in degrees) of the base line on which the characters
are to be plotted.
nasc is an integer constant or variable that is equal to the
number of characters in numeric array asc that are to
be plotted. This is ignored if a character expression
is specified for asc.
WHERE
Subroutine
F.11 WHERE SUBROUTINE
The WHERE subroutine reports on the current position of the plotter
F-14
FORTRAN-SUPPLIED PLOTTER SUBROUTINES
pen, in inches, relative to the origin.
NOTE
The plotter origin is set by a call to the AXIS
subroutine or a call to the PLOT subroutine that has a
negative value for the penup/down variable. Also, the
WHERE subroutine does not allow you to determine
whether the plotter pen is raised or lowered.
The form of the WHERE subroutine is:
CALL WHERE(x,y)
where:
x is a variable in which the subroutine returns the x
coordinate of the current print position.
y is a variable in which the subroutine returns the y
coordinate of the current pen position.
F-15