Product Documentation

c-treeDB API API for C

Previous Topic

Next Topic

Allocating a Session Handle

A valid session handle is required to perform any session operation. The session handle must be allocated using ctdbAllocSession(). When the session handle is no longer needed it may be freed using ctdbFreeSession().

CTHANDLE hSession;

hSession = ctdbAllocSession(CTSESSION_CTDB);

if (!hSession)

FatalError("Session handle allocation failed\n");

/* ... some other statements ... */


When allocating a session handle, specify the session handle type. There are three different session handle types:


This session mode is intended for existing ISAM applications that want access to some of the c-treeDB API functionality, which is higher-level and easier-to-code than ISAM. Consider this mode as a stepping stone that allows ISAM applications to be modified to start using c-treeDB API functions a little at a time.

This mode allocates a new session handle for logon to the server only—it does NOT connect to the persistent session dictionary on the server. That means that many of the features available in the c-tree API (like database dictionaries and the database-specific functions) will not be available.

This session mode provides direct, low-level access to the table and index files on disk. This mode is higher-level than ISAM, but lower-level than c-treeDB API and SQL modes, which means that many of the higher-level database functions provided by the c-treeDB API API are not available in this mode. When using this session mode, allocate table handles using the session handle.


Allocate a new session making full use of a c-treeDB API session dictionary and the database dictionaries. Tables and fields/columns can be accessed using their logical names rather than paths on disk and column numbers.

The full database functions of the c-treeDB API API are available, providing high-level function calls which greatly simplifies the client application code. Table and index creation and modification is significantly easier, because this mode hides the complexity of the low-level ISAM layer, so the programmer can focus on the tables and indexes being created.

This session also maintains the SQL "NULL" field for you. With this session mode, a Session dictionary file must exist to perform a session logon and you must connect to a database before attempting to perform operations on tables.


Allocate a new session using c-treeDB API session and database dictionaries. Once logged on a server, if the server is SQL then database creation creates a SQL database. Once connected to a database, if the database is a SQL database and the table is associated with the database, then table and index creation, deletion, modifications are reflected in SQL system tables.

Note that database creation and table creation are slightly slower in this mode, but all other operations (table searching, record creation and deletion, etc) are just as fast as with the other session modes.


CTSESSION_SQL mode has the following limitation:

  • Problems with table structures will prevent update of FairCom DB SQL system tables.