Fortran Language Reference Manual, Volume 2 - S-3693-50
Prev SectionChapter 1. Input and Output (I/O) ProcessingNext Section

1.8. File Positioning Statements

Execution of a data transfer statement usually changes the file position. In addition, there are three statements whose main purpose is to change the file position. Changing the position backwards by one record is called backspacing and is performed by the BACKSPACE statement. Changing the position to the beginning of the file is called rewinding and is performed by the REWIND statement. The ENDFILE statement writes an end-of-file record and positions the file after the end-of-file record. The following are file positioning statements:

BACKSPACE 9
BACKSPACE (UNIT = 10)
BACKSPACE (ERR = 99, UNIT = 8, IOSTAT = STATUS)
REWIND (ERR = 102, UNIT = 10)
ENDFILE (10, IOSTAT = IERR)
ENDFILE (11)

The file positioning statements have common components.

The following sections describe the BACKSPACE, REWIND, and ENDFILE statements in more detail.

1.8.1. BACKSPACE Statement

Executing a BACKSPACE statement causes the file to be positioned before the current record if there is a current record, or before the preceding record if there is no current record. If there is no current record and no preceding record, the file position is not changed. If the preceding record is an end-of-file record, the file becomes positioned before the end-of-file record.

If the last data transfer to a file connected for sequential access was an output data transfer statement, a BACKSPACE statement on that file writes an end-of-file record to the file. If there is a preceding record, the BACKSPACE statement causes the file to become positioned before the record that precedes the end-of-file record.

The BACKSPACE statement is defined as follows:

Table 1-14.

 

backspace_stmt

is

BACKSPACE external_file_unit

 

 

or

BACKSPACE (position_spec_list)

The BACKSPACE statement is used only to position external files.

If the file is already at its initial point, a BACKSPACE statement has no effect. If the file is connected, but does not exist, backspacing is prohibited. Backspacing over records written using list-directed or namelist formatting is prohibited.

BACKSPACE  ERROR_UNIT        ! ERROR_UNIT is an
                             !    integer variable
BACKSPACE (10, &             ! STAT is an integer
                             !    variable of
           IOSTAT = STAT)    !    default type

1.8.2. REWIND Statement

A REWIND statement positions the file at its initial point. Rewinding has no effect on the file position when the file is already positioned at its initial point. If a file does not exist, but it is connected, rewinding the file is permitted, but it has no effect.

If the last data transfer to a file was an output data transfer statement, a REWIND statement on that file writes an end-of-file record to the file.

The file must be connected for sequential access.

The REWIND statement is defined as follows:

Table 1-15.

 

rewind_stmt

is

REWIND external_file_unit

 

 

or

REWIND (position_spec_list)

The REWIND statement is used only to position external files.

REWIND  INPUT_UNIT      ! INPUT_UNIT is an integer
                        !   variable
REWIND (10, ERR = 200)  ! 200 is a label of branch
                        !   target in this
                        !   scoping unit

1.8.3. ENDFILE Statement

The ENDFILE writes an end-of-file record as the next record and positions the file after the end-of-file record written. Writing records past the end-of-file record is prohibited, except for certain file structures. For more information on file structures, see the Fortran Application Programmer's I/O Reference Manual.

Note: The Fortran standard does not address writing past an end-of-file record.

FORTRAN77 record blocking is the default form for sequential unformatted files. Text files are used for all other types of Fortran I/O.

Note: The Fortran standard does not address writing past an end-of-file record.

After executing an ENDFILE statement, it is necessary to execute a BACKSPACE or REWIND statement to position the file ahead of the end-of-file record before reading or writing the file. If the file is connected but does not exist, writing an end-of-file record creates the file.

The file must be connected for sequential access.

The ENDFILE statement is defined as follows:

Table 1-16.

 

endfile_stmt

is

ENDFILE external_file_unit

 

 

or

ENDFILE (position_spec_list)

The ENDFILE statement is used only to position external files.

                     ! OUTPUT_UNIT is an integer variable.
ENDFILE  OUTPUT_UNIT
ENDFILE (10, ERR = 200, IOSTAT = ST)
                     !   200 is a label of a branch
                     !   target in this scoping unit
                     !   ST is a default scalar integer
                     !   variable

A file can be connected for sequential and direct access, but not for both simultaneously. If a file is connected for sequential access and an ENDFILE statement is executed on the file, only those records written before the ENDFILE statement is executed are considered to have been written. Consequently, if the file is subsequently connected for direct access, only those records before the end-of-file record can be read.

1.8.4. Specifiers for File Position Statements

The position_spec_list is defined as follows (note that no specifier can be repeated in a position_spec_list):

Table 1-17.

 

position_spec

is

[UNIT = ] scalar_int_expr

 

 

or

IOSTAT = scalar_default_int_variable

 

 

or

ERR = label

The following sections describe the form and effect of the position specifiers that can appear in the file positioning statements.

1.8.4.1. UNIT= Specifier

The format of the UNIT= specifier is as follows:

[ UNIT= ] scalar_int_expr

The scalar_int_expr specifies an external unit. The value of the scalar_int_expr must be nonnegative.

A unit specifier is required. If the keyword UNIT is omitted, the scalar integer expression must be the first item in the position specifier list. A unit number identifies one and only one external unit in all program units in a Fortran program.

There must be a file connected to the unit, and the unit must be connected for sequential access.

1.8.4.2. IOSTAT= Specifier

The format of the IOSTAT= specifier is as follows:

IOSTAT= scalar_default_int_variable

The I/O library returns an integer value in scalar_default_int_variable. If scalar_default_int_variable > 0, an error condition occurred. If scalar_default_int_variable = 0, no error condition occurred. Note that the value cannot be negative.

The IOSTAT= specifier applies to the execution of the file positioning statement itself.

1.8.4.3. ERR= Specifier

The format of the ERR= specifier is as follows:

ERR= label

The program branches to the label in the ERR= specifier if there is an error in the execution of the particular file positioning statement itself. The label must be the label of a branch target statement in the same scoping unit as the file positioning statement.

If an error condition occurs, the position of the file becomes indeterminate.

If an IOSTAT= specifier is present and an error condition occurs, the IOSTAT variable specified becomes defined with a positive value.

Prev SectionTable of Contents | Title Page | IndexNext Section
Inquiring About FilesUp one levelRestrictions on I/O Specifiers, List Items, and Statements