PositionFile( )
Positions a binary or stream file to the specified offset or record, relative to the base.
Syntax
[returnfield = ] [callproc] positionfile(handle =
handle, offset = offset | record = recordno
[ , base = base] )
returnfield
Specifies the name of field to which the result is returned. Integer.
handle
Specifies the file identifier used by the 4GL file access functions. Integer.
offset
Specifies the location, in bytes, from the specified base. If the base is not specified, the location is measured from the beginning of the file.
For a binary file, the positionfile() function always positions the file to the beginning of a record. 4GL adjusts the file position to the beginning of the record containing the byte number specified by offset.
Can be a positive or negative integer, including zero. Integer.
recordno
Specifies the location, in record numbers, from the specified base. If the base is not specified, the location is measure from the beginning of the file. Can be a positive or negative, non-zero integer. Applies to binary files only. Integer.
base
Specifies the location to start measuring the offset or record from. The base can be 'start', 'end', or 'record'. The default is base = 'start'. String.
Description
The positionfile() built-in function positions a binary or stream file. You specify the position by offset, the location in bytes, or by recordno, the record number. You must indicate the position by specifying a record number or the amount of offset, but not both.
The offset or record number is relative to the position you specify by the keyword base. The base can be the current position, or the beginning or end of the file. If you do not specify the base, the record number or offset is measured from the beginning of the file.
The recordno indicates the number of records forward or backward from the base. A record is a logical division only, which is determined by the file's record size. You can only use the record keyword for binary files.
The offset indicates the number of bytes forward or backward from the base. For a binary file, the positionfile() function always positions the file to the beginning of a record. If you specify the offset clause, 4GL adjusts the file position to the beginning of the record containing the specified byte number.
You cannot specify a value for offset or record that moves beyond the beginning or end of the file.
You can only position a file that was previously opened with the openfile() statement. The file must be open and the handle known to 4GL. You cannot position a file that was opened in append or create mode.
You cannot position a text file, but you can rewind it with the rewindfile() statement.
The procedure returns 0 if the function completes without error.
Examples
In a binary file, records are logical divisions only; that is, there is no physical record delimiter between records. In the examples in this section, the file is a binary file, with a record size of 41 bytes. The beginning of each record is determined from the record size, as shown in the following table:
The following examples position the file to the beginning of the file (byte 0):
positionfile(handle=handle, offset=1, base='start')
or
positionfile(handle=handle, record=1, base='start')
The following example also positions the file to byte 0, because the offset is adjusted to be the beginning of a record:
positionfile(handle=handle, offset=39, base='start')
In the following example, the file position does not change. The file pointer remains at byte 164:
positionfile(handle=handle, offset=20, base='current')
The following example positions the file to byte 123:
positionfile(handle=handle, offset=-1, base='current')
The following example positions the file to byte 164, because byte 187 is in the record beginning at byte 164.
positionfile(handle = handle, offset=-100, base ='end')
The following examples position the file to record 7 (byte 246):
positionfile(handle=handle, record=7, base='start')
or
positionfile(handle=handle, record=-1, base='end')
The following example positions the file to the 3rd record, offset 82:
positionfile(handle = handle, record=-5, base ='end')