#include <lcio.h> int kretrv(void *rec, void *key, int flags, FILE *f);
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
K_noupdate
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.
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.
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.
ksearch
, kseek
Copyright (c) 1998 SAS Institute Inc. Cary, NC, USA. All rights reserved.