Version 1.2 of ais/ai-00026.txt

Unformatted version of ais/ai-00026.txt version 1.2
Other versions for file ais/ai-00026.txt

!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
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 to Size(File)+1. Beyond this, the current file index maintained by Stream_IO is set in the same manner as the current file index maintained by instances of Direct_IO.
!question
Which operations set and modify the current file index of a stream file?
!recommendation
The following operations set the value of the current index if positioning is supported for the specified file:
- Open(File,Mode,Name,Form) and Create(File,Mode,Name,Form) set the
current index to Size(File)+1 if Mode(File) = Append_File, and to 1 otherwise.
- Read increments the current index by the number of stream elements
read.
- Write increments the current index by the number of stream elements
written.
- Set_Index(File,To) sets the current index to the value of To (which
may be greater than Size(File)).
- Set_Mode(File,Mode) sets the current index to Size(File)+1 if Mode =
Append_File, and leaves it unchanged otherwise.
- Reset(File,Mode) sets the current index to Size(File)+1 if Mode =
Append_File, and to 1 otherwise; Reset(File) sets the current index to Size(File)+1 if Mode(File) = Append_File, and to 1 otherwise.
Set_Index and the versions of Read and Write with Positive_Count parameters raise Use_Error if positioning is not supported for the specified file.
!wording
(See corrigendum.)
!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 Set_Index and Set_Mode. The intent was to model the current index of a stream file after the current index of a direct file (except that the index counts stream elements rather than file elements, and except that a stream file can be opened in or reset to mode Append_File). The 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)
Replace the paragraph:
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).
by:
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)
Replace the paragraph:
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.
by:
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)
Replace the paragraph:
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.
by:
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)
Replace the paragraph:
The Set_Index procedure sets the current index to the specified value.
by:
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)
Replace the paragraph:
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.
by:
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

!section A.12.1(31)
!subject Do Read and Write advance the current index?
!reference RM9X-A.12.1(31);5.95
!from Norman Cohen
!reference as: 95-5088.a Norman H. Cohen 95-1-30>>
!discussion

Is it intended that calls on Stream_IO Read and Write procedures advance
the current index, as in instances of Direct_IO?  That is not stated
anywhere in A.12.1.  If no, what is the point of maintaining a current
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