Click above to get retro games delivered to your door ever month!

Name:       ifindkey

Purpose:    find first record that matches a key

Prototype:  int ifindkey (Db_Obj *db, Index_Obj *index, char *keyfields[]);

Header:     isam.h

Inputs:     db          - database handle
            index       - index handle
            keyfields   - array of pointers to keys which matches index fields

Description:
        ifindkey finds the first recordd in the database named db via the
        index that matches the key (except for case) that is specified in
        keyfields.  The file cursor (current record pointer) for the database
        for the database is set to this record.  Use igetrec to actually
        retrieve the record, or igetreclen to discover its length.

        If there are several records that exactly match the key, the current
        record pointer is set to the one that happens to appear first in the
        database.  If there is no record that exactly matches the key, the
        current record pointer is set to the record that follows the place
        where the desired record would be.

        The keyfields array specifies the key to be search for.  It is an
        argv-style array of pointers to character strings.  The array need not
        be terminated by a NULL, but it won't hurt if it is.  Each element is
        the value of a key field.  For example, if an index is keyed on the
        fields "Zip" and "Name", the keyfields array would be two elements
        long and the values might be "99999" and "Jones".

        Use ifindrec instead if you wish to find a particular record.

        ifindkey is not implemented for the Physical Index.  It is an error
        to call ifindkey for the Physical Index.

Returns:
        Returns FOUND if an exactly matching key (except for case) is found,
        and sets the current record to that record.  Returns NOTFOUND if an
        exact match is NOT found, and sets the current record to the closest
        match.  Returns ERROR for error.
Example:
/* assumes existing database named "phonbook"; see EXAMPLE for icreate_db */

#include    "isam.h"

char    *key[] = {
        "Anna"
};

int main()
{
    Db_Obj      *phone_db;
    Index_Obj   *name_index;
    int         status;

    phone_db = iopen_db("phonbook");
    if (phone_db != NULL) {
        name_index = ihandle(phone_db, "name");
        status = ifindkey(phone_db, name_index, key);
        if (status == FOUND)
            printf("Found a matching key for Anna\n");
        else if (status == NOTFOUND)
            printf("No matching key for Anna\n");
        else
            iprterr();

        iclose_db(phone_db);
    }
}