.SEEK - change read/write position in file, using integer.

Alternate entries: .SEEKB, FSEEK, _FSEEK

Usage:

B:
   %b/manif/seek
   status = .seek( unit, seekint, origin );
/* C users see "expl c lib fseek" */

Where:

unit
is the unit number of the unit you want to reposition.
seekint
is a seek integer (see below).
origin
tells .SEEK where to start moving: the beginning of the file, the current read/write location, or the end of the file (see below).
status
is zero if the seek operation succeeds; otherwise, it is non-zero.

Description:

.SEEK changes to a new read/write position in a file, using a "seek integer" to represent the target position.

If you opened unit with the "zb" option, the seek integer represents a character offset from the "origin". The value of "origin" may be any of the following manifests:

SEEK_SET
moves a distance of "offset" bytes from the beginning of the file. In this case, "offset" must be positive or zero.
SEEK_CUR
moves a distance of "offset" bytes from the current position in the file. "offset" may be positive, negative, or zero.
SEEK_END
moves a distance of "offset" bytes from the end of the file. "offset" may have any value, but positive values move the read/write position beyond the current end of the file.

If you did not specify the "zb" option when opening the file, the seek integer has a more complex format. The upper 14 bits represent a logical block number within the file and the bottom 22 bits represent a character offset within that block. Seek integers of this form can be obtained through calls to .TELL. When the seek integer takes this form, "origin" is usually SEEK_SET; if "origin" is SEEK_CUR or SEEK_END, the "offset" must be zero.

Notes:

Some GCOS8 files are too large for seek integers to be able to address every location in the file. Thus you may be better off to use the library functions .FSPOS and .FGPOS which address locations using "seek structures" instead of seek integers. Seek structures offer a much larger range of addressing.

The .SEEK function will not work on concatenated file strings, i.e. lists of files specified as "file1+file2+file3".

The .SEEK function is now supported on strings that have been opened for I/O.

See Also:

expl b lib open
to open a file using the "zb" option.
expl b lib .tell
to obtain seek integers for the current read/write location.
expl b lib .fspos
to seek to a new position using a seek structure.
expl b lib .fgpos
to obtain seek structures for the current read/write location.

Copyright © 2000, Thinkage Ltd.