|
|
|
In order for your application function with the FairCom DB libraries, and to take advantage of various FairCom DB #defines, at the top of each application you must have the following include statement:
#include "ctreep.h"
|
|
|
InitCTree
The first step needed is to initialize the FairCom DB system. This is done with a call to InitCTree(). Along with other operations, this function allocates memory for buffers and files. This function requires three parameters; the number of index buffers, the number of data and index files, and the number of node sectors.
The number of buffers to enter depends on several factors. First, if you are running a Standalone Multi-user system, you should only enter 6. More will not help, unless you have important read-only indexes. For single user or FairCom Server systems, reasonable speed is achieved with 6 buffers for each active index. The second parameter is the number of data files and indexes open at any given time. The most common value for the third parameter is four. This parameter is covered in detail in the InitCTree() description in the function reference section.
OpenCtFile, CreateDataFile, and CreateIndexFile
Once FairCom DB has been initialized, open the data files and indexes. Use OpenCtFile() to open an already existing data or index file, one call for each data file and each index. If the data file or index does not exist, you must use either CreateDataFile() for data files, or CreateIndexFile() for index files, to create them
|
|
|
If the user wants to add a record, we must first see if the key already exists, (unless you want to allow duplicate keys), then we need to add the key and write the record.
GetKey
First, look to see if the key exists by using GetKey(). This function returns the record offset associated with the key if it is in the index file. If GetKey() returns a record offset, we must tell the user that they cannot add it again.
NewData
To add a record to a data file, we must ask FairCom DB for the next available data record. This can be a record added to the end of the file or a previously deleted record. FairCom DB tracks of records returned to the data file and reuses deleted space before automatically extending the file. On each call to NewData() to get a record, c‑tree looks to see if there is a deleted record to use before extending the file.
WriteData
Once we have a data record offset, we can actually place the data in the file with WriteData().
AddKey
This function is used to add the key to the index file. Do this after writing the record for two reasons. First, AddKey() must know what the record offset to associate with this key. Second, to be sure that the data record can actually be written before putting the key into the index.
It is important to pad the key to its full length, so it can easily be found later. For instance, if the key length is 25 characters, but AddKey() receives a null terminated string shorter than 25 characters, the key may be corrupted. AddKey() adds 25 characters to the index including undefined characters after the null. Since the characters after the null are unknown, there is no way to make an exact match later.
|
|
|
To find a record, look for the key in the index and read the associated data record. In this simple example, we look for an exact match of the key entered by the user. More sophisticated searches can use partial keys, or scan up and down through the index.
GetKey
GetKey() looks for an exact match of the key, returning the record offset if the key is found. Remember that the key must be perfectly formed for an exact match. This usually means that it must be padded the same way that the key was when it was entered into the index.
ReadData
Once the key has been found, use ReadData() to read the associated data record.
|
|
|
DeleteKeyBlind and DeleteKey
Two functions delete a key, DeleteKeyBlind() and DeleteKey(). DeleteKeyBlind() requires only the key to delete. DeleteKey() also asks for the associated record offset. If you are allowing duplicate keys, you must use DeleteKey().
ReleaseData
Once the key has been deleted from the index, you will want to delete the data record. ReleaseData() marks a data record as deleted, making the record is available for reuse by a subsequent call to NewData().
|
|
|
When the application prepares 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.
CloseCtFile
Call CloseCtFile() for every open data file and index.
