Chapter Contents |
Previous |
Next |
ksearch |
Portability: | SAS/C extension |
SYNOPSIS | |
DESCRIPTION | |
RETURN VALUE | |
CAUTION | |
EXAMPLE | |
RELATED FUNCTIONS | |
SEE ALSO |
SYNOPSIS |
#include <lcio.h> int ksearch(const void *key, size_t keylen, int flags, FILE *f);
DESCRIPTION |
The
ksearch
function searches the keyed stream associated with the
FILE
object addressed by
f
for a
record matching the
key
specification.
The key can either be a full key or a generic key. If the key is generic,
the key length is specified by the
keylen
argument, and only the first
keylen
characters
of each key are considered during the search. If the key is not generic, you
should specify
keylen
as 0, and all characters
of the key are considered. Generic key searches are supported only for KSDS
data sets.
The
flags
argument
is an integer that specifies various options through flag bits. Any combination
of the following bits can be specified:
K_exact
keylen
characters for a generic key search). If
K_exact
is not specified, the first record found with a key greater than or
equal to the key specified (less than or equal to a backward search) is considered
to match.
K_exact
must be specified for
ESDS searches.
K_backwards
K_noupdate
kretrv
.
For files with duplicate keys, you must specify
K_exact
if you specify
K_backwards
, and you must not use a generic
key.
The
ksearch
function
positions the file to the first record with matching keys, but does not copy
the record. You must call
kretrv
to access
the record. If
ksearch
fails to locate
a matching record, the file is positioned to the point at which a matching
record would be inserted. For example,
K_exact
sets positions to the end of file.
K_exact
sets positions to the start of file.
K_exact
sets positions to the first record after the specified
key.
K_exact
sets positions to the first record whose partial key follows
the generic key.
RETURN VALUE |
The
ksearch
function returns the number of records found by the search. This number
is 1, unless the file permits duplicate keys, in which case the number of
records with the key of the first record found is returned. The
ksearch
function returns 0 if no matching record is found, or a negative
value if an error occurred.
CAUTION |
Keys are always compared as character
arrays, even if they are declared as some other type. For instance, if the
key
field of a VSAM file has type
int
, and an inexact search is made for a key greater than or equal
to 4096, a record with a key of -1 may be returned because the search
key, \x00\x00\x10\x00 (in hexadecimal notation) as a character array, is less
than the record key of \xff\xff\xff\xff.
EXAMPLE |
#include <lcio.h> extern FILE *vsam; int findrec(void *key, void *rec) { int rc; char nearkey [20] ; rc = ksearch(key, 0, K_exact | K_noupdate, vsam); if (rc < 0) return rc; /* If error, return. */ if (rc > 0) { rc = kretrv(rec, NULL, K_noupdate, vsam); printf("Record %.20s found.\n", key); return rc; /* Return length of record. */ } printf("Record %.20s not found.\n", key); /* Search for greater key. */ rc = ksearch(key, 0, K_noupdate, vsam); if (rc < 0) return rc; if (rc == 0) /* no greater record */ puts("No record following this key."); else { rc = kretrv(rec, nearkey, K_noupdate, vsam); if (rc < 0) return rc; printf("Following record key: %.20s\n", nearkey); } /* Retrieve previous record. */ rc = kretrv(rec, nearkey, K_backwards | K_noupdate, vsam); if (rc < 0) return rc; if (rc == 0) /* no previous record */ puts("No record preceding this key."); else { rc = kretrv(rec, nearkey, K_backwards | K_noupdate, vsam); if (rc < 0) return rc; printf("Preceding record key: %.20s\n", nearkey); } return 0; /* Show record not found. */ }
RELATED FUNCTIONS |
SEE ALSO |
Chapter Contents |
Previous |
Next |
Top of Page |
Copyright © 2001 by SAS Institute Inc., Cary, NC, USA. All rights reserved.