Developer Guide and Reference

ID 767251
Date 10/31/2024
Public
Document Table of Contents

READ Statement

Statement: Transfers input data from external sequential, direct-access, or internal records.

Sequential

Formatted:

READ (eunit, format [, advance] [, asynchronous] [, blank] [, decimal] [, id] [, pad] [, pos] [, round] [, size] [, iostat] [, err] [, end] [, eor] [, iomsg]) [io-list]

READ form[, io-list]

Formatted - List-Directed:

READ (eunit, *[, asynchronous] [, blank] [, decimal] [, id] [, pad] [, pos] [, round] [, size] [, iostat] [, err] [, end] [, iomsg]) [io-list]

READ *[, io-list]

Formatted - Namelist:

READ (eunit, nml-group[, asynchronous] [, blank] [, decimal] [, id] [, pad] [, pos] [, round] [, size] [, iostat] [, err] [, end] [, iomsg])

READ nml

Unformatted:

READ (eunit [, asynchronous] [, id] [, pos] [, iostat] [, err][, end] [, iomsg]) [io-list]

Direct-Access

Formatted:

READ (eunit, format, rec [, asynchronous] [, blank] [, decimal] [, id] [, pad] [, pos] [, round] [, size] [, iostat] [, err] [, iomsg]) [io-list]

Unformatted:

READ (eunit, rec [, asynchronous] [, id] [, pos] [, iostat] [, err] [, iomsg]) [io-list]

Internal

READ (iunit, format [, nml-group] [, iostat] [, err] [, end] [, iomsg]) [io-list]

Internal Namelist

READ (iunit, nml-group [, iostat] [, err] [, end] [, iomsg]) [io-list]

eunit

Is an external unit specifier, optionally prefaced by UNIT=. UNIT= is required if eunit is not the first specifier in the list.

format

Is a format specifier. It is optionally prefaced by FMT= if format is the second specifier in the list and the first specifier indicates a logical or internal unit specifier without the optional keyword UNIT=.

For internal READs, an asterisk (*) indicates list-directed formatting. For direct-access READs, an asterisk is not permitted.

advance

Is an advance specifier (ADVANCE=c-expr). If the value of c-expr is 'YES', the statement uses advancing input; if the value is 'NO', the statement uses nonadvancing input. The default value is 'YES'.

asynchronous

Is an asynchronous specifier (ASYNCHRONOUS=i-expr). If the value of i-expr is 'YES', the statement uses asynchronous input; if the value is 'NO', the statement uses synchronous input. The default value is 'NO'.

blank

Is a blank control specifier (BLANK = blnk). If the value of blnk is 'NULL', all blanks are ignored. If the value is 'ZERO', all blanks are treated as zeros. The default value is 'NULL'.

decimal

Is a decimal mode specifier (DECIMAL=dmode) that evaluates to 'COMMA' or 'POINT'. The default value is 'POINT'.

id

Is an id specifier (ID=id-var). If ASYNCHRONOUS='YES' is specified and the operation completes successfully, the id specifier becomes defined with an implementation-dependent value that can be specified in a future WAIT or INQUIRE statement to identify the particular data transfer operation. If an error occurs, the id specifier variable becomes undefined.

pad

Is a blank padding specifier (PAD = pd). If the value of pad is 'YES', the record will be padded with blanks when necessary. If the value is 'NO', the record will not be padded with blanks. The default value is 'YES'.

pos

Is a pos specifier (POS=p) that indicates a file position in file storage units in a stream file (ACCESS='STREAM'). It can only be specified for a file opened for stream access. If omitted, the stream I/O occurs starting at the next file position after the current file position.

round

Is a rounding specifier (ROUND=rmode) that determines the I/O rounding mode for this READ statement. If omitted, the rounding mode is unchanged. Possible values are UP, DOWN, ZERO, NEAREST, COMPATIBLE or PROCESSOR_DEFINED.

size

Is a character count specifier (SIZE=i-var).

iostat

Is the name of a variable to contain the completion status of the I/O operation. Optionally prefaced by IOSTAT=.

err, end, eor

Are branch specifiers if an error (ERR=label), end-of-file (END=label), or end-of-record (EOR=label) condition occurs.

EOR can only be specified for nonadvancing READ statements.

iomsg

Is an I/O message specifier (IOMSG=msg-var).

io-list

Is an I/O list: the names of the variables, arrays, array elements, or character substrings from which or to which data will be transferred. Optionally an implied-DO list.

If an item in io-list is an expression that calls a function, that function must not execute an I/O statement or the EOF intrinsic function on the same external unit as eunit.

If I/O is to or from a formatted device, io-list cannot contain derived-type variables, but it can contain components of derived types. If I/O is to a binary or unformatted device, io-list can contain either derived type components or a derived-type variable.

form

Is the nonkeyword form of a format specifier (no FMT=).

*

Is the format specifier indicating list-directed formatting. (It can also be specified as FMT=*.)

nml-group

Is the namelist group specification for namelist I/O. Optionally prefaced by NML=. NML= is required if nml-group is not the second I/O specifier. For more information, see Namelist Specifier.

nml

Is the nonkeyword form of a namelist specifier (no NML=) indicating namelist I/O.

rec

Is the cell number of a record to be accessed directly. It must be prefaced by REC=.

iunit

Is an internal unit specifier, optionally prefaced by UNIT=. UNIT= is required if iunit is not the first specifier in the list. It must be a character variable. It must not be an array section with a vector subscript.

If you specify EOR= or SIZE=, you must also specify ASYNCHRONOUS='NO'.

If you specify BLANK=, DECIMAL=, PAD=, or ROUND=, you must also specify FMT= or NML=.

If you specify ID=, you must also specify ASYNCHRONOUS='YES'.

CAUTION:

The READ statement can disrupt the results of certain graphics text functions (such as SETTEXTWINDOW) that alter the location of the cursor. You can avoid the problem by getting keyboard input with the GETCHARQQ function and echoing the keystrokes to the screen using OUTTEXT. Alternatively, you can use SETTEXTPOSITION to control cursor location.

Example

 DIMENSION ia(10,20)
 ! Read in the bounds for the array.
 ! Then read in the array in nested implied-DO lists
 ! with input format of 8 columns of width 5 each.
 READ (6, 990) il, jl, ((ia(i,j), j = 1, jl), i =1, il)
 990 FORMAT (2I5, /, (8I5))

 ! Internal read gives a variable string-represented numbers
 CHARACTER*12 str
 str = '123456'
 READ (str,'(i6)') i

 ! List-directed read uses no specified format
 REAL x, y
 INTEGER i, j
 READ (*,*) x, y, i, j