Skip to main content

This is documentation for Caché and Ensemble. See the InterSystems IRIS version of this content.Opens in a new tab

Please read this important announcement about the future of Caché and Ensemble maintenanceOpens in a new tab. Contact your account team to migrate to InterSystems IRIS.

$ZSEEK

Establishes a new offset into the current sequential file.

Synopsis

$ZSEEK(offset,mode)

Parameters

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 parameter 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 parameters 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 $ZPOS special variable contains the current file position. It is the same as the value returned by $ZSEEK(0,1) or $ZSEEK() (with no parameters).

Parameters

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:

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 parameters returns the resulting offset from the beginning of the file (in this case, 13). 

  SET $TEST=0
  SET myfile="C:\InterSystems\Cache\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\Cache\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

See Also

$ZSINNext section
Previous section$ZSEC
FeedbackOpens in a new tab