Rexx lets you move the read or write position of a persistent stream object to any location within the stream. You can specify this location in terms of characters or lines.

Character positioning is based upon the view of a stream as a simple collection of bytes of data. No special meaning is given to any single character. Character positioning alone can move the stream pointer. For example:

MyStream~charin(10,0)

moves the stream pointer so that the tenth character in MyStream is the next character read. But this does not return any data. If MyStream is opened for reading or writing, any output that was previously written but is still buffered is eliminated. Moving the write position always causes any buffered output to be written.

Line positioning views a stream as a collection of lines of data. There are two ways of positioning by lines. If you open a stream in binary mode and specify a record length of x on the open, a line break occurs every x characters. Line positioning in this case is an extension of character positioning. For example, if you open a stream in binary mode with record length 80, then the following two lines are exactly equivalent.

MyStream~command(position 5 read line)
MyStream~command(position 321 read char)

Remember that streams and other Rexx objects are indexed starting with one rather than zero.

The second way of positioning by lines is for non-binary streams. Line-end characters separate lines in non-binary streams. Because the line separator is contained within the stream, ensure accurate line positioning. For example, it is possible to change the line number of the current read position by writing extra line-end characters ahead of the read position or by overwriting existing line-end characters. Thus, line positioning in a non-binary stream object has the following characteristics:

Note that for both character and line positioning, the index starts with one rather than zero. Thus, character position 1 and line position 1 are equivalent, and both point to the top of the persistent stream object. The Rexx I/O processing uses certain optimizations for positioning. These require that no other process is writing to the stream concurrently and no other program uses or manipulates the same low-level drive, directory specification, and file name that the language processor uses to open the file. If you need to work with a stream in these circumstances, use the system I/O functions.