CVS difference for ai12s/ai12-0130-1.txt

Differences between 1.3 and version 1.4
Log of other versions for file ai12s/ai12-0130-1.txt

--- ai12s/ai12-0130-1.txt	2014/11/13 06:10:36	1.3
+++ ai12s/ai12-0130-1.txt	2014/11/15 03:31:04	1.4
@@ -1,7 +1,12 @@
-!standard A.8.1(10)                          14-10-09   AI12-0130-1/01
+!standard A.8.1(10)                          14-11-14   AI12-0130-1/02
 !standard A.8.2(28/3)
 !standard A.8.4(10)
-!class Amendment 14-10-09
+!standard A.10.3(21)
+!standard A.12.1(28/2)
+!standard A.12.1(28.6/1)
+!class binding interpretation 14-10-19
+!status Corrigendum 2015 14-11-14
+!status ARG Approved 7-0-1  14-10-19
 !status work item 14-10-09
 !status received 14-10-01
 !priority Low
@@ -12,14 +17,14 @@
 
 Flush is added to Sequential_IO and Direct_IO.
 
-!problem
+!question
 
 Text_IO and Stream_IO have procedure Flush to ensure that internal
 buffers are "flushed". However, Sequential_IO and Direct_IO do
 not. This makes it impossible to ensure that a write using one
-of these packages has completed.
+of these packages has completed. Should these routines be added? (Yes.)
 
-!proposal
+!recommendation
 
 (See summary.)
 
@@ -33,36 +38,110 @@
 
    procedure Flush (File : in File_Type);
 
-      The effect of Flush is the same as the corresponding subprogram
-      in Streams.Stream_IO (see A.12.1).   
+      The Flush procedure synchronizes the external file with the internal
+      file (by flushing any internal buffers) without closing the file. For
+      a direct file, the current index is unchanged; for a stream file
+      (see A.12.1), the current position is unchanged.
 
-[Editor's note: This is how Text_IO.Flush is defined. We could consider
-removing A.10.3(20-21) since it would be mostly subsumed by A.8.2 (and
-rest could be moved to A.10.2), but that seems like work. :-) Note that
-Flush doesn't make much sense being defined in A.10.3 (which is about
-Standard_Output and the like).]
+      The exception Status_Error is propagated if the file is not open. The
+      exception Mode_Error is propagated if the mode of the file is In_File.
 
+Modify A.10.3(21):
+
+The effect of Flush is the same as the corresponding subprogram in
+{Sequential_IO (see A.8.2)}[Streams.Stream_IO (see A.12.1)]. If File is
+not explicitly specified, Current_Output is used. 
+
+Modify A.12.1(28/2):
+
+The subprograms given in subclause A.8.2 for the control of external files
+(Create, Open, Close, Delete, Reset, Mode, Name, Form, [and] Is_Open{, and
+Flush}) are available for stream files.
+
+Delete A.12.1(28.6/1).
+
 !discussion
 
 Consistency suggests that Flush should be in all of the I/O packages,
 not just two.
 
-It's thought that it wasn't included in Sequential_IO and Direct_IO
-because these packages don't use any buffering. But of course the target
-system might use buffering whether or not it makes sense to the Ada
-program. Most implementations of Flush also call a target OS function to
+It's thought that Flush wasn't included in Sequential_IO and Direct_IO
+because these packages don't use any buffering. But the definition of those
+packages only specify the behavior relative to the internal file; what the
+target system does with the external file isn't specified. In particular,
+it could use buffering whether or not it makes sense to the Ada program.
+Most implementations of Flush also call a target OS function to
 ensure that any pending writes are completed. It's odd that this
-functionality isn't available in Sequential_IO and Direct_IO.
+functionality isn't available in Sequential_IO and Direct_IO; this
+lack makes it harder to write cooperating programs using these I/O packages.
 
-[Editor's note: I used "It's thought" because I don't know for sure, this
-is my best guess. Maybe Tucker or Bob could explain this oddity. If not,
-delete this note!]
-
 It's possible to use Stream_IO (which has Flush) to emulate Sequential_IO
 and Direct_IO. But such code is necessarily more complicated and
 error-prone than using the original packages (especially for Direct_IO,
 which requires calculating a positioning location, an operation that is
 easy to get wrong).
+
+Since this is inconsistent for no obvious reason, and the routine has value
+for all of the I/O packages, we add the missing procedures.
+
+!corrigendum A.8.1(10)
+
+@dinsa
+@xcode<   @b<function> Is_Open(File : @b<in> File_Type) @b<return> Boolean;>
+@dinst
+@xcode<   @b<procedure> Flush (File : @b<in> File_Type);>
+
+!corrigendum A.8.2(28/3)
+
+@dinsa
+@xindent<Returns True if the file is open (that is, if it is associated
+with an external file); otherwise, returns False.>
+@dinss
+@xcode<   @b<procedure> Flush(File : @b<in> File_Type);>
+
+@xindent<The Flush procedure synchronizes the external file with the internal
+file (by flushing any internal buffers) without closing the file. For
+a direct file, the current index is unchanged; for a stream file
+(see A.12.1), the current position is unchanged.>
+
+@xindent<The exception Status_Error is propagated if the file is not open. The
+exception Mode_Error is propagated if the mode of the file is In_File.>
+
+!corrigendum A.8.4(10)
+
+@dinsa
+@xcode<   @b<function> Is_Open(File : @b<in> File_Type) @b<return> Boolean;>
+@dinst
+@xcode<   @b<procedure> Flush (File : @b<in> File_Type);>
+
+!corrigendum A.10.3(21)
+
+@drepl
+@xindent<The effect of Flush is the same as the corresponding subprogram in
+{Sequential_IO (see A.8.2)}[Streams.Stream_IO (see A.12.1)]. If File is
+not explicitly specified, Current_Output is used.>
+@dby
+@xindent<The effect of Flush is the same as the corresponding subprogram in
+Sequential_IO (see A.8.2). If File is not explicitly specified,
+Current_Output is used.>
+
+!corrigendum A.12.1(28/2)
+
+@drepl
+The subprograms given in subclause A.8.2 for the control of external files
+(Create, Open, Close, Delete, Reset, Mode, Name, Form, and Is_Open) are
+available for stream files.
+@dby
+The subprograms given in subclause A.8.2 for the control of external files
+(Create, Open, Close, Delete, Reset, Mode, Name, Form, Is_Open, and Flush)
+are available for stream files.
+
+!corrigendum A.12.1(28.6/1)
+
+@ddel
+The Flush procedure synchronizes the external file with the internal file
+(by flushing any internal buffers) without closing the file or changing
+the position. Mode_Error is propagated if the mode of the file is In_File.
 
 !ASIS
 

Questions? Ask the ACAA Technical Agent