To introduce you to FairCom DB low-level functions, we are going to build a very simple application. A listing of this application can be found on your distribution disk in lowlevel.c. In this chapter, we will present an outline of the program. Following the application, we will review other available low-level functions.
Full explanations of each function can be found in the FairCom DB Function Reference Guide, along with brief examples of how to use them.
Simple Application
We will start with a simple file maintenance application with a single data file and a single index file. The records are fixed-length, and we will not allow duplicate keys.
Application Outline
An outline of our application would be:
- Initialize the file system
- Ask if the user wants to Add or Delete a record
- When done, close the file system
The Application
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"
Initialize FairCom DB
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
Add a record
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.
Find a record
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.
Delete a 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().
Close the system
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.
Low Level API Example
An example demonstrating the basic use of the FairCom Low-Level C API can be fund in the FairCom Low-Level area of your FairCom DB installation located at drivers\c.lowlevel\tutorials.
Introductory Tutorial
<faircom>\drivers\c.lowlevel\tutorials\lowlevel.c
This tutorial will take you through the basic use of the FairCom Low-Level C API.
It is a sample program provided to show you how to use FairCom Low-Level functions. The application is a very simple one; creating and updating a simple database.
The key is a single segment, no duplicates are allowed. The data input functions are extremely simple, and do little or no error checking.
If any value is passed on the command line, this program assumes that you want to create the database. Otherwise it assumes that the database has already been created.
Note: This tutorial uses a function, "toupper", which is not found in all C compilers. It translates any lower case letter into an upper case letter.
Tutorial #1: Introductory - Simple Single Table
The tutorial begins with some basics, such as includes and #defines. You can refer to the source code to see that in detail.
Note our simple main program:
#ifdef PROTOTYPE
NINT main (NINT argc,pTEXT argv[])
#else
NINT main (argc,argv)
NINT argc;
pTEXT argv[];
#endif
{
#ifdef PROTOTYPE
VOID db_create(void), db_init(void), database(void), db_close(void);
#else
VOID db_create(), db_init(), database(), db_close();
#endif
#ifdef ctPortMAC
argc = ccommand(&argv);
#endif
#ifdef ctThrds
{
NINT err;
if ((err = ctThrdInit(2,(LONG) 0, (pctINIT)0))) {
ctrt_printf("\nctThrdInit failed. Error={%d}\n", err);
fflush(stdout);
ctrt_exit(1);
}
}
#endif
Some simple error handling is provided by these functions:
/*********************************************************
* *
* terminate: if an error occurs in a place *
* where we should terminate the program, *
* call this function. *
* *
* You may wish to have a more *
* sophisticated error routine that will *
* look at the error code and give the user *
* more information. *
* *
**********************************************************/
#ifdef PROTOTYPE
VOID terminate(pTEXT termsg,COUNT fil)
#else
VOID terminate(termsg,fil)
pTEXT termsg;
COUNT fil;
#endif
{
printf("\n\n%s",termsg);
func_error(fil);
/* Call the routine that will give you *
* a meaningful message */
STPUSR();
/* This is needed to shut the user down *
* if you are using a file server. If *
* you aren't, it is a good idea to *
* include since it will free up c-tree *
* PLUS(tm)'s memory allocations. */
fflush(stdout);
ctrt_exit(1);
}
/********************************************************
* *
* func_error: A simple error message handler. You can *
* add other error conditions as you need. *
* *
********************************************************/
#ifdef PROTOTYPE
VOID func_error(COUNT fil)
#else
VOID func_error(fil)
COUNT fil;
#endif
{
switch (uerr_cod)
{
case NO_ERROR:
break; /* no error occured, so return */
case DLOK_ERR:
printf("\nCouldn't get lock on record");
break;
case FNOP_ERR:
printf("\nCould not open file %d",fil);
printf("\nIf the files do not exist, you need to create them.");
printf("\nTo do so, type in \"lowlevel create\" on the command line.");
break;
case KCRAT_ERR:
case DCRAT_ERR:
printf("\nCould not create file [%d]",fil);
break;
case KOPN_ERR:
case DOPN_ERR:
printf("\nTried to create existing file [%d]",fil);
break;
case KDUP_ERR:
printf("\nKey already in index");
break;
case FUNK_ERR:
case FCRP_ERR:
printf("\nHeader record of file %d is damaged",fil);
break;
case SEEK_ERR:
case WRITE_ERR:
case READ_ERR:
printf("\nFailure while trying to read or write record");
break;
case DADV_ERR:
printf("\nServer did not find proper lock");
break;
case UDLK_ERR:
printf("\nCannot unlock data record");
break;
default:
printf("\nError %d on file %d",uerr_cod,fil);
break;
} /* end switch */
}
Init
Below is the code to "Initialize" FairCom DB:
/* Initialize the c-tree system */
if (InitCTreeXtd(10,2,4,10,USERPRF_NTKEY,"admin","ADMIN","FAIRCOMS"))
terminate("Could not initialize c-tree",-1);
if (argc > 1)
db_create(); /* create the database files */
db_init(); /* open the database files that are already created */
database(); /* perform database routines */
db_close(); /* close the files, and any other ending stuff */
fflush(stdout);
return(0); /* dummy to remove compiler warning */
}
/********************************************************
* *
* db_init: Open the data files and indices. They *
* must have been already created. Most of *
* the important parameters for the files *
* are set when the file was created. *
* *
********************************************************/
#ifdef PROTOTYPE
VOID db_init(void)
#else
VOID db_init()
#endif
{
/* Open the data file */
if (OpenCtFile(INVENTDAT,"invent.dat",ctVIRTUAL|ctSHARED)) {
db_create();
if (OpenCtFile(INVENTDAT,"invent.dat",ctVIRTUAL|ctSHARED))
terminate("Could not open invent.dat",INVENTDAT);
}
/* Open the index file */
if (OpenCtFile(INVENTIDX,"invent.idx",ctVIRTUAL|ctSHARED))
terminate("Could not open invent.idx",INVENTIDX);
return;
}
Create
Below is the code where specific data definitions are established by your application and/or process. With this code, you will "Create" columns/fields and creating the tables/files with optional indexes:
/********************************************************
* *
* db_create: creates the data files and indexes. *
* If any of the files already exist there *
* will be an error. The files are closed *
* so all intended file modes take effect. *
* *
********************************************************/
#ifdef PROTOTYPE
VOID db_create(void)
#else
VOID db_create()
#endif
{
/* Create the data file */
if (CreateDataFile(INVENTDAT,"invent.dat",sizeof(invent),4096,ctVIRTUAL|ctSHARED|ctFIXED))
terminate("Could not create invent.dat",INVENTDAT);
/* the second parameter is no longer used */
if (CloseCtFile(INVENTDAT,0))
terminate("Could not close invent.dat after creation",INVENTDAT);
/* Create the index file */
if (CreateIndexFile(INVENTIDX,"invent.idx",25,0,0,0,4096,ctVIRTUAL|ctSHARED))
terminate("Could not create invent.idx",INVENTIDX);
if (CloseCtFile(INVENTIDX,0))
terminate("Could not close invent.idx after creation",INVENTIDX);
printf("\nSuccessfully created data files and indices");
return;
}
Manage
The database() function includes a loop that asks if you want to add a new record, delete an existing record, or quit. The other functions implement various data management functions: datadd(), transkey(), getfld(), and datdel().
Below is the code for the "Manage" functions, database(), datadd(), transkey(), getfld(), and datdel():
/********************************************************
* *
* database: This is the main action function. *
* *
********************************************************/
#ifdef PROTOTYPE
VOID database(void)
#else
VOID database()
#endif
{
TEXT choice[2];
#ifdef PROTOTYPE
VOID datadd(void), datdel(void);
#else
VOID datadd(), datdel();
#endif
choice[0] = '\0';
while (choice[0] != 'Q')
{
printf("\n\nA)dd D)elete Q)uit:");
fflush(stdout);
ctsfill(inpbuf,0,INPBUFSIZ);
if (!ctrt_fgets(inpbuf, sizeof(inpbuf), stdin))
inpbuf[0] = 'Q';
choice[0] = (TEXT)toupper((NINT)inpbuf[0]);
switch (choice[0])
{
case 'A':
datadd(); /* add new entry to database */
break;
case 'D':
datdel(); /* delete existing entries */
break;
default:
break;
} /* end switch */
} /* end while */
}
/********************************************************
* *
* dataadd: Add a new record *
* *
********************************************************/
#ifdef PROTOTYPE
VOID datadd(void)
#else
VOID datadd()
#endif
{
printf("\nADD NEW DATA\n\n");
/* Initialize the new record so that all fields are blank */
invent.delete_flag[0] = '\0';
invent.delete_flag[1] = '\0';
invent.item[0] = '\0';
invent.descrip[0] = '\0';
invent.location[0] = '\0';
invent.quantity = 0.0;
invent.cost = 0.0;
getfld(); /* acquire new item info */
transkey(keyfld,invent.item,sizeof(invent.item)); /* prepare key for use */
/* Look to see if this key is already *
* in the file. */
if (GetKey(INVENTIDX,keyfld))
{
printf("\nKey already in file, cannot add");
return;
}
if (uerr_cod) /* Check for error in EQLKEY call*/
{
func_error(INVENTIDX);
return;
}
/* Get data record from data file */
if ((datarec = NewData(INVENTDAT)) == 0)
/* assignment intended */
{
func_error(INVENTDAT);
return;
}
/* Write data record to data file */
if (WriteData(INVENTDAT,datarec,&invent))
{
func_error(INVENTDAT);
ReleaseData(INVENTDAT,datarec);
/* if we cannot write to *
* the record, we will *
* return the record to *
* the pool. */
LockCtData(INVENTDAT,ctFREE,datarec);
/* NewData puts a lock on *
* the record automatically*
* that we must free */
return;
}
/* Add key to the index, now that we know*
* that we have successfully added the *
* record to the data file. */
if (AddKey(INVENTIDX,keyfld,datarec,REGADD))
{
func_error(INVENTIDX);
ReleaseData(INVENTDAT,datarec);
/* If cannot add key, *
* then return the record.*/
LockCtData(INVENTDAT,ctFREE,datarec);
/* NewData puts a lock on *
* the record automatically*
* that we must free */
return;
}
printf("\nSuccessful Addition");
LockCtData(INVENTDAT,ctFREE,datarec);
/* release the lock that NewData placed*/
return;
}
/**********************************************************
* *
* transkey: The key field must be properly formatted *
* by us, as c-tree does not format it *
* automatically with low level functions. *
* We are going to do two things to the *
* key. First, we will translate all of the *
* alpha characters to upper case. Second, *
* we will pad the key to its full length. *
* This second part is very critical! c-tree *
* looks at the entire buffer when comparing *
* keys, and if you have garbage after a *
* null terminated string in a key buffer, *
* that becomes a part of the key! *
* *
***********************************************************/
#ifdef PROTOTYPE
VOID transkey(pTEXT dest,pTEXT source,NINT len)
#else
VOID transkey(dest,source,len)
pTEXT dest,source;
NINT len;
#endif
{
TEXT ch;
len--;
/* loop until field filled or null found,
* translating any lower case to upper case */
while(*source && len-- > 0)
{
ch = *source++;
*dest++ = (TEXT)toupper((NINT)ch);
}
/* fill the rest of the field with nulls, if needed */
while(len-- > 0)
*dest++ = '\0';
*dest = '\0';
}
/********************************************************
* *
* getfld: enter input information *
* *
********************************************************/
#ifdef PROTOTYPE
VOID getfld(void)
#else
VOID getfld()
#endif
{
printf("\nEnter Item ID: ");
fflush(stdout);
ctsfill(inpbuf,0,INPBUFSIZ);
ctrt_fgets(inpbuf, sizeof(inpbuf), stdin);
if (inpbuf[0] != '\0')
cpybuf(invent.item,inpbuf,sizeof(invent.item));
printf("\nEnter Description: ");
fflush(stdout);
ctsfill(inpbuf,0,INPBUFSIZ);
ctrt_fgets(inpbuf, sizeof(inpbuf), stdin);
if (inpbuf[0] != '\0')
cpybuf(invent.descrip,inpbuf,sizeof(invent.descrip));
printf("\nEnter Location: ");
fflush(stdout);
ctsfill(inpbuf,0,INPBUFSIZ);
ctrt_fgets(inpbuf, sizeof(inpbuf), stdin);
if (inpbuf[0] != '\0')
cpybuf(invent.location,inpbuf,sizeof(invent.location));
printf("\nEnter Quantity: ");
fflush(stdout);
ctsfill(inpbuf,0,INPBUFSIZ);
ctrt_fgets(inpbuf, sizeof(inpbuf), stdin);
if (inpbuf[0] != '\0')
sscanf(inpbuf,"%lf",&invent.quantity);
printf("\nEnter Cost: ");
fflush(stdout);
ctsfill(inpbuf,0,INPBUFSIZ);
ctrt_fgets(inpbuf, sizeof(inpbuf), stdin);
if (inpbuf[0] != '\0')
sscanf(inpbuf,"%lf",&invent.cost);
}
/********************************************************
* *
* datdel: find and delete record *
* *
********************************************************/
#ifdef PROTOTYPE
VOID datdel(void)
#else
VOID datdel()
#endif
{
printf("\nDELETE DATA\n");
printf("\nEnter Item to Delete:");
fflush(stdout);
ctsfill(inpbuf,0,INPBUFSIZ);
ctrt_fgets(inpbuf, sizeof(inpbuf), stdin);
transkey(keyfld,inpbuf,sizeof(invent.item));
/* Prepare key for use. It is important to form
* this key in the same way as we do keys to be added,
* since we will be looking for an exact match
*/
/* find the key to delete in index */
if (!(datarec = GetKey(INVENTIDX,keyfld)))
{
if (uerr_cod)
func_error(INVENTIDX);
else
printf("\nKey not found");
return;
}
/* read the record to display */
if (ReadData(INVENTDAT,datarec,&invent))
func_error(INVENTDAT);
else
{
printf("\n\nItem %s",invent.item);
printf("\nDescription %s",invent.descrip);
printf("\nLocation %s",invent.location);
printf("\nQuantity %f",invent.quantity);
printf("\nCost %f",invent.cost);
}
/* Delete the key from index */
if (DeleteKey(INVENTIDX,keyfld,datarec))
{
printf("\n\nKey delete failed (code %d).",uerr_cod);
return;
}
/* Return the data record to pool */
if (ReleaseData(INVENTDAT,datarec))
printf("\n\nData record delete failed (code %d).",uerr_cod);
else
printf("\n\nDelete Successful");
}
Done
When an application and/or process has completed operations with the database, it must release resources by closing the open files
Below is the code for db_close():
/********************************************************
* *
* db_close: close the data files and indexes. *
* *
********************************************************/
#ifdef PROTOTYPE
VOID db_close(void)
#else
VOID db_close()
#endif
{
if (CloseCtFile(INVENTDAT,0)) /* the second parameter is no longer used*/
func_error(INVENTDAT);
if (CloseCtFile(INVENTIDX,0))
func_error(INVENTIDX);
StopUser(); /* Terminate this user with server and/or free-up
* c-tree PLUS(tm) memory allocations.
* You can include this even if you are
* not sure if you will be using the server.
*/
fflush(stdout);
ctrt_exit(0);
}
Additional Resources
We encourage you to explore the additional resources listed here:
- Complete source code for this tutorial can be found in lowlevel.c in your installation directory, within the <faircom>\drivers\c.lowlevel\tutorials directory for your platform.
- Additional documentation may be found on the FairCom Web site.
Low-Level Function Overview
Some of the low-level functions, those with return type COUNT, return an error code value. A zero error code indicates success. The rest of the index file functions, those with return type LONG, return a data record position. A zero data record position indicates an error. Each low-level function sets the value of a global error code variable: uerr_cod.
Several of the functions listed here have two versions - a standard version and an extended version. The extended version has the same name as the standard version, with a suffix of Xtd. The extended version provides access to the security features of the FairCom Server.
System Functions
InitCTree and InitCTreeXtd
This function must be called before using any FairCom DB functions, unless you are using ISAM functions, which require a different initialization function. It initializes the FairCom DB buffers for the number of files that you are going to use. If you are using the FairCom Server, it also logs you on to the Server.
StopUser
If you are using the FairCom Server, and you are not using the ISAM functions, you must call StopUser() when you are finished using the Server, typically just before you exit the application. If you are not using a Server, this function is ignored.
File Manipulation Functions
CloseCtFile
Use this to close a data or index file when you are finished with it. It is important to close any file if it has been updated. If you do not close an updated file when your application terminates, the file will be damaged.
CreateDataFile and CreateDataFileXtd
Creates a data file. Sets characteristics of the data file, such as record length and file mode.
CreateIndexFile and CreateIndexFileXtd
Creates an index file. The characteristics of the index file are set at this time, such as the key length.
CreateIndexMember
Establishes additional indexes within an existing index file. Any physical index file can contain multiple logical indexes. While there is only one file on the disk, it can look to your program as if it is several separate indexes.
DeleteCtFile
Deletes a specified file. Use instead of a C language function, such as unlink(). When using the FairCom Server the application may not have direct access to the file.
GetCtTempFileName
Creates a file name that is guaranteed to by unique.
GetCtFileInfo
This function returns information from the data file or index header record.
GetSymbolicNames
Returns symbolic information from the file, such as the file name.
OpenCtFile and OpenCtFileXtd
Use to open a data or index file created with CreateDataFile() or CreateIndexFile().
UpdateFileMode
This function changes critical file mode attributes.
Security
Use this function to change a password, Group ID, or permission mask of a file.
AvailableFileNbr
Returns the next available FairCom DB file number.
Data Record Manipulation
NbrOfRecords
Get the number of active records in a fixed length data file.
VDataLength
This function returns the length of a variable-length data record.
LockCtData
Locks and unlocks data records.
NewData
Returns the next available record position in a fixed-length data file.
NewVData
Returns the next available record position in a variable-length data file.
ReadData
Use to read a fixed-length data record.
ReadVData
Read a variable-length data record. Use VDataLength() before calling ReadVData() to ensure the buffer is large enough to hold the record.
ReleaseData
Deletes a fixed-length record from a data file, making it available for use by the next call to NewData().
ReleaseVData
Deletes a variable-length data record from a data file, making it available for use by the next call to NewVData().
WriteData
Writes a fixed-length data record to the file.
WriteVData
Writes a variable-length data record to the file.
Key Manipulation
AddKey
Add a key value to an index.
TransformSegment
Performs key value transformations similar to the ISAM function TransformKey().
DeleteKey
Deletes a key value from an index. You must pass DeleteKey() the proper data record position for success.
DeleteKeyBlind
Deletes a key value from an index, but does not require the data record number.
GetKey
Search the index for an exact match of the given key. Do not use with indexes allowing duplicate keys.
EstimateKeySpan
This function finds the approximate number of entries between two key values.
KeyAtPercentile
Find the key value located approximately at the percentile specified.
FirstKey
Find the first key in the specified index.
GetGTEKey
Find a key that is equal to or greater than the target key.
GetGTKey
Find the first key that follows the target key.
NbrOfKeyEntries
Get the number of entries in an index file.
LoadKey
Build an index with multiple key values when the key values are in sorted order. It works faster than AddKey(), but has some restrictions.
LastKey
Find the last key in the index.
GetLTEKey
Find a key that precedes or equals the target key.
GetLTKey
Find a key that precedes the target key.
NextKey
Find the next key in the index, relative to the last key search.
PreviousKey
Find the previous key in the index, relative to the last key search.
Transaction Processing Functions
Using the FairCom Server or FairCom DB single-user mode there are a number of functions to perform transaction processing. In standard multi-user mode, they are ignored. See Data Integrity for information on transaction processing.
Abort
Aborts an in-progress transaction, releasing all locks.
Begin
Begin a transaction. This must be followed by Commit() to complete the transaction.
Commit
Commit the transaction started with a Begin().
RestoreSavePoint
Undo operations back to a specified savepoint created by SetSavePoint().
SetSavePoint
Establishes a savepoint. Provides a partial undo capability with RestoreSavePoint().
ClearTranError
Clears the transaction error flag set if there was an error in an update function. This allows Commit() to complete successfully. Use with extreme caution.
Resource Functions
A Resource is auxiliary information stored in a file that is transparent to the regular processing of the file. Resources store version information, counters, or any information that is not part of the regular data records. Resource functions work in all modes of operations.
AddCtResource
Adds a Resource to a data file.
DeleteCtResource
Deletes a Resource from a data file.
EnableCtResource
Enables Resources in a file created without Resources enabled.
GetAltSequence
Retrieve a stored alternate collating sequence.
GetDODA
Retrieve DODA and record schema information stored in a file as a Resource.
GetCtResource
Retrieve Resource information from a data file.
PutDODA
Store a DODA in a file as a Resource.
SetAlternateSequence
Define an alternate collating sequence for a file, stored as a resource.
SetVariableBytes
Change the value for the Padding character and Field Delimiter for a file.
UpdateCtResource
Updates Resource information in a data file.
Data Integrity Verification Function
ctVERIFYidx
The FairCom Server version of the ctVERIFY() function, which can be called by a client or in standalone mode to check the integrity of an index file.