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

Name:       ifindrec

Purpose:    find a particular record via an index

Prototype:  int ifindrec(Db_Obj *db, Index_Obj *index, char *recfields[]);

Header:     isam.h

Inputs:     db          - database handle
            index       - index handle
            recfields   - array of pointers to strings for EACH field in rec

Description:
        ifindrec finds the particular record in the database named db
        via the indez that exactly matches (except for case) all of the
        record fields specified by recfields.  The file cursor (current
        record pointer) for the database is set to the found record.  Use
        igetrec to actually retrieve the record, or igetreclen to
        discover its length.

        The recfields is the record to search for.  It is the same format
        as the fields in the iaddrec routine; namely, an argv-style array
        of pointers to character strings.  Each string is the value of the
        corresponding field in the record.  The recfields array need not
        be terminated by NULL, though it won't hurt if it is.

        If there is no exactly matching record, ifindrec functions like
        ifindkey; that is, it leaves the current record pointer at the
        first record whose key matches the key fields from the recfields
        array (or the closest matching record).

        ifindrec operates faster if you have chosen keyfields for index
        properly.  If you have many records with the same key, ifindrec
        must look through all those matching records for the particular record
        that you specify.  If you choose your keyfields such that there are
        only one or a few records for each key value, ifindrec can move
        more rapidly to the specified record.  For example, if you have a
        mailing list database that is indexed on the state field, there will
        probably be many records with the same key value (say, dozens of
        records for "New York").  In this case, ifindrec must look through
        all of the matching ("New York") records for the specified record.  If,
        instead, you index on the zip code field, or use a compound key of
        last name and state, there will only be a few records that match any
        particular key, so that ifindrec can operate much faster.

        Use ifindkey instead if you wish to find the first record that
        matches a key, rather than matching all the fields in the record.

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

Returns:
        Returns FOUND if an exactly matching record (except for case) is found,
        and sets the current record pointer to that record.  Returns NOTFOUND
        if an exactly matching record is NOT found, and sets the current
        record pointer to the first record that has the same (or closest
        matching) key.  Returns ERROR for error.