Version 1.7 of ais/ai-00026.txt

Unformatted version of ais/ai-00026.txt version 1.7
Other versions for file 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:
!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