J3/02-181r3

Date:     May 15, 2002
To:       J3
From:     Dick Hendrickson as amended by Dan Nagle
Subject:  FLUSH for files

Dick Wrote:
A frequent topic on Comp.Lang.Fortran is "How do I flush a file
in Fortran?"  The answer is "you can't."
End Dick Wrote

As an alternative to Dick's original FLUSH= specifier proposal,
I propose a FLUSH statement, modeled after the file positioning statements.
This has the advantage of making (largely, at least) localized edits.

The statement is:

FLUSH unit
-or-
FLUSH( UNIT=  , IOSTAT=  , IOMSG=  , ERR=  )

This has the further advantage that a simple source file editing script
changing "call flush( unit)" to "flush( unit)" makes a standard conforming
program, easing efforts of programmers.  Implementation may be done
by translating the flush statement into the previously widely supported
flush procedure.

The IOSTAT variable will be given a positive value
if an error occurs, a zero value if the operation is successful,
and a negative value to indicate processor-defined conditions
such as when flush doesn't apply to the unit.

Flush should be given as vacuous a definition as possible,
since we don't discuss the means of storing files.  I propose
to say nothing more than that a flush makes data transferred
to the file available for further processing, and adding a NOTE
stating, roughly, "you know what I mean".

EDITS:

11:19+ Add
or <flush-stmt>

175:10 Change "REWIND, WAIT" to
"REWIND, FLUSH, WAIT"

177:7 Change "REWIND," to "REWIND, FLUSH,"

Insert new section after 9.7 (Bottom of page 210):

9.7+ Flush Statement

The form of the FLUSH statement is:

Rxxx	<flush-stmt>	is	FLUSH <file-unit-number>
				or	FLUSH ( <flush-spec-list> )

Rxxx	<flush-spec>		is	[UNIT =] <file-unit-number>
				or	IOSTAT = <scalar-int-variable>
				or	IOMSG = <iomsg-variable>
				or	ERR = <label>

Cxxx	No specifier shall appear more than once in a given <flush-spec-list>.

Cxxx	A <file-unit-number> shall be specified; if the
	optional characters UNIT= are omitted
	from the unit specifier, the <file-unit-number> shall
	be the first item in the list.

Cxxx	The <label> in the ERR= specifier shall be the statement label
	of a branch target statement that appears in the same scoping unit
	as the flush statement.

The IOSTAT=, IOMSG= and ERR= specifiers are as described in section 9.9.
The IOSTAT= variable shall be set to a processor-specified positive value
if an error occurs, to zero if the processor-dependent flush operation
was successful and to a processor-specified negative value to indicate
a processor-dependent condition such as the flush operation had no effect
or that the flush operation is not appropriate for the unit specified.

Note xx:
The negative values for the IOSTAT=
variable allow a flush operation on a unit where it is
ineffective or inappropriate to be treated as a "harmless error"
that does not require an error to occur.
End Note

Execution of a FLUSH statement causes data written to an external file
to be available to other processes,
or causes data placed in an external file by means beyond the program
to be available to a read statement.
The action is processor dependent.

Execution of a FLUSH statement for a file that is connected
but does not exist is permitted and has no effect.  A FLUSH statement
has no effect on file position.

Note xx:
Since this standard does not specify the mechanism of file storage,
the exact meaning of the flush operation is left vague.  The intention
is that the flush operation should make all data written to a file
available to other processes or devices, or make data recently added to a file
by other processes or devices available to the program via a subsequent read
operation.  This is commonly called "flushing I/O buffers".
These actions are processor dependent.
End Note

Note xx
An example of a FLUSH statement is:

FLUSH( 10, ERR=20)
End Note

284:21 Change "<rewind-stmt>," to "<rewind-stmt>, <flush-stmt>"