!standard A.10.1   (21)                               99-08-31  AI95-00057/03
!standard A.10.3   (20)
!standard A.12.1   (25)
!class binding interpretation 95-06-25
!status Corrigendum 2000 99-05-24
!status WG9 approved 95-06-14
!status ARG approved 10-0-0  95-11-01
!status received 95-06-25
!qualifier Error
!subject Text_IO.Flush should use mode 'in'

!summary

The mode of the parameter of Text_IO.Flush is 'in' (not 'in out').
The same is true of Streams.Stream_IO.Flush.

!question

A.10.1(21) shows the parameter of Text_IO.Flush as mode 'in out'.
This makes it impossible to flush Standard_Output.  Is this the
intent?  (No.)

!recommendation

The parameter mode of Text_IO.Flush and Stream_IO.Flush is 'in'
(not 'in out', as shown in the International Standard).

!wording

(See corrigendum.)

!discussion

It is important to be able to call Flush on the Current_Output,
Standard_Output, Current_Error, and Standard_Error files.
However, these files are only accessible via function results
or dereferencing an access-to-constant value; thus they cannot
be flushed if the mode is 'in out'.

Note that Current_Output is flushed by the parameterless Flush procedure
(see A.10.3(21)); thus it had better make sense to flush Current_Output.

Therefore, we make the mode of the parameter of Flush be 'in'.
This is consistent with procedures like Put, which also modify
the file; a level of indirection is presumed in the implementation.

For consistency, the same applies to Stream_IO.Flush (see A.12.1(25)).

!corrigendum A.10.01(21)

@drepl
@i<-- Buffer control>
@xcode<@b<procedure> Flush (File : @b<in out> File_Type);
@b<procedure> Flush;>
@dby
@i<-- Buffer control>
@xcode<@b<procedure> Flush (File : @b<in> File_Type);
@b<procedure> Flush;>

!corrigendum A.10.03(20)

@drepl
@xcode<@b<procedure> Flush (File : @b<in out> File_Type);
@b<procedure> Flush;>
@dby
@xcode<@b<procedure> Flush (File : @b<in> File_Type);
@b<procedure> Flush;>

!corrigendum A.12.01(25)

@drepl
@xcode<@b<procedure> Flush (File : @b<in out> File_Type);>
@dby
@xcode<@b<procedure> Flush (File : @b<in> File_Type);>

!ACATS test

Test CXAA019 tests that flush has mode 'in' for Text_IO, Wide_Text_IO, and
Stream_IO. It also tests using Flush on Standard_Output.
(Test, 6-1-1, ARG Letter Ballot, February 2001).

!appendix

!section A.10.1(21)
!section A.10.3(20)
!subject Text_IO.Flush should use IN mode
!reference RM95-A.10.1(21)
!reference RM95-A.10.3(20)
!from Tucker Taft 95-06-23
!reference as: 95-5166.a Tucker Taft 95-6-23>>
!discussion

The parameter mode of Text_IO.Flush should be IN
rather than IN OUT, given that Put uses IN mode,
and given that File_Access is access-to-constant.

This was pointed out by Dan Johnston (dan@cs.uq.oz.au)
on comp.lang.ada.

-Tuck

****************************************************************