Connecting to a database

Before performing any operations with a database, except creating a new database, the database handle must be connected to the session by ctdbConnect(). The database should already have been created or added to the session. After a successful database connection to a session, the database is considered “active”.

CTHANDLE pMyDatabase;           

pMyDatabase = ctdbAllocDatabase(pMySession);

ctdbConnect(pMyDatabase, “MyFirstDatabase”);

The first line above declares the Database handle, which is not required for the database creation. The allocation of the handle links the database to the session. Use ctdbConnect() to connect to the database using the database handle and name. If the database doesn't exist, or exists but was dropped from the session, this call returns INOT_ERR (101). As suggested in the session creation/logon, the best approach to avoid errors is to attempt to connect to the database, and if it doesn't exist, create it, as shown in the Tutorial and Sample programs. The database path is not required to connect, since this information is stored inside the Session Dictionary.

When finished working with a database, disconnect it using ctdbDisconnect() or disconnect all databases at once with ctdbDisconnectAll(). If the database handle is not needed, free the allocated memory using ctdbFreeDatabase(). These steps are shown below, along with logging out from the session and freeing the session handle.

ctdbDisconnect(pMyDatabase);

ctdbLogout(pMySession);

ctdbFreeDatabase(pMyDatabase);

ctdbFreeSession(pMySession);