kretrv

kretrv

Retrieve Next Record from Keyed File

Portability: SAS/C extension

SYNOPSIS
DESCRIPTION
RETURN VALUE
CAUTION
EXAMPLE
RELATED FUNCTIONS
SEE ALSO

SYNOPSIS

#include <lcio.h>

int kretrv(void *rec, void *key, int flags, FILE *f);

DESCRIPTION

The kretrv function retrieves the next record from the keyed stream associated with the FILE object addressed by f . The rec function addresses the area into which the record is to be read. key addresses an area in which the key of the record is to be stored. key may be specified as NULL , in which case the key is not stored. However, the key can always be retrieved from the record itself.

The flags argument is an integer that specifies various options through flag bits. Any combination of the following bits can be specified:

K_backwards: indicates that the record before the current record is to be retrieved.
K_noupdate: indicates that the program will not delete or replace this record.

If you do not specify K_backwards , kretrv always retrieves the next record. If K_noupdate is not specified, the record is always retrieved for update (if the file's open mode permits writing).

For a file with duplicate keys, records with the same key are always returned in the order in which they were added to the file, whether or not K_backwards is specified. K_backwards only affects the order in which records with different keys are retrieved. See CAUTION for additional restrictions relating to files with duplicate keys.

RETURN VALUE

If successful, kretrv returns the length of the record retrieved, including 4 bytes for the key prefix for an ESDS or RRDS data set. If kretrv fails to return a record because the file is positioned to end of file (or beginning of file if you specify K_backwards ), a return code of 0 is returned. If no record is retrieved due to an error, a negative number is returned.

CAUTION

The first kretrv call after a call to ksearch should specify the same flag settings if possible. Specifying different options is not an error, but will necessitate substantial additional processing.

When processing a file with duplicate keys, you are not permitted to switch between forward and backward retrieval except with a call to ksearch .

When the same VSAM cluster is accessed by several streams, with at least one of the streams permitting writing, retrieving a record that the program has previously updated with K_noupdate set may retrieve an obsolete copy of the record. In applications where the same file is opened several times and obtaining the most recent copy of each record is important, you should not set K_noupdate . This is true even if you do not intend to modify the record. Alternately, if your program can detect this out-of-sync condition, you can use afflush to write all buffers to disk, thus ensuring that the record on disk and any copies of the record in memory are identical.

EXAMPLE

See VSAM I/O Example.

RELATED FUNCTIONS

ksearch , kseek