Version 1.7 of ais/ai-00026.txt
!standard A.12.1 (28-35) 00-09-26 AI95-00026/06
!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
!qualifier Omission
!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. Stream files also fail to describe their conceptual
model.
The intent was that stream files that support positioning are similar to
direct files, and that other stream files are similar to sequential
files. Both of these file types are described in A.8. Note, however, that
A.8 specifically says it does not apply to stream files.
Since stream files with positioning are intended to be similar to direct files,
the current index of a stream file should be handled similarly (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.
!corrigendum A.12.1(2)
Insert before the paragraph:
The library package Streams.Stream_IO has the following declaration:
the new paragraph:
The elements of a stream file are stream elements. If positioning is supported
for the specified external file, a current index and current size are maintained
for the file as described in A.8. If positioning is not supported, a current
index is not maintained, and the current size is implementation defined.
!corrigendum A.12.1(28)
Insert after 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).
the new paragraphs:
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.
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.
!corrigendum A.12.1(30)
Insert after 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.
the new paragraph:
The Size function returns the current size of the file.
!corrigendum A.12.1(31)
Replace the paragraph:
The Index function returns the current file index, as a count (in stream
elements) from the beginning of the file. The position of the first element
in the file is 1.
by:
The Index function returns the current index.
!corrigendum A.12.1(32)
Insert after the paragraph:
The Set_Index procedure sets the current index to the specified value.
the new paragraphs:
If positioning is supported for the external file, the current index is
maintained as follows:
- For Open and Create, if the Mode parameter is Append_File, the current
index is set to the current size of the file plus one; otherwise, the current
index is set to one.
- For Reset, if the Mode parameter is Append_File, or no Mode parameter
is given and the current mode is Append_File, the current index is set to the
current size of the file plus one; otherwise, the current index is set to one.
- For Set_Mode, if the new mode is Append_File, the current index is set
to current size plus one; otherwise, the current index is unchanged.
- For Read and Write without a Positive_Count parameter, the current
index is incremented by the number of stream elements read or written.
- For Read and Write with a Positive_Count parameter, the value of the
current index is set to the value of the Positive_Count parameter plus the
number of stream elements read or written.
!corrigendum A.12.1(34)
Delete the paragraph:
The Size function returns the current size of the file, in stream elements.
!corrigendum A.12.1(35)
Delete 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.
!corrigendum A.12.1(36)
Delete the paragraph:
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.
!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.
****************************************************************
!from Editor 99-04-11
At the recent ARG meeting, we determined to rearrange the paragraphs of this
section to make the most possible sense. This was done by putting related
items together. Traditionally, entities in Ada 95 packages are described in
the order that they are declared in the package. However, this package is
quite disorganized; Flush and Set_Mode have more in common with Open and Reset
than they do with Size and Set_Index. We decided to break this meta rule
rather than to rearrange the package.
The meeting also added a reference to the description of the model of
direct access files given in A.8. This is needed because A.8 says specifically
that it does not apply to stream files.
****************************************************************
Questions? Ask the ACAA Technical Agent