J3/98-210 Date: 23 Oct 1998 To: J3 From: R. Maine Subject: Edits for sequential stream I/O This paper proposes edits for B.4, stream I/O. Specs and syntax were proposed in paper J3/98-209. The edits of the current paper are for the simplest case, without any random positioning capability. These edits are intended to be compatable with the possible addition of a random positioning capability, but they do stand alone if the random positioning issues cannot be acceptably resolved. These edits are all relative to J3/98-007R3. In 9.0 [155:11] add ", WAIT" after "REWIND". This edit not really related to stream I/O. It was already a bit anomalous to start talking about records before we mentioned that files have (or now may have) records. This anomaly gets worse when files might not have records. So we will do a minor reorganization. The (very little) material in 9.2.0 can be readily moved up into 9.0 and expended to cover the new concepts. And we then promote all the 9.2 subsections up one level (they went a little deep anyway). Thus: [155:15+] Add as new paragraphs A file is composed of either a sequence of values or sequence of records, which provide an extra level of organization to the file. A file composed of records is called a <>. A file composed of a sequence of values without a record structure is called a <>. A processor may allow a file to be viewed both as a record file and as a stream file; in this case the relationship between the values when viewed as a stream file and the records when viewed as a record file is processor dependent. A file is either an external file or an internal file. In 9.2, Files [156:19-23] Delete all of 9.2 (including the heading), except for the note 9.3. Then promote all former subsections of 9.2 up one level. [156:24-25] Add "external" before "files" in note 9.3 and then move the note to [156:36+] In C.6.1 [387:32] "Files" -> "External files" and change the xref to be to the external files section in 9. In 9.2.1.2.*, File access [157:8] Replace the first sentence by "There are three methods of accessing the data of an external file: sequential, direct, and stream." [157:16+] Add para "<> is a method of accessing the records of an external record file in the order of their record numbers." [157:17] Unbolden "sequential access" [157:30-31] replace these lines by "(3) The records of the file shall be read or written only by sequential access input/output statements." [157:32+] Add para "<> is a method of accessing the records of an external record file in arbitrary order." [157:17] Unbolden "direct access" [157:45-46] replace these lines by "(3) The records of the file shall be read or written only by direct access input/output statements." [158:8+] Add new section "9.2.2.3 Stream access <> is a method of accessing the values of an external stream file. When connected for stream access, an external file has the following properties: (1) The values of the file shall be read or written only by stream access unformatted input/output statements." (2) The order of the values of the file is the order in which they were written. In 9.2.1.3.*, File position [158:12-14] Replace "record(s)" by "record(s) or value(s)" 3 times. [158:15] "file" -> "record file" [158:27,29] "the file" -> "a record file" twice. [158:35-36] "sequential or direct" -> "sequential, direct, or stream" [159:4+] Add para "For stream access, the file position is not changed." [159:8+] Add para "For stream access, if no error condition occurred, the file position is not changed." In 9.2.2, Internal files [159:19] "has" -> "is a record file with" The two subsections of this section aren't clearly distinguishable. Although the first is labelled as "properties" and the second as "restrictions", there are things in the first list that are clearly restrictions, and there are things in the second list that directly correspond to "properties" listed for external files. Thus: [159:18] Delete the section heading [160:1-2] Delete the section heading and the lead-in to the list [160:3-6] Renumber these as items 10 and 11. In 9.3.4, OPEN statement [163:26] "or DIRECT" -> ", DIRECT, or STREAM" [163:27] "or direct" -> ", direct, or stream" [163:35] "direct" -> "direct or stream" [163:36] After "." insert "The value shall not be FORMATTED if the file is being connected for stream access." [163:42] After "." insert "This specifier shall not be present when a file is being connected for stream access." [164:22] "sequential" -> "sequential or stream" In 9.4.1 Control information list [169:24] before the "." insert "or a <>, depending on whether the file connection is for sequential access or stream access." [169:37] after "sequential" insert "or stream" [170:25] after "external" insert "record" [171:2] after "omitted" insert "from a formatted sequential input/output statement". (Otherwise we manage to imply that, for example, unformatted direct access input/output statements all perform advancing formatted sequential input/output, which would seem a bit bizzare). [171:28] After "Records" insert "and values" In 9.4.2, Data transfer I/O list This isn't directly related to stream I/O, but its something I got reminded of while doing the stream I/O stuff. It does cause some confusion in stream I/O, but only because it causes exactly the same confusion elsewhere. I commented about this once sometime before, but my comment apparently got lost. I don't really feel like diverting my stream I/O work to deal with this, so I'll just add it as an unresolved issue. [173:43+] Add J3 note after Note 5.29 "[begin J3 note] Unresolved issue xx. The definition of the term "effective item" as used in I/O lists is dispersed and confused. Note 9.29 says that the rules in 9.4.2 determine the list off effective items. This is true, except that the term "effective item is never once mentioned there outside of note 9.29 itself. The rules are there, but not the term. The first para of 9.4.4.4, data transfer, appears to define the term "next effective item" and even puts in in bold face as befits the defining occurance. It would seem more sensible to define the term "effective item". I think we can rely on the English definition of "next". In addition to that, if this is supposed to be the definition, it is wrong, because it does NOT mention the rules of 9.4.2. For example, it does not say anything about the treatment of derived types and distinguish the cases where a scalar of derived type is treated as a single effective item from the cases where it is decomposed into its components. Speaking of which, note 9.29 is wrong because its statement that effective items in formatted i/o are ALWAYS of intrinsic type is now incorrect with derived type I/O. I suggest that section 9.4.2 say somewhere that it is defining the term "effective item". Then the words about this in 9.4.4 can be removed and replaced by a reference to 9.4.2. Section 10 uses the term extensively, but should not need modifying, except possibly to refer to wherever the term is defined. [end J3 note]" In 9.4.3, Error, etc. [174:25] delete "either of" [174:28+] Add list item "(3) When an attempt is made to read beyond the end of a stream file." [174:31] After the "." add "An end-of-file condition also may occur during execution of a stream input statement." [176:14] "gg" -> "g" (typo) In 9.4.4, Execution of data transfer... [177:2] "records" -> "the file" [177:35,36, 38] Insert "record" after "unformatted" 3 times. The following 2 edits doen't really have anything to do with stream i/o. The sentences appear to be no-ops that are more confusing than helpful in that they implies that there are other possibilities. The only other possibility is that it might be a formatted record when we expect an unformatted one or vice versa (as we've defined record files to consist of those 3 kinds of records). We have also already said that all of the records of a file are either all formatted or all unformatted, except for the endfile record. And we've said that formatted records can only be read/written by formatted i/o statements, ans simillarly for unformatted. So there is nothing left for these sentences to actually mean. They confusingly implies that a file might have a mixture of formatted and unformatted records - perhaps they are holdovers from some draft where that was allowed. [177:40-41] Delete the sentence "On input, the file shall be positioned so that the record read is an unformatted record or an endfile record." and change the following "The" to "On input, the". [178:27-28] Delete the para. [179:3+] Insert new section "9.4.4.4.3 Stream data transfer Formatted stream data transfer is not defined by this standard. During unformatted stream data transfer, data are transfered without editing between the file and the entities specified by the input/output list. Objects of intrinsic or derived types may be transferred by means of an unformatted stream data transfer statement. On input, each value in the file shall be of the same type as the corresponding entity in the input list, except that one complex value may correspond to two real list entities or two real values may correspond to one complex list entity. The type parameters of the corresponding entities shall be the same. [begin j3 note] Unresolved issue xx As mentioned in note 9.37, the rules for unformatted i/o are pretty strict about type matching. In particular, they disallow writing a character variable of length N and then reading that data as an array of N characters of length 1 (or conversely). I presume this is to allow processor freedom in padding; it might do something like pad each scalar character to the next word boundary, but only put such padding at the end of a character string of length N. The standard requires the processor treat an array as equivalent to the sequence of scalars, but doesn't have any such requirements for a string of length N being equivalent to a sequence of strings of length N. My model of unformatted stream I/O is that it looks just like unformatted record I/O without the record boundaries. Do we want to allow more freedom for the user on character data, thus getting pickier about what the processor must do? If so, do we want to be equally liberal to the user (and strict to the processor) about unformatted record I/O? Note that this concept would "work" only by treating character length as a special case; you can't assume that an arbitrary type with a non-kind parameter value of 2 necessarily has any ascertainable relationship to 2 values of the same type with a parameter value of 1. [end j3 note] The unit specified shall be an external unit. If an entity in the input list is of type character, the character entity shall have the same length and the same kind type parameter as the character value. Also, if two real values correspond to one complex entity or one complex value corresponds to two real entities, all three shall have the same kind type parameter value." 9.4.4.4.3 on derived type I/O appears to need almost no changes. That section already treats sequential and direct access the same, and it looks like stream works as well. The only places where it talks about records are about formatted i/o. The intro sentences to the 2 paras at [182:29-41] may be intended to apply to unformatted also; they don't explicitly say formatted, but if intended to apply to unformatted they already have a problem because they refer to edit descriptors. [179:25] Before the "." insert "or at the current file position" [180:6,34] Align the ampersands. (Not related to stream I/O) [182:19] Delete the first "other". (Not related to stream I/O) [182:38+] Add new J3 note "Unresolved issue xx The derived type I/O section has some wording in the above 2 paras about "where the last edit descriptor finished". This only makes sense for formatted I/O (and not all cases of that). This wording either needs to be generalized, or we need to say that it is for formatted I/O, and then add comparable statements about unformatted." In 9.6, File positioning statements [185:22-23] replace the sentence spanning these line with "A file that is connected for direct access shall not be referred to by a BACKSPACE, ENDFILE, or REWIND statement. A file that is connected for stream access shall not be referred to by a BACKSPACE statement." [186:9,14] (twice) after "ENDFILE statement" insert "for a file connected for sequential access" [186:16+] Add new para "Execution of an ENDFILE statement for a file connected for stream access causes the terminal point of the file to become equal to the current file position. Only values before the current position are considered to have been written; thus only those values may be subsequently read. Subsequent stream output statements may be used to write further data to the file. [186:17-18] after "creates the file" insert "; if the file is connected for sequential access it is created" In 9.7.1, Inquiry specifiers [187:24+] Add new line "<> STREAM = " [188:40] Delete "and". Before the "." insert ", or STREAM is the file is connected for stream access" [189:11+] Duplicate lines [189:7-11], changing all 5 occurances of "DIRECT" to "STREAM" and incrementing the subsection number. [189:33] after "connection" insert ", or if the connection is for stream access" In Annex C [392:16] "or direct" -> ", direct, or stream"