$ZSEEK (ObjectScript)
Synopsis
$ZSEEK(offset,mode)
Arguments
Argument | Description |
---|---|
offset | The offset into the current file in characters, specified as an integer. Can be zero, a positive integer, or a negative integer. |
mode | Optional — An integer value that determines the relative position of the offset. 0=beginning, 1=current position, 2=end. The default is 0. |
Description
$ZSEEK establishes a new offset into the current device. The current device must be a sequential file. If the current device is not a sequential file, $ZSEEK issues a <FUNCTION> error.
The mode argument determines the point from which offset is based: beginning, current position, or end.
$ZSEEK returns the current position in the file after performing the offset. $ZSEEK without arguments returns the current position in the file without performing an offset.
$ZSEEK can only be used when the device is a sequential file. Invoking $ZSEEK from the Terminal, or when there is no open sequential file results in a <FUNCTION> error. If there is no specifically set current device, $ZSEEK assumes that the device is the principal device.
The $ZIO special variable contains the pathname of the current file. The $ZPOS special variable contains the current file position. It is the same as the value returned by $ZSEEK(0,1) or $ZSEEK() (with no arguments).
Arguments
offset
The offset (in characters) from the point established by mode. This is an offset, not a position. Therefore an offset of 0 from the beginning of the file is position 1, the start of the file. An offset of 1 is position 2, the second character of the file.
An offset can be a position after the end of the file. $ZSEEK fills with blanks for the specified offset.
An offset can be a negative number if mode is 1 or 2. Specifying a negative number that results in a position before the beginning of the file results in a <FUNCTION> error.
mode
The valid values are:
Value | Meaning |
---|---|
0 | Offset is relative to the beginning of the file (absolute). |
1 | Offset is relative to the current position. |
2 | Offset is relative to the end of the file. |
If you do not specify a mode value, $ZSEEK assumes a mode value of 0.
Examples
The following Windows example opens a sequential file and writes “AAA”, $ZSEEK(10) establishes an offset 10 characters from the beginning of the file (filling with 7 blanks), the example writes “BBB” at that position, then $ZSEEK() with no arguments returns the resulting offset from the beginning of the file (in this case, 13).
SET $TEST=0
SET myfile="C:\InterSystems\IRIS\mgr\user\zseektestfile.txt"
OPEN myfile:("WNS"):10
IF $TEST=0 {WRITE "OPEN failed" RETURN}
USE myfile
WRITE "AAA"
SET rtn=$ZSEEK(10)
WRITE "BBB"
SET rtnend=$ZSEEK()
CLOSE myfile
WRITE "set offset:",rtn," end position:",rtnend
The following Windows example writes the letter “A” to a sequential file ten times, with increasing numbers of blank spaces between them. It uses $ZPOS to determine the current file position:
SET $TEST=0
SET myfile="C:\InterSystems\IRIS\mgr\user\zseektestfile2.txt"
OPEN myfile:("WNS"):10
IF $TEST=0 {WRITE "OPEN failed" RETURN}
USE myfile
FOR i=1:1:10 {WRITE "A" SET rtn=$ZSEEK($ZPOS+i,0)}
CLOSE myfile