|
|
|
We use a simple file maintenance application as an example, as we did with the low-level functions. The records are fixed-length, and do not allow duplicate keys. The complete source code for this simple application can be found in isam.c. It is explained in more detail in the Sample Applications chapter. We will just outline the application here.
Outline
As with the low-level functions, the outline of our application is:
ISAM Parameters
The characteristics of the data files and indices used in your application program can be defined in two different ways, either with ISAM structures defined in your application or with an ISAM Parameter File (the ISAM Parameter File is considered legacy).
The ISAM structures specify the layout of each data file and its associated indices in a set of structures in your application. Data and index files are created or opened with CreateIFile(), OpenIFile(), and OpenFileWithResource().
The ISAM Parameter File is a simple ASCII file created with a text editor. It contains records specifying the characteristics of all data files, indices, and keys for an application. OpenISAM() and CreateISAM() use this file to initialize the system. These files are considered legacy.
Initially, we will discuss using ISAM structures, also referred to as Incremental ISAM structures. Later we will discuss the use of ISAM Parameter Files. Although both methods are covered in detail, FairCom recommends using the ISAM Structures. This method provides individual file open, close, and rebuild control, and offers advanced features not available with the ISAM Parameter File, such as file definitions automatically stored at file creation time. This capability is recommended for use with the FairCom Drivers and will be required in some future FairCom R&D projects.
|
|
|
For your application to function with the c-tree libraries, and to take advantage of various c-tree #defines, at the top of each application you must have the following include statement:
#include "ctreep.h"
|
|
|
The first three functions, InitISAM(), CreateIFile(), and OpenIFile(), are specific to ISAM Structures.
InitISAM
The first step is initializing the c-tree system with InitISAM(), which allocates memory for buffers and files.
CreateFile
If the data files and indexes do not already exist, use CreateIFile() to create each data file and its associated indexes.
OpenFile
If the data files and indexes already exist, use OpenIFile() to open each data file and its associated indexes.
Note: This function supports EXCLUSIVE file opens. For more information, please refer to Multi-user File Mode.
The next two functions, OpenISAM() and CreateISAM(), are specific to ISAM Parameter Files (legacy).
OpenISAM
The first step needed is to initialize the c-tree system. This is done with a call to OpenISAM(). This takes the information stored in the ISAM Parameter File, allocates memory for buffers and files, and opens all of the data files and indexes.
Note: This function supports EXCLUSIVE file opens. For more information, please refer to Multi-user File Mode.
CreateISAM
If the data files and indexes do not already exist, use CreateISAM() to create them.
The remaining functions in this section work with both Incremental Structures and ISAM Parameter Files (legacy).
|
|
|
AddRecord
In the low-level function example we had to call three functions to add a record to the file system; NewData() to get the data record, WriteData() to write the record, and AddKey() to add the key to the index. With the ISAM functions, the process is much simpler. All that is needed is a call to AddRecord(). This performs all of the functions necessary to add the record and key.
|
|
|
GetRecord
To find a key and read the associated record into our application we simply make a call to GetRecord(). This function finds the match to the key and reads the record into your data buffer. More sophisticated searches can be done for partial keys, or scanning up and down through the index.
|
|
|
DeleteRecord
This function will delete a record from the data file, and its key from the index. The record deleted is the current ISAM record, defined later in this chapter.
|
|
|
When the application is ready to exit, it should close the data files and indexes. If not, and records or keys were added or deleted, the files will be damaged. Closing the files updates the header information to the file.
CloseISAM
This function only needs to be called once to close all open files. Every data file and index opened with an ISAM level open call, such as OpenIFile() or OpenFileWithResource(), will be closed with this one function call.
