5.2.4.22. seek


         +- = -+                  +-CHAR-+
>>-seek(-+-----+-offset-+-------+-+------+-)-------------------><
         +- < -+        +-READ--+ +-LINE-+
         +- + -+        +-WRITE-+
         +- - -+

Sets the read or write position to a given number (offset) within a persistent stream. If the stream is open for both reading and writing and you do not specify READ or WRITE, both the read and write positions are set.

Note

See Chapter 14, Input and Output Streams for a discussion of read and write positions in a persistent stream.

To use this method, you must first open the stream object (with the OPEN method described previously or implicitly with an input or output operation). One of the following characters can precede the offset number:

=: Explicitly specifies the offset from the beginning of the stream. This is the default if you supply no prefix. For example, an offset of 1 means the beginning of the stream.
<: Specifies offset from the end of the stream.
+: Specifies offset forward from the current read or write position.
-: Specifies offset backward from the current read or write position.

The seek method returns the new position in the stream if the read or write position is successfully located, or an appropriate error message.

The following is a description of the options for seek:

READ: specifies that the read position be set.
WRITE: specifies that the write position be set.
CHAR: specifies that positioning be done in terms of characters. This is the default.
LINE: specifies that the positioning be done in terms of lines. For non-binary streams, this is potentially an operation that can take a long time to complete because, in most cases, the file must be scanned from the top to count the line-end characters. However, for binary streams with a specified record length, the new resulting line number is simply multiplied by the record length before character positioning. See Section 14.1.5, “Line versus Character Positioning” for a detailed discussion of this issue.
Note
If you do line positioning in a file open only for writing, you receive an error message.

Example 5.126. Stream object - SEEK method

stream_name~seek("=2 read")
stream_name~seek("+15 read")
stream_name~seek("-7 write line")
fromend  = 125
stream_name~seek("<"fromend read)