flocate - set file position indicator in ISAM file (BS2000)

Syntax

#include <stdio.h> int flocate(FILE *stream, void *key, size_t keylen, int option);

Description flocate() is used to explicitly position an ISAM file with record I/O. flocate() sets the

file position indicator of the file pointed to by stream according to the following specifications:
the key value key,
the key length keylen and
the specified option (_KEY_FIRST, _KEY_LAST, _KEY_EQ, _KEY_GE).

FILE *stream is the file pointer of an ISAM file opened in the mode
type=record,forg=key (see fopen(), freopen()).

void *key is the pointer to an area containing the key value.

size_t keylen is the length of the key value. The value must not be zero.

If keylen is less than the key length of the file, then flocate() internally pads the key value
with binary zeros to the key length of the file and uses this generated key as the basis for
positioning.

If keylen is greater than the key length of the file, flocate() internally truncates the key
value from the right to the key length of the file and uses this shortened key as the basis for
positioning.

int option may contain the following values defined in stdio.h:

_KEY_FIRST	Sets the file position indicator to beginning of file. The key and keylen parameters are ignored. Positioning works even if the file is empty.
_KEY_LAST	Sets the file position indicator to end of file. The key and keylen parameters are ignored. Positioning works even if the file is empty.
_KEY_EQ	Sets the file position indicator to the first record with the specified key.
_KEY_GE	Sets the file position indicator to the first record with a key value greater than or equal to the specified key.

Return val.

0

> 0

EOF

if successful. The record with the specified key exists.

The record does not exist.

if an error occurs.

Notes

If the call was error-free (return values 0 or > 0), the EOF flag of the file is reset. If the specified key value is not present in the file (return value > 0), the current setting of the file position indicator remains unchanged. Sole exception: if at the time of the flocate call the file is positioned on the second or higher key of a group of records with identical keys, then flocate() positions the file on the first record after this group. In ISAM files with key duplication, flocate() cannot be used to position on the second or higher record of a group with identical keys. This can only be done by sequential reading or deleting. flocate() can only be used to position on the first record or after the last record of such a group.

See also

fdelrec(), fgetpos(), fsetpos(), fopen(), freopen(), stdio.h.