Each FairCom DB function has two names: the full name and the abbreviated name. Full names are used throughout this manual, and describe the action the function performs. The abbreviated name is generally shorter and more cryptic. You will see it if you examine the FairCom DB source code. Prior versions of the c‑tree File Handler used the abbreviated names. If you have a program that worked with older versions of c‑tree, you will not have to change the function calls to the full names. Also included in the table is the function’s API group and a table of API groups.

Four Byte File Numbering TypeDef Change

FairCom V12 and later servers support opening more than 32,767 files. This enhancement has been designed so no application changes should be required. Each individual database connection is still limited to a maximum of 32,767 files (preserving the original definition of data and index file numbers as two-byte signed values, using the COUNT data type). Internally, a new four byte typedef was introduced supporting up to 2 billion files. Note that there is a compile-time limit of 1,000,000 files to reduce the memory footprint of the c-tree database engine. If you need more than 1,000,000 open files, please contact FairCom.

However, if opening many files, consider the possibility of using multiple FairCom DB engines to host the files, rather than having one FairCom DB engine hosting all the files. This is recommended as files compete for resources such as data and index cache, file system cache, operating system kernel memory, and transaction logs.

New FILNO typedef

The data type FILNO replaces COUNT in all API functions that specify a FairCom DB file number as input or output. When code is compiled with #define ctFeatMAXFILE32, FILNO evaluates to a 4-byte value. When ctFeatMAXFILE32 is off, FILNO evaluates to a 2-byte value as before. Likewise, the IFIL structure's dfilno and tfilno fields become 4-byte values when ctFeatMAXFILE32 is defined.

In addition, the global state variable isam_fil remains a two byte value (COUNT). isam_fil32 holds the four byte value (FILNO) in case of errors.

See Also

Millions of Open Files

Full Names

This table lists the functions alphabetically by the Full Name.

Abbreviated (short) Names

This table lists the functions alphabetically by the Abbreviated Name.

Function API Listing

This section lists the FairCom DB Function API broken into functional groupings: Initialization, Definition, Manipulation, and Utility. Each of these groupings has sub-groups as described in the topics that follow.

Initialization API

The initialization API prepares the environment for FairCom DB operation. Included are the ctThrd, Instance Control, ISAM Initialization, and Low-Level Initialization APIs.

ctThrd API

The FairCom DB ctThrd API is a very thin overlay over the native threading API for each operating systems. Only systems without native threading use a FairCom DB proprietary threading API.

Instance Control API

Similar to the thread API but used only with single-thread models, Instance Control allows and controls multiple FairCom DB instances within a single application.

ISAM Initialization API

Used to initialize the ISAM level operation of FairCom DB.

Low-Level Initialization API

Used to initialize the Low-Level FairCom DB environment.

Data Definition API

Used to create and define tables and indexes. Divided into ISAM and Low-Level APIs.

ISAM Data Definition API

Used to create and define files for ISAM level use.

Low-Level Data Definition API

Used to create and define files for Low-Level use.

Data Manipulation API

Data manipulation functions are used to alter the contents of data and index files. This sections is divided into ISAM and Low-Level functions.

ISAM Data Manipulation API

ISAM Manipulation functions are divided into general, Batch, Context, and Set APIs.

Batch API

Manipulate batches of records in a single call.

Context API

Maintain separate positions in a file.

Sets API

Work with a specified subset of a table’s records.

Low-Level Data Manipulation API

Manipulate data and index files at the low level.

Utility Functions

The following functions provide capabilities that do not fit into the categories above. In addition to general utility functions, Server administration and Transaction Processing control functions are included here.

Data Integrity Verification

The following utility functions are used to verify the integrity of data and/or index files.

Server Administration API

The following utility functions are specific to Client/Server operation.

Transaction Processing API

The following utility functions control transaction processing.

File Copy Functions

The following functions are used for copying files between FairCom DB Servers.

API Functions Sorted by Type - ISAM Functions

The list below groups the ISAM functions according to the type of function.

General ISAM Functions

InitISAM - Initialize file structures and index buffer area.

InitISAMXtd - Initialize file structures and index buffer area (extended version).

LockISAM - Enable, free or suspend data record locks.

ReadIsamData - ISAM read data at record position.

ReadIsamVData - ISAM read variable-length data at record position.

TransformXtdSegment - Creates a binary sort key (segment) using an extended key segment definition.

Batch Operations

AllocateBatch - Allocates buffer space for multiple batches

ChangeBatch - Change current batch

DoBatch - Perform operations on a group of records.

DoBatchXtd - Perform operations on a group of records (extended version).

FreeBatch - Free space allocated for multiple batches (groups of records).

Context Functions

ChangeISAMContext - Change current ISAM context

CloseISAMContext - Close current ISAM context

OpenISAMContext - Opens (creates) an ISAM context.

File Functions

CloseCtFileByName - Close a memory file and remove it from memory

CloseISAM - Close all ISAM files

CurrentFileOffset - Returns the byte position, (file address or offset), of the current ISAM record for the specified file.

CompactIFile - Compresses a data file then rebuilds to regenerate the indexes

CompactIFileXtd - Compresses a data file, then rebuilds to regenerate the indexes.

CompactIFileXtd8 - Compresses a data file, then rebuilds to regenerate the indexes.

CreateISAM - Create all the ISAM files.

CreateISAMXtd - Extended ISAM file creation routine.

DeleteRFile - Delete ISAM file and associated indexes.

OpenISAM - Open all the ISAM files.

OpenISAMXtd - Open all the ISAM files (extended version).

History Functions

ChangeHistory - Change current history buffer

FreeHistory - Free space allocated for multiple history buffers.

IFile Functions

CloseIFile - Incremental ISAM close

CloseRFile - Incremental ISAM close for files opened by Resource IFIL open

CreateIFile - Incremental ISAM create.

CreateIFileXtd - Extended incremental ISAM creation.

CreateIFileXtd8 (CreateIFileXtd8, CreateIFileXtd8) - Extended 8-byte incremental ISAM creation.

DeleteIFile - Delete ISAM file and associated indexes.

GetIFile - Retrieve an IFIL structure from a data file

OpenIFile - Incremental ISAM open.

OpenFileWithResource - Incremental ISAM open, based on the IFIL Resource.

OpenFileWithResourceXtd - Incremental ISAM open, based on the IFIL Resource (extended).

OpenIFileXtd - Extended Incremental ISAM open.

PutIFile - Place an IFIL structure into a data file resource record.

PutIFileXtd - Place an IFIL structure into a data file resource record. (Extended version)

PutIFileXtd8 - Put an IFIL structure into a data file resource record. Extended 8-byte version.

RebuildIFile - Incremental ISAM rebuild.

RebuildIFileXtd - Extended Incremental ISAM rebuild.

RebuildIFileXtd8 - Extended 8-byte Incremental ISAM rebuild.

RenameIFile - Atomically rename some or all of the files associated with the IFIL structure.

RenameIFileXtd - Rename ISAM files, extended version.

Index Functions

DropIndex - Permanent Incremental Index deletion.

GetConditionalIndex (GetConditionalIndex, /doc/ctreeplus/getconditionalindex.htm) - Get the conditional index resource from a data file.

PermIIndex - Permanent Incremental Index creation.

PermIIndex8 - Permanent 8-byte Incremental Index creation.

RebuildIIndex - Rebuilds a single index.

TempIIndexXtd - Temporary Incremental Index creation.

TempIIndexXtd8 - Extended 8-byte temporary Incremental Index creation.

UpdateConditionalIndex (UpdateConditionalIndex, /doc/ctreeplus/updateconditionalindex.htm) - Update the Conditional Index Resource in a data file.

Key Functions

CurrentISAMKey - Create an ISAM key from the current ISAM record.

GetXtdKeySegmentDef (GetXtdKeySegmentDef, GetXtdKeySegmentDef) - ISAM data definition: Retrieves the requested extended key segment definition.

PutXtdKeySegmentDef (PutXtdKeySegmentDef, PutXtdKeySegmentDef) - Defines an extended key segment for a Server, an application, a data file, an index file, or a particular index segment.

TransformKey - Transforms an assembled key value according to the ISAM key segment mode

uTFRMKEY - Undo key segment translation to target key.

Notifications

ctCallback - Establish a notification callback.

ctNotify - Send notification messages to a queue.

Queue Management

ctSysQueueClose - Closes an existing queue.

ctSysQueueLIFOWrite - Add new data at the beginning of a queue.

ctSysQueueMlen - Retrieves the length of the next available message in the queue.

ctSysQueueOpen (ctSysQueueOpen, ctSysQueueOpen) - Open or create a new queue.

ctSysQueueRead - Read data from the queue.

ctSysQueueWrite - Add new data at the end of a queue.

Range Functions

AllocateRange - Establishes index range for ISAM record retrieval

EstimateRange - Find the approximate number of entries between two key values.

FirstInRange - Read the first data record in a range

FirstInVRange - Read the first data record in a range

FreeRange - Reset and free allocated buffers for range operation

LastInRange - Read the last data record in a range

LastInVRange - Read the last data record in a range

NextInRange - Read the next data record in a range

NextInVRange - Read the next data record in a range

PreviousInRange - Read the previous record in a range

PreviousInVRange - Read the previous record in a range

Records

AddRecord - Fixed-length record add

AddVRecord - Variable-length record add

BlockingISAMRead - Blocking record read

DeleteRecord - Delete current fixed-length ISAM record.

DeleteVRecord - Delete current variable-length ISAM record.

FirstRecord - Read the first data record.

FirstVRecord - Read the first variable-length data record.

GetGTERecord - Read the record with key greater than or equal to target.

GetGTEVRecord - Read the variable-length record with key greater than or equal to target.

GetGTRecord - Read the record with key greater than target.

GetGTVRecord - Read the variable-length record with key greater than target.

GetLTERecord - Read the record with key less than or equal to target.

GetLTEVRecord - Read the variable-length record with key less than or equal to target.

GetLTRecord - Read the record with key less than target.

GetLTVRecord - Read the variable-length record with a key less than target.

GetRecord - Get data record with key equal to target value.

GetVRecord - Read the variable-length record with a key equal to target.

LastRecord - Read the last data record.

LastVRecord - Read the last variable-length data record.

NextRecord - Read the next data record.

NextVRecord - Read the next variable-length data record in the data file.

PreviousRecord - Read the preceding data record.

PreviousVRecord - Read the previous variable-length data record in the data file.

ReReadRecord - Reread current ISAM record.

ReReadVRecord - Reread variable-length ISAM data record.

ResetRecord - Updates the current ISAM record image buffers.

ReWriteRecord - Rewrite current fixed-length ISAM record.

ReWriteVRecord - Rewrite current variable-length ISAM record.

SetRecord - Resets the current ISAM record.

VRecordLength - Get length of current variable-length ISAM record.

Sets

AllocateSet - Allocates buffer space for multiple sets

ChangeSet - Change current set

FirstInSet - Read the first data record in the set defined by target.

FirstInVSet - Read the first variable-length data record in the set defined by target.

FreeSet - Free space allocated for multiple sets.

LastInSet - Read the last data record in the set defined by a target.

LastInVSet - Read the last variable-length data record in the set defined by target.

NextInSet - Read the next data record in the set defined by target.

NextInVSet - Read the next variable-length data record in the set defined by target.

PositionSet - Establish current ISAM record as current position in set.

PositionVSet - Establish current variable-length ISAM record as current position in set.

PreviousInSet - Read the previous data record in the current key value set.

PreviousInVSet - Read the previous variable-length data record in the set defined by target.