Finding Records

Many of the ISAM functions perform operations relative to a particular index. Therefore an index handle must be passed to the function to identify which index to use. The ihandle function is called to get the handle for an index. It requires a single argument, the name of the index. The return value is an index handle if successful, or NULL if an error occurs.

The ifindkey function is called to find a record matching a particular key value. It requires three arguments, the database handle, the index handle, and the key value. The key value is a list of values for the fields that comprise the index. In the case of the "Author_Index", the key value is the author's last name followed by the first name. The ifindkey function returns I_FOUND if a record matching the key is found, I_NOTFOUND if a matching record is not found, or I_ERROR if an error occurs. If the record is found, then it becomes the current record for the specified index.

The following example program attempts to find a record in the BOOKS database that matches a specified author's name. If the record is found, it becomes the current record for the "Author_Index". The igetrec function is then called to read the current record. It requires four arguments, the database handle, the index handle, an array of pointers that igetrec initializes to point to the field values, a buffer where igetrec stores the actual field values, and finally the size of the buffer. The array of pointers to field values must be one greater than the number of fields in each record. The igetrec function initializes the last field pointer to NULL to indicate the end of the list of field values. The return value is I_OK if the record is successfully read.

#include 
#include "isam.h"

char author_first[80], author_last[80];
char *author_key[2] = { author_last, author_first };

int main()                      /* find.c */
{
    Db_Obj    *db;
    Index_Obj *author_idx;
    char      *db_name = "BOOKS";
    char      buffer[500];
    char      *field[5];

    /* open existing ISAM database */
    if ((db = iopen_db(db_name)) == NULL) {
        printf("Unable to open database: %s\n", db_name);
        iprterr();
        return -1;
    }

    /* get handle for author's name index */
    if ((author_idx = ihandle(db, "Author_Index")) == NULL) {
        printf("Unable to get handle for Author_Index\n");
        iprterr();
        return -1;
    }

    /* check to see if database is empty */
    if (ifindhead(db, author_idx) != I_OK) {
        printf("%s database contains no records\n", db_name);
        return 0;
    }

    /* show database records in order of author index */
    printf("%s database contains the following records\n", db_name);
    showdb(db, author_idx, "|");

    /* collect author data */
    printf("\nEnter author's first name: ");
    gets(author_first);
    printf("Enter author's last name: ");
    gets(author_last);

    /* find record matching key (author's name) in ISAM database */
    if (ifindkey(db, author_idx, author_key) != I_FOUND) {
        printf("%s %s is not in the database\n",
                  author_first, author_last);
        return 0;
    }
    printf("Record Found\n");

    /* get current record from ISAM database */
    if (igetrec(db, author_idx, field, buffer, sizeof(buffer)) != I_OK) {
        printf("Unable to read current record\n");
        iprterr();
        return -1;
    }

    /* print contents of current record */
    printf("\tAuthor: %s %s\n"
           "\tTitle : %s\n"
           "\tISBN  : %s\n",
            field[0], field[1], field[2], field[3]);

    /* close ISAM database */
    iclose_db(db);

    return 0;
}

Notice that the ifindhead function is called to find the first record in the database, as ordered by the author index. If the return value of ifindhead is not I_OK, it is assumed that the database is empty. If the database is not empty, the showdb function is called to display the field values of each record in the database.