Language Reference
Purpose
The READ statement is the data transfer input statement.
Format
>>-READ--+-name----------------------------------------+-------><
+-format--+---------------------+-------------+
| '-,--input_item_list--' |
'-(--io_control_list--)--+-----------------+--'
'-input_item_list-'
|
- format
- is a format identifier, described below under
FMT=format. In addition, it cannot be a Hollerith
constant.
- name
- is a namelist group name
- input_item
- is an input list item. An input list specifies the data to be
transferred. An input list item can be:
- A variable name, but not for an assumed-size array. An array is
treated as if all of its elements were specified in the order they are
arranged in storage.
A pointer must be associated with a definable target, and an allocatable
array must be allocated. A derived-type object cannot have any ultimate
component that is outside the scoping unit of this statement. The
evaluation of input_item cannot result in a derived-type object that
contains a pointer. The structure components of a structure in a
formatted statement are treated as if they appear in the order of the
derived-type definition; in an unformatted statement, the structure components
are treated as a single value in their internal representation (including
padding).
- An implied-DO list, as described under Implied-DO List.
- io_control
- is a list that must contain one unit specifier (UNIT=) and can
also contain one of each of the other valid specifiers described below.
- [UNIT=] u
- is a unit specifier that specifies the unit to be used in the input
operation. u is an external unit identifier or internal file
identifier.
An external unit identifier refers to an external file. It is one of
the following:
- An integer expression whose value is in the range 0 through
2,147,483,647.
- An asterisk, which identifies external unit 5 and is preconnected to
standard input.
An internal file identifier refers to an internal file. It is the
name of a character variable that cannot be an array section with a vector
subscript.
If the optional characters UNIT= are omitted, u must be
the first item in io_control_list. If the optional characters
UNIT= are specified, either the optional characters FMT= or
the optional characters NML= must also be present.
- [FMT=] format
- is a format specifier that specifies the format to be used in the input
operation. format is a format identifier that can be:
If the optional characters FMT= are omitted, format must
be the second item in io_control_list and the first item must be the
unit specifier with the optional characters UNIT= omitted.
Both NML= and FMT= cannot be specified in the same input
statement.
- REC= integer_expr
- is a record specifier that specifies the number of the record to be read
in a file connected for direct access. The REC= specifier is
only permitted for direct input. integer_expr is an integer
expression whose value is positive. A record specifier is not valid if
list-directed or namelist formatting is used and if the unit specifier
specifies an internal file. The END= specifier can appear concurrently. The record specifier represents the relative position of a record
within a file. The relative position number of the first record is
1.
- ID= integer_variable
- indicates that the data transfer is to be done asynchronously. The
integer_variable is a scalar of type INTEGER(4) or default
integer. If no error is encountered, the integer_variable is
defined with a value after executing the asynchronous data transfer
statement. This value must be used in the matching WAIT
statement.
Asynchronous data transfer must either be direct unformatted or sequential
unformatted. Asynchronous I/O to internal files is prohibited.
Asynchronous I/O to raw character devices (for example, to tapes or raw
logical volumes) is prohibited. The integer_variable must not
be associated with any entity in the data transfer I/O list, or with a
do_variable of an io_implied_do in the data transfer I/O
list. If the integer_variable is an array element reference,
its subscript values must not be affected by the data transfer, the
io_implied_do processing, or the definition or evaluation of any
other specifier in the io_control_spec.
- IOSTAT= ios
- is an input/output status specifier that specifies the status of the
input/output operation. ios is a variable of type
INTEGER(4) or default integer. Coding the IOSTAT=
specifier suppresses error messages. When the statement finishes
execution, ios is defined with:
- A zero value if no error condition, end-of-file condition, or
end-of-record condition occurs.
- A positive value if an error occurs.
- A negative value if an end-of-file condition is encountered and no error
occurs.
- A negative value that is different from the end-of-file value if an
end-of-record condition occurs and no error condition or end-of-file condition
occurs.
- ERR= stmt_label
- is an error specifier that specifies the statement label of an executable
statement to which control is to transfer in the case of an error.
Coding the ERR= specifier suppresses error messages.
- END= stmt_label
- is an end-of-file specifier that specifies a statement label at which the
program is to continue if an endfile record is encountered and no error
occurs. An external file is positioned after the endfile record; the
IOSTAT= specifier, if present, is assigned a negative value; and the
NUM= specifier, if present, is assigned an integer value. If
an error occurs and the statement contains the SIZE= specifier, the
specified variable becomes defined with an integer value. Coding the
END= specifier suppresses the error message for end-of-file.
This specifier can be specified for a unit connected for either sequential or
direct access.
- NUM= integer_variable
- is a number specifier that specifies the number of bytes of data
transmitted between the I/O list and the file.
integer_variable is a scalar variable name of type
INTEGER(4), type INTEGER(8) in 64-bit, or type default
integer. The NUM= specifier is only permitted for unformatted
output. Coding the NUM parameter suppresses the indication of
an error that would occur if the number of bytes represented by the output
list is greater than the number of bytes that can be written into the
record. In this case, integer_variable is set to a value that
is the maximum length record that can be written. Data from remaining
output list items is not written into subsequent records.
- [NML=] name
- is a namelist specifier that specifies the name of a
namelist list that you have previously defined. If the optional
characters NML=are not specified, the namelist name must appear as
the second parameter in the list and the first item must be the unit specifier
with UNIT= omitted. If both NML=and UNIT=are
specified, all the parameters can appear in any order. The
NML= specifier is an alternative to FMT=; both NML=
and FMT= cannot be specified in the same input statement.
- ADVANCE=char_expr
- is an advance specifier that determines whether nonadvancing input occurs
for this statement. char_expr is a scalar character expression
that must evaluate to YES or NO. If NO is
specified, nonadvancing input occurs. If YES is specified,
advancing, formatted sequential input occurs. The default value is
YES. ADVANCE= can be specified only in a formatted
sequential READ statement with an explicit format specification that
does not specify an internal file unit specifier.
- SIZE=count
- is a character count specifier that determines how many characters are
transferred by data edit descriptors during execution of the current input
statement. count is a scalar variable of type INTEGER(4),
type INTEGER(8) in 64-bit, or type default integer. Blanks that are inserted as padding are not included in the
count.
- EOR=stmt_label
- is an end-of-record specifier. If the specifier is present, an
end-of-record condition occurs, and no error condition occurs during execution
of the statement. If PAD= exists, the following also occur:
- If the PAD= specifier has the value YES, the record is
padded with blanks to satisfy the input list item and the corresponding data
edit descriptor that requires more characters than the record contains.
- Execution of the READ statement terminates.
- The file specified in the READ statement is positioned after the
current record.
- If the IOSTAT= specifier is present, the specified variable
becomes defined with a negative value different from an end-of-file
value.
- If the SIZE= specifier is present, the specified variable becomes
defined with an integer value.
- Execution continues with the statement containing the statement label
specified by the EOR= specifier.
- End-of-record messages are suppressed.
>>-(--do_object_list-- , --------------------------------------->
>-----do_variable = arith_expr1, arith_expr2-------------------->
>----+---+--+-------------+--)---------------------------------><
'-,-' '-arith_expr3-'
|
- do_object
- is an output list item
- do_variable
- is a named scalar variable of type integer or real
- arith_expr1, arith_expr2, and
arith_expr3
- are scalar numeric expressions
The range of an implied-DO list is the list
do_object_list. The iteration count and the values of the
DO variable are established from arith_expr1,
arith_expr2, and arith_expr3, the same as for a DO
statement. When the implied-DO list is executed, the items in
the do_object_list are specified once for each iteration of the
implied-DO list, with the appropriate substitution of values for any
occurrence of the DO variable.
The DO variable or an associated data item must not appear as an
input list item in the do_object_list, but can be read in the same
READ statement outside of the implied-DO list.
Rules
Any statement label specified by the ERR=, EOR= and
END= specifiers must refer to a branch target statement that appears
in the same scoping unit as the READ statement.
If either the EOR= specifier or the SIZE= specifier is
present, the ADVANCE= specifier must also be present and must have
the value NO.
If a NUM= specifier is present, neither a format specifier nor a
namelist specifier can be present.
Variables specified for the IOSTAT=, SIZE= and
NUM= specifiers must not be associated with any input list item,
namelist list item, or the DO variable of an implied-DO
list. If such a specifier variable is an array element, its subscript
values must not be affected by the data transfer, any implied-DO
processing, or the definition or evaluation of any other specifier.
A READ statement without io_control_list specified
specifies the same unit as a READ statement with
io_control_list specified in which the external unit identifier is an
asterisk.
If the ERR= and IOSTAT= specifiers are set and an error
is encountered during a synchronous data transfer, transfer is made to the
statement specified by the ERR= specifier and a positive integer
value is assigned to ios.
If the ERR= or IOSTAT= specifiers are set and an error is
encountered during an asynchronous data transfer, execution of the matching
WAIT statement is not required.
If the END= or IOSTAT= specifiers are set and an
end-of-file condition is encountered during an asynchronous data transfer,
execution of the matching WAIT statement is not required.
If a conversion error is encountered and the CNVERR run-time
option is set to NO, ERR= is not branched to, although
IOSTAT= may be set.
If IOSTAT= and ERR= are not specified,
- The program stops if a severe error is encountered.
- The program continues to the next statement if a recoverable error is
encountered and the ERR_RECOVERY run-time option is set to
YES. If the option is set to NO, the program
stops.
- The program continues to the next statement when a conversion error is
encountered if the ERR_RECOVERY run-time option is set to
YES. If the CNVERR run-time option is set to
YES, conversion errors are treated as recoverable errors; if
CNVERR=NO, they are treated as conversion errors.
Examples
INTEGER A(100)
CHARACTER*4 B
READ *, A(LBOUND(A,1):UBOUND(A,1))
READ (7,FMT='(A3)',ADVANCE='NO',EOR=100) B
·
100 PRINT *, 'end of record reached'
END
Related Information
[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]
© Copyright IBM Corporation 1990, 1998