SAS/C Library Reference, Vol. 1

ksearch -- Search Keyed File for Matching Record

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: specifies that a matching record must match the requested key exactly (up to 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: indicates that the search is to be performed in descending key order rather than ascending key order.
K_noupdate: indicates that the program does not attempt to replace or delete records located by the search. You can override this option by a later call to 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,

A full key-forward search without K_exact sets positions to the end of file.
A full key-backward search without K_exact sets positions to the start of file.
A full-key search with K_exact sets positions to the first record after the specified key.
A generic-key search with K_exact sets positions to the first record whose partial key follows the generic key.

RETURN VALUES

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

This example locates a record in a VSAM file with a specific key. If the record is not found, it determines the next and previous records and prints their keys. The example function returns 0 if no record is found, or a negative value if an error occurs:

  #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: %.20sn", 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: %.20sn", nearkey);
     }
     return 0;                      /* Show record not found.   */
  }

RELATED FUNCTIONS

kretrv, kseek