CVS difference for ais/ai-00026.txt

Differences between 1.1 and version 1.2
Log of other versions for file ais/ai-00026.txt

--- ais/ai-00026.txt	1998/09/30 00:17:07	1.1
+++ ais/ai-00026.txt	1999/08/16 19:52:42	1.2
@@ -1,12 +1,13 @@
-!standard A.12.1   (31)                               96-06-05  AI95-00026/03
+!standard A.12.1   (31)                               99-08-08  AI95-00026/04
 !class binding interpretation 95-06-25
+!status Corrigendum 2000 99-08-13
 !status WG9 approved 95-06-14
 !status ARG approved 11-0-0 (by letter ballot) 96-06-05
 !status ARG approved (subject to letter ballot) 10-0-0  95-11-01
 !status received 95-06-25
 !subject Stream_IO.Read and Stream_IO.Write advance the current index
 
-!summary 96-04-30
+!summary
 
 Opening a file of type Streams.Stream_IO.File_Type in mode Append_File,
 or resetting such a file to mode Append_File, sets the current file index
@@ -14,11 +15,11 @@
 Stream_IO is set in the same manner as the current file index maintained
 by instances of Direct_IO.
 
-!question 95-06-25
+!question
 
 Which operations set and modify the current file index of a stream file?
 
-!recommendation 96-04-30
+!recommendation
 
 The following operations set the value of the current index if
 positioning is supported for the specified file:
@@ -47,10 +48,11 @@
 parameters raise Use_Error if positioning is not supported for the
 specified file.
 
-!wording 95-06-25
+!wording
 
+(See corrigendum.)
 
-!discussion 95-06-25
+!discussion
 
 A.12.1 describes the current index, or position, of a stream file, but
 does not indicate that its value is set by any operation other than
@@ -61,8 +63,87 @@
 recommendation is based on the behavior described in A.8(4), A.8.2, and
 A.8.5 for direct files.  (The part of the recommendation about the
 raising of Use_Error echoes A.12.1(33).)
+
+!corrigendum A.12.1(28)
+
+@drepl
+The subprograms Create, Open, Close, Delete, Reset, Mode, Name, Form,
+Is_Open, and End_of_File have the same effect as the corresponding
+subprograms in Sequential_IO (see A.8.2).
+@dby
+The subprograms Create, Open, Close, Delete, Mode, Name, Form, Is_Open, and
+End_of_File have the same effect as the corresponding subprograms in
+Sequential_IO (see A.8.2). In addition, if positioning is supported for the
+specified external file, a current index is maintained for the file. The
+current index is set to Size(File) +1 by Open and Create if Mode(File) =
+Append_File, and to 1 otherwise.
+
+!corrigendum A.12.1(29)
+
+@drepl
+The Stream function returns a Stream_Access result from a File_Type
+object, thus allowing the stream-oriented attributes Read, Write, Input, and
+Output to be used on the same file for multiple types.
+@dby
+The Stream function returns a Stream_Access result from a File_Type object,
+thus allowing the stream-oriented attributes Read, Write, Input, and Output
+to be used on the same file for multiple types. If positioning is supported for
+the File_Type object, then the default implementations of these attributes add
+one to the current index.
+
+!corrigendum A.12.1(30)
+
+@drepl
+The procedures Read and Write are equivalent to the corresponding
+operations in the package Streams. Read propagates Mode_Error if the mode of
+File is not In_File. Write propagates Mode_Error if the mode of File is not
+Out_File or Append_File. The Read procedure with a Positive_Count parameter
+starts reading at the specified index. The Write procedure with a Positive_
+Count parameter starts writing at the specified index.
+@dby
+The procedures Read and Write are equivalent to the corresponding operations in
+the package Streams. Read propagates Mode_Error if the mode of File is not
+In_File. Write propagates Mode_Error if the mode of File is not Out_File or
+Append_File. The Read procedure with a Positive_Count parameter starts reading
+at the specified index if positioning is supported for the file. The Write
+procedure with a Positive_Count parameter starts writing at the specified index
+if positioning is supported for the file. Read and Write increment the current
+index by the number of stream elements read or written. Or, for Read and Write
+with a Positive_Count parameter, the value of the current index is set to
+Positive_Count plus the number of stream elements read or written.
+
+!corrigendum A.12.1(32)
+
+@drepl
+The Set_Index procedure sets the current index to the specified value.
+@dby
+The Set_Index procedure sets the current index to the specified value if
+positioning is supported for the file, otherwise Use_Error is raised.
+
+!corrigendum A.12.1(35)
+
+@drepl
+The Set_Mode procedure changes the mode of the file. If the new mode is
+Append_File, the file is positioned to its end; otherwise, the position in
+the file is unchanged.
+@dby
+The Set_Mode procedure changes the mode of the file. If the new mode is
+Append_File, the file is positioned to its end, and the current index is set to
+Size(File)+1; otherwise, the position in the file is unchanged.
+
+The Reset procedure can also change the mode and position of the file. If
+positioning is supported for the file, Reset with no Mode parameter sets the
+current index to Size(File)+1 if the current mode is Append_File, and to one
+otherwise. If positioning is not supported, the position is set to after the
+current end of the file if the mode is Append_File, and to the beginning
+otherwise. The procedure Reset with a Mode parameter is equivalent to a call to
+Set_Mode(File, Mode) followed by a call to Reset(File).
+
+!ACATS test
+
+Create a C-Test to check that the current index is maintained properly.
 
-!appendix 95-06-25
+!appendix
 
 !section A.12.1(31)
 !subject Do Read and Write advance the current index?
@@ -77,5 +158,59 @@
 index?  If yes, it should also be stated that opening a Stream_IO file
 sets the current index to 1.  (Paragraph 35 does state that
 Set_Mode(F,Append) advances the current index to the end of the file.)
+
+****************************************************************
+
+!from Robert Eachus 99-08-08
+
+Notes on corrigendum wording:
+
+A.12.1(28): Removed Reset from the list and added the last two sentences.
+I could have removed Create and Open as well, but it seemed easier to put the
+current index stuff in this paragraph.
+
+A.12.1(29):
+That last sentence is made up from whole cloth, and I'm not sure whether the
+correct behavior should be described as 'add one' or left looser. But if these
+attributes don't maintain the current index, the index is pretty useless. The
+reason it is only defined for the default implementations is so that user
+definitions, written from other primitives, will act correctly without any need
+for testing state. I'd also like to invent an attribute which determines if a
+particular file can be positioned, but that is going too far. Implementations
+can do that anyway.
+
+A.12.1(30):
+Added part starting with 'if positioning...' to the last two sentences, then
+added two more sentences. Note that an implicit effect of the last sentence is
+that the current index is not changed if the call to read or write raises an
+exception. Doing this right will involve resetting the value if a partial read
+or write has been done.
+
+A.12.1(31):
+No change here. The index can be read even for sequential files.
+
+A.12.1(32):
+Appended "if positioning_" again.
+
+A.12.1(33):
+This paragraph was already here. I don't know why calls to Index have to raise
+Use_Error, since many file types do have a current index without explicit
+positioning. But I'm not going to change it.
+
+A.12.1(34):
+Unchanged.
+
+A.12.1(35):
+Writing this 'correctly' is tough. As it is, it says that the current index is
+set in some cases where it can't be read. I see that as less harmful than
+completely opaque wording. Especially as I am adding lots of opaqueness to this
+section already.
+
+The second replacement paragraph is completely new and the third sentence seems
+a bit redundant.  But in this case I need to go out of the way, as the case
+without a current index still changes the file position.
+
+A.12.1(36):
+Unchanged.
 
 ****************************************************************

Questions? Ask the ACAA Technical Agent