docs.intersystems.com
Caché ObjectScript Reference
$ZSEEK
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Search:    

Establishes a new offset into the current sequential file.
Synopsis
$ZSEEK(offset,mode)
Parameters
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


Send us comments on this page
Copyright © 1997-2019 InterSystems Corporation, Cambridge, MA