Creating a New Database

The icreate_db function is called to create a new ISAM database. It requires three arguments, the name of the database (no extension necessary), the block size for the index file (DEFAULT_BLKSIZE specifies the default block size), and a list of field names. The list of field names is stored as an array of pointers to strings. The last element in the array must be NULL to indicate the end of the list.

The icreate_db function creates two files, a data file with the extension DB, and an index file with the extension IDX. The return value is a pointer to a database object of type Db_Obj. This is the handle that is subsequently passed to other ISAM functions to identify the database. A return value of NULL indicates that an error occurred in attempting to create the database.

The following example program creates a database named BOOKS. Each record in this database is able to store four string fields representing the author's first and last names, the title of the book, and the ISBN number for the book. This program creates two files, a data file named BOOKS.DB and an index file named BOOKS.IDX.

#include 
#include "isam.h"

int main()                      /* create.c */
{
    Db_Obj *db;
    char   *db_name = "BOOKS";
    char   *field_names[] = { "Author_First",
                              "Author_Last",
                              "Title",
                              "ISBN",
                               NULL };

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

    printf("Created database: %s\n", db_name);

    /* close ISAM database */
    iclose_db(db);
    return 0;
}

The ISAM function named iprterr is called to print an error message if an error occurs. Notice that the iprterr function is called only if the icreate_db function returns NULL.

The iclose_db function is called to close the database. Actually the database is automatically closed when the program terminates. However, it is good practice to explicitly close the database when processing is finished. Notice that the database object returned by the icreate_db function is passed to the iclose_db function to identify the database.