Input, output, and format statements provide the means for transferring data to or from files. Data is transferred as records to or from files. A record is a sequence of data which may be values or characters and a file is a sequence of such records. A file may be internal, that is, held in memory, or external such as those held on disk. To access an external file a formal connection must be made between a unit, for example a disk file, and the required file. An external unit must be identified either by a positive integer expression, the value of which indicates a unit, or by an asterisk (*) which identifies the standard input or output device.
This chapter describes the types of input and output available and provides examples of input, output and format statements. There are four types of input/output you can use to transfer data to or from files: unformatted, formatted, list directed, and namelist.
You can access files using one of two methods, sequential access, or direct access (random access). The access method is determined by the specifiers supplied when the file is opened using the OPEN statement. Sequential access files are accessed one after the other, and are written in the same manner. Direct access files are accessed by specifying a record number for input, and by writing to the currently specified record on output.
Files may contain one of two types of records, fixed length records or variable length records. To specify the size of the fixed length records in a file, use the RECL specifier with the OPEN statement. RECL sets the record length in bytes .[*] RECL can only be used when access is direct.
A record in a variable length formatted file is terminated with \n (on DOS systems a \c\n terminates). A record in a variable length unformatted file is preceded and followed by a word indicating the length of the record.
Certain input and output units are predefined, depending on the value of compiler options. The pgf77 option -Mdefaultunit tells the compiler to treat "*" as a synonym for standard input for reading and standard output for writing. When the option is set to -Mnodefaultunit, then the compiler treats "*" as a synonym for unit 5 on input and unit 6 on output.
The OPEN statement establishes a connection to a file. OPEN allows you to do any of the following
OPEN (list)where list contains a unit specifier of the form:
[UNIT]= uwhere u, an integer, is the external unit specifier.
In addition list may contain one of each of the specifiers shown in Table 4-1.
If a file is connected for direct access using OPEN with ACCESS='DIRECT', the record length must be specified using RECL=, and optionally one of each of the other specifiers may be used.
Any file opened for direct access must be via fixed length records.
In the following example a new file, book.dat, is created and connected to unit 12 for direct formatted input/output with a record length of 98 characters. Numeric values will have blanks ignored and the variable E1 will be assigned some positive value if an error condition exists when the OPEN statement is executed; execution will then continue with the statement labeled 20. If no error condition pertains, E1 is assigned the value 0 and execution continues with the statement following the OPEN statement.
OPEN(12,IOSTAT=E1,ERR=20,FILE='book.dat',BLANK='NULL', +ACCESS='DIRECT',RECL=98,FORM='FORMATTED',STATUS='NEW')
| Specifier
|
Description
|
| IOSTAT=
ios
|
Input/output
status specifier where ios is an integer scalar memory reference. If
this is included in list, ios becomes defined with 0 if no error
exists or a positive integer when there is an error condition.
|
| ERR=
errs
|
An
error specifier which takes the form of a statement label of an executable
statement in the same program. If an error condition occurs, execution
continues with the statement specified by errs..
|
| FILE=
fin
|
Where
fin is a character string defining the file name to be connected to the
specified unit.
|
| STATUS=
sta
|
The
file status where sta is a character expression: it can be NEW, OLD,
SCRATCH or UNKNOWN. When OLD or NEW is specified a file specifier must be
given. SCRATCH must not be used with a named file. The default is UNKNOWN.
|
| ACCESS=
acc
|
Where
acc is a character string specifying the access method for file connection
as DIRECT (random access) or SEQUENTIAL. The default is SEQUENTIAL.
|
| FORM=
fm
|
Where
fm is a character string specifying whether the file is being connected for
FORMATTED or UNFORMATTED output respectively. The default is FORMATTED.
|
| RECL=
rl
|
Where
rl is an integer which defines the record length in a file connected for
direct access and is the number of characters when formatted input/output is
specified. This specifier must only be given when a file is connected for
direct access.
|
| BLANK=
blnk
|
Where
blnk is a character string which takes the value NULL or ZERO: NULL causes
all blank characters in numeric formatted input fields to be ignored with the
exception of an all blank field which has a value of zero. ZERO causes all
blanks other than leading blanks to be treated as zeros. The default is NULL.
This specifier must only be used when a file is connected for formatted
input/output.
|
Close a unit by specifying the CLOSE statement from within any module. If the unit specified does not exist or has no file connected to it, the CLOSE statement has no effect.
Provided the file is still in existence it may be reconnected to the same or a different unit after the execution of a CLOSE statement. An implicit CLOSE is executed when a program stops.
The CLOSE statement terminates the connection of the specified file to a unit.
CLOSE ([UNIT=] u [,IOSTAT=ios] [,ERR= errs ]Close takes the status values IOSTAT, ERR, and STATUS, similar to those described in Table 4-1 OPEN Specifiers. In addition, CLOSE allows the DISPOSE or DISP specifier which can take a status value sta which is a character string, where case is insignificant, specifying the file status (the same keywords are used for the DISP and DISPOSE status). Status can be can be KEEP or DELETE. KEEP cannot be specified for a file whose dispose status is SCRATCH. When KEEP is specified (for a file that exists) the file continues to exist after the CLOSE statement, conversely DELETE deletes the file after the CLOSE statement. The default value is KEEP unless the file status is SCRATCH.
[,STATUS= sta] [,DISPOSE= sta] [,DISP= sta])
A unit may be the subject of a CLOSE statement from within any module. If the unit specified does not exist or has no file connected to it the use of the CLOSE statement has no effect. Provided the file is still in existence it may be reconnected to the same or a different unit after the execution of a CLOSE statement. Note that an implicit CLOSE is executed when a program stops.
In the following example the file on UNIT 6 is closed and deleted.
CLOSE(UNIT=6,STATUS='DELETE')
Unformatted data transfer allows data to be transferred between the current record and the items specified in an input/output list. Use OPEN to open a file for unformatted output:
OPEN (2, FILE='new.dat', FORM='UNFORMATTED')The unit specified must be an external unit.
After data is transferred, the file is positioned after the last record read or written, if there is no error condition or end-of-file condition set Unformatted data transfer cannot be carried out if the file is connected for formatted input/output.
The following example shows an unformatted input statement:
READ (2, ERR=50) A, BOn output to a file connected for direct access, the output list must not specify more values than can fit into a record. If the values specified do not fill the record the rest of the record is undefined.
On input the following conditions must pertain; the file must be positioned so that the record read is either:
During formatted data transfer, data is edited to conform to a format specification, and the edited data is transferred between the items specified in the input or output statement's iolist and the file; the current record is read or written and, possibly, additional records. On input the file must be positioned so that the record read is either a formatted record or an endfile record. Formatted data transfer is prohibited if the file is connected for unformatted input/output.
For variable length record formatted input, each newline character is interpreted as a record separator. On output, the I/O system writes a newline at the end of each record. If a program writes a newline itself, the single record containing the newline will appear as two records when read or backspaced over. The maximum allowed length of a record in a variable length record formatted file is 2000 characters.[*]
An implied DO list takes the form
(iolist,do-var=var1,var2,var3)where the items in iolist are either items permissible in an input/output list or another implied DO list,. The value do-var is an INTEGER, REAL or DOUBLE PRECISION variable and var1, var2 and var3 are arithmetic expressions of type INTEGER, REAL or DOUBLE PRECISION. Generally do-var, var1, var2 and var3 are of type INTEGER. Should iolist occur in an input statement, the do-var cannot be used as an item in iolist. If var3 and the preceding comma are omitted the increment takes the value 1. The list items are specified once for each iteration of the DO loop with the DO-variable being substituted as appropriate.
REAL C(6),D(6) DATA OXO,(C(I),I=7,9),TEMP,(D(J),J=1,2)/4*0.0,3*10.0/In the above example OXO, C(7), C(8) and C(9) are set to 0.0 with TEMP, D(1) and D(2) being set to 10.0. In the next example:
READ *,A,B,(R(I),I=1,4),Shas the same effect as
READ *,A,B,R(1),R(2),R(3),R(4),S
Format requirements may be given either in an explicit FORMAT statement or alternatively, as fields within an input/output statement (as values in character variables, arrays or other character expressions within the input/output statement).
When a format identifier in a formatted input/output statement is a character array name or other character expression, the leftmost characters must be defined with character data that constitute a format specification when the statement is executed. A character format specification is enclosed in parentheses. Blanks may precede the left parenthesis. Character data may follow the right-hand parenthesis and has no effect on the format specification. When a character array name is used as a format identifier, the length of the format specification can exceed the length of the first element of the array; a character array format specification is considered to be an ordered concatenation of all the array elements. When a character array element is used as a format identifier the length must not exceed that of the element used.
The FORMAT statement has the form:
FORMAT (list-of-format-requirements)The list of format requirements can be any of the following, separated by commas:
Each repeatable edit code has a corresponding item in the iolist; however when a list item is of type complex two edit codes of F, E, D or G are required. The edit codes P, X, T, TL, TR, S, SP, SS, H, BN, BZ, /, : and apostrophe act directly on the record and have no corresponding item in the input/output list.
The file is positioned after the last character read or written when the edit codes I, F, E, D, G, L, A, H or apostrophe are processed. If the specified unit is a printer then the first character of the record is used to control the vertical spacing as shown in Table 4-2:
| Character
|
Vertical
Spacing
|
| Blank
|
One
line
|
| 0
|
Two
lines
|
| 1
|
To
first line on next page
|
| +
|
No
advance
|
The A specifier transfers characters. The A can optionally be followed by a field width w. When w is not specified, the width is determined by the size of the data item.
On output, if l is the length of the character item and w is the field width, then the following rules apply:
If w > l w - l blanks before the character
If w < l leftmost w characters.
On input, if l is the length of the character io item and w is the field width, then the following rules apply:
If w > l rightmost l characters from the input filed.
If w < l leftmost w characters from the input filed and followed by l - w blanks.
You can also use the A format specifier to process data types other than CHARACTER. For types other than CHARACTER, the number of characters supplied for input/output will equal the size in bytes of the data allocated to the data type. For example, an INTEGER*4 value is represented with 4 characters and a LOGICAL*2 is represented with 2 characters.
The following shows a simple example that reads two CHARACTER arrays from the file data.src:
CHARACTER STR1*8, STR2*12
OPEN(2, FILE='data.src')
READ(2, 10) STR1, STR2
10 FORMAT ( A8, A12 )
The D specifier transfers real values for double precision data with a representation for an exponent. The form of the D specifier is:
Dw.dwhere w is the field width and d the number of digits in the fractional part.
For input, the same conditions apply as for the F specifier which is described later.
For output the scale factor k controls the decimal normalization. The scale factor k is the current scale factor specified by the most recent P format control; if one hasn't been specified, the default is zero (0). If -d < k <= 0, the output file contains leading zeros and d-|k| significant digits after the decimal point. If 0 < k < d+2 there are exactly |k| significant digits to the left of the decimal point and d-k+1 significant digits to the right of the decimal point. Other values of k are not allowed.
For example:
DOUBLE PRECISION VAL1produces the following:
VAL1 = 141.8835
WRITE( *, 20) VAL1
20 FORMAT ( D10.4 )
0.1418D+03
The E specifier transfers real values for single precision data with an exponent. The E format specifier has two basic forms:
Ew.dw is the field width, d the number of digits in the fractional part and e the number of digits to be printed in the exponent part.
Ew.dEe
For input the same conditions apply as for F editing. For output the scale factor controls the decimal normalization as in D above.
The F specifier transfers real values The form of the F specifier is:
Fw.dw is the field width and d is the number of digits in the fractional part.
On input if the field does not contain a decimal digit or an exponent, righthand d digits, with leading zeros, are interpreted as being the fractional part.
On output a leading zero is only produced to the left of the decimal point if the value is less than one.
The G format specifier has two basic forms:
Gw.d Gw.dEeThe specifier transfers real values; it acts like the F format control on input and depending on the value's magnitude, like E or F on output. The magnitude of the data determines the output format. For details on the actual format used, based on the magnitude, refer to Section 13.5.9.2.3 "G Editing", in the ANSI FORTRAN Standard.
The I format specifier transfers integer values. The I format specifier has two basic forms:
Iw Iw.mwhere w is the field width and m is the minimum filed width on output, including leading zeros. If present, m must not exceed width w.
On input, the external field to be input must contain (unsigned) decimal characters only. An all blank field is treated as a value of zero. If the value of the external field exceeds the range of the corresponding list element, an error occurs.
On output, the I field descriptor transfers the decimal values of the corresponding I/O list element, right-justified, to an external field that is w characters long. If the value to be transmitted does not fill the field, leading spaces are inserted; if the value is too large for the field, the entire field is filled with asterisks. If m is present, the external field consists of at least m digits, and is zero-filled on the left if necessary. Note that if m is zero, and the internal representation is zero, the external field is blank-filled.
LwThe L format control transfers logical data of field width w. On input the list item will become defined with a logical value; the field consists of optional blanks, followed by an optional decimal point followed by T or F. Also, the values .TRUE. or .FALSE. may appear in the input field
The output field consists of w-1 blanks followed by T or F as appropriate.
Quote editing prints a character constant. The format specifier writes the characters enclosed between the quotes and cannot be used on input. The field width is that of the characters contained within quotes (you can also use apostrophes to enclose the character constant).
To write an apostrophe (or quote) use two consecutive apostrophes (or quotes).
For example:
WRITE ( *, 101) 101 FORMAT ( 'Print an apostrophe '' and end.')Produces:
Print an apostrophe ' and end.Similarly, you can use quotes, for example:
WRITE ( *, 102) 102 FORMAT ( "Print a line with a "" and end.")Produces:
Print a line with a " and end.
The BN and BZ formats control blank spacing. BN causes all embedded blanks except leading blanks in numeric input to be ignored, which has the effect of right justifying the remainder of the field. Note that a field of all blanks has the value zero. Only input statements and I, F, E, D and G editing are affected.
BZ causes all blanks except leading blanks in numeric input to be replaced by zeros. Only input statements and I, F, E, D and G editing are affected.
The H format control writes the n characters following the H in the format specification and cannot be used on input.
The basic form of this format specification is:
nHc1cn...where n is the number of characters to print and c1 through cn are the characters to print.
The O and Z field descriptors transfer octal or hexadecimal values and can be used with any data type. They have the form:
Ow[.m] and Zw[.m]where w specifies the field width and m indicates minimum field width on output.
On input, the external field to be input must contain (unsigned) octal or hexadecimal characters only. An all blank field is treated as a value of zero. If the value of the external field exceeds the range of the corresponding list element, an error occurs.
On output, the O and Z field descriptors transfer the octal and hexadecimal values, respectively, of the corresponding I/O list element, right-justified, to an external field that is w characters long. If the value to be transmitted does not fill the field, leading spaces are inserted; if the value is too large for the field, the entire field is filled with asterisks. If m is present, the external field consists of at least m digits, and is zero-filled on the left if necessary. Note that if m is zero, and the internal representation is zero, the external field is blank-filled.
kPThe P format specifier is the scale factor format which is applied as follows.
DIMENSION A(6)produces:
DO 10 I = 1,6
10 A(I) = 25.
TYPE 100,A
100 FORMAT(' ',F8.2,2PF8.2,F8.2)
25.00 2500.00 2500.00 2500.00 2500.00 2500.00Note that the effect of the scale factor continues until another scale factor is used.
The Q edit descriptor calculates the number of characters remaining in the input record and stores that value in the next I/O list item. On output, the Q descriptor skips the next I/O item.
The S format specifier restores the default processing for writing a plus; the default is SS processing.
SP forces the processor to write a plus in any position where an optional plus is found in numeric output fields, this only affects output statements.
SS stops the processor from writing a plus in any position where an optional plus is found in numeric output fields, this only affects output statements.
The T specifier controls which portion of a record a iolist value is read from or written to a file. The general form is as follows:
Tnthis specifies that the nth value is to be written to or from a record.
The TL form specifies the relative position to the left of the data to be read or written.
TLnThis specifies that the nth character to the left of the current position is to be written to or from the record. If the current position is less than or equal to n the transmission will begin at position one of the record.
The TR form specifies the relative position to the right of the data to be read or written.
TRnSpecifies that the nth character to the right of the current position is to be written to or from the record.
The X control specifies a number of characters to skip forward.
nXSpecifies that the next character to be written to or from is n characters forward from the current position.
The following example uses the X format specifier.
NPAGE = 19
WRITE ( 6, 90) NPAGE
90 FORMAT('1PAGE NUMBER ,I2, 16X, 'SALES REPORT, Cont.')
produces:
PAGE NUMBER 19 SALES REPORT, Cont.The following example shows use of the T format specifier.
PRINT 25produces:
25 FORMAT (T41,'COLUMN 2',T21,'COLUMN 1')
COLUMN 1 COLUMN 2
The slash (/) control indicates the end of data transfer on the current record.
On input from a file connected for sequential access the rest of the current record is skipped and the file positioned at the start of the next record.
On output a new record is created which becomes the last and current record. For an internal file, connected for direct access the record is filled with blank characters. If a direct access file, the record number is increased by one and the file is positioned at the start of the record.
The(: ) control terminates format control if there are no more items in the input/output list. It has no effect if there are any items left in the list.
The $ field descriptor allows the programmer to control carriage control conventions on output. It is ignored on input. For example, on terminal output, it can be used for prompting.
The form of the $ field descriptor is:
$
Variable format expressions are supported. They provide a means for substituting run-time expressions for the field width, other parameters for the field and edit descriptors in a FORMAT statement (except for the H field descriptor and repeat counts).
Variable format expressions are enclosed in "<" and ">" and are evaluated each time they are encountered in the scan of a format. If the value of a variable used in the expression changes during the execution of the I/O statement, the new value is used the next time the format item containing the expression is processed.
List-directed formatting is an abbreviated form of input/output that does not require the use of a format specification. The type of the data is used to determine how a value is read/written. On output it will not always be accurate enough for certain ranges of values. The characters in a list-directed record constitute a sequence of values which cannot contain embedded blanks except those permitted within a character string. To use list-directed input/output formatting, specify a * for the list of format requirements. For example, the following example uses list-directed output:
READ( 1, * ) VAL1, VAL2
The form of the value being input must be acceptable for the type of item in the iolist. Blanks must not be used as zeros nor be embedded in constants except in a character constant or within a type complex form contained in parentheses.
| Input
List Type
|
Form
|
| Integer
|
A
numeric input field.
|
| Real
|
A
numeric input field suitable for F editing with no fractional part unless a
decimal point is used.
|
| Double
precision
|
Same
as for real.
|
| Complex
|
An
ordered pair of numbers contained within parentheses as shown (real part,
imaginary part).
|
| Logical
|
A
logical field without any slashes or commas.
|
| Character
|
A
non-empty character string within apostrophes. A character constant can be
continued on as many records as required. Blanks, slashes and commas can be
used.
|
A null value has no effect on the definition status of the corresponding iolist item. A null value cannot represent just one part of a complex constant but may represent the entire complex constant. A slash encountered as a value separator stops the execution of that input statement after the assignment of the previous value. If there are further items in the list they are treated as if they are null values.
Commas may be used to separate the input values. If there are consecutive commas, or the if the first non-blank character of a record is a comma, the input value is a null value. Input values may also be repeated.
In the following example of list-directed formatting, assume that
A= -1.5and all other variables are undefined. When the statement below reads in the list from the input file:
K= 125
READ * I, J, X, Y, Z, A, C, Kwhere the file contains the following record:
10,-14,25.2,-76,313,,29/The variables are assigned the following values by the list-directed input/output mechanism:
I=10 J=-14 X=25.2 Y=-76.0 Z=313.0 A=-1.5 C=29 K=125.Note that the value for A does not change because the input record is null (consecutive commas). No input is read for K, so it assumes null and K retains it previous value ( the / terminates the input).
List directed input/output is an abbreviated form of formatted input/output that does not require the use of a format specification. Depending on the type of the data item or data items in the iolist, data is transferred to or from the file, using a default, and not necessarily accurate format specification. The data type of each item appearing in the iolist is formatted according to the rules in Table 4-4.
| Data
Type
|
Default
Formatting
|
BYTE |
I5 |
INTEGER*2 |
I7 |
INTEGER*4 |
I12 |
INTEGER*8 |
I24 |
LOGICAL*1 |
I5 (L2) |
LOGICAL*2 |
L2 |
LOGICAL*4 |
L2 |
LOGICAL*8 |
L2 |
REAL*4 |
G15.7e2 |
REAL*8 |
G25.16e3 |
COMPLEX*8 |
(G15.7e2, G15.7e2) |
COMPLEX*16 |
(G25.16e3, G25.16e3) |
CHAR *n |
An |
The length of a record is less than 80 characters; if the output of an item would cause the length to exceed 80 characters, a new record is created.
Notes
Use of the comma in an external field eliminates the need to "count spaces" to have data match format edit descriptors. The use of a comma to terminate an input field and thus avoid padding the field is fully supported.
The NAMELIST statement allows for the definition of namelist groups. A namelist group allows for a special type of formatted input/output, where data is transferred between a named group of data items defined in a NAMELIST statement and one or more records in a file.
The general form of a namelist statement is:
NAMELIST /group-name/ namelist [[,] /group-name/ namelist ]...
Namelist input is accomplished using a READ statement by specifying a namelist group as the input item. The following statement shows the format:
READ ([unit=] u, [NML=] namelist-group [,control-information])
One
or more records are processed which define the input for items in the namelist
group.The records are logically viewed as follows:
$group-name item=value [,item=value].... $ [END]The following rules describe these input records:
Namelist output is accomplished using a READ statement by specifying a namelist group as the output item. The following statement shows the format:
@ WRITE ([unit=] u, [NML=] namelist-group [,control-information])The records output are logically viewed as follows:
$group-name item = value $ [END]The following rules describe these output records:
[*] The units depend on the value of the FORTRANOPT environment variable. If the value is vaxio, then the record length is in units of 32-bit words. If FORTRANOPT is not defined, or its value is something other than vaxio, then the record length is always in units of bytes.
[*] For programs run in a DOS environment, newline is considered to be an ASCII CR-LF (carriage return - line feed) pair. For a non-DOS environment, newline is considered to be just LF.