Product Documentation

c-treeDB API API for C

Previous Topic

Next Topic

Allocating a Database Handle

Except for sessions allocated in CTSESSION_CTREE mode, a database handle is required before most database operations can take place. The FairCom DB API functions that work with databases expect a database handle as one of their parameters. A database handle is allocated with ctdbAllocDatabase() and freed with ctdbFreeDatabase().

When allocating a database handle, you need to provide a properly-allocated session handle because the call to ctdbAllocDatabase() associates the newly-allocated database handle with the specified session. The session does not need to be logged in, only allocated, before the database handle can be allocated and associated with that session.

CTHANDLE hSession = ctdbAllocSession(CTSESSION_CTDB);

CTHANDLE hDatabase = ctdbAllocDatabase(hSession);

if (!hSession || !hDatabase) {

printf("Session or database handle allocation failed\n");



When the database handle is no longer needed, release it with ctdbFreeDatabase(). A database handle must be allocated and released by ctdbAllocDatabase() and ctdbFreeDatabase().

If you free/release an active database handle (one that is currently connected to a database), ctdbFreeDatabase() automatically closes all tables associated with the database and disconnects the database from the database handle before releasing any of the resources associated with the database handle.