Position Pointer Details

Each persistent stream maintains a position pointer to mark the position where a read operation or write operation takes place. By definition, position 1 marks the first character in a stream, and the positions are counted in number of characters relative to the beginning of a stream. When a stream is opened, the position pointer is set to position 1 of the stream.

The general use of position pointers is to ease the sequential reading and writing of streams. By default the first read operation starts at position 1, reads a number of characters or a line, and automatically increments the read position to the next unread character or line. A subsequent read operation starts at the incremented read position (the current read position). Similarly, a first write operation starts at position 1, writes a number of characters or a line, and automatically increments the write position behind the last character written. A subsequent write operation starts at the incremented write position (the current write position). The current position is maintained automatically. Thus, for sequential processing of a persistent stream, the stream I/O functions do not require the specification of a stream position.

The position pointer in a persistent stream can be manipulated to a certain degree to set it to a specific position where the next read operation or write operation should take place.

A CHARIN or CHAROUT start value of 1 sets the current position to the beginning of a stream.
A LINEIN line value can be set to any line number within a stream, which sets the current position to the beginning of this line.
A LINEOUT line value of 1 sets the current position to the beginning of the stream (the beginning of the first line).

Note that the line parameter specifies a line, not the position of a character. Lines are counted from 1 to n, where line 1 is the first line in a stream.

Each open stream has its own position pointer. If a stream is opened for read operations, the pointer is either automatically set by any sequence of CHARIN and LINEIN function calls, or it is explicitly manipulated as described. Likewise, if a stream is opened for write operations, the pointer is either automatically set by any sequence of CHAROUT and LINEOUT function calls, or it is explicitly manipulated as described.

The CHARIN and LINEIN functions manipulate the same read position in a stream; while the CHAROUT and LINEOUT functions manipulate the same write position in a stream. For example, if two lines of 80 characters each were written to a fixed length data set by LINEOUT, followed by a CHAROUT of five characters, the current write position is 166 (the position where the next write operation would start). A subsequent LINEOUT with 80 characters would not succeed because only 75 characters would fit in the record. The line would be truncated. Conversely, if a line of 50 characters was written by LINEOUT to a fixed length (80) data set, the line is padded with blanks, and the current write position is 81 (the position where the next write operation would start). A subsequent CHAROUT or LINEOUT function starts at position 81.