c-treeDB API API for C

Working with Databases

A database is a collection of tables and a session may contain several different databases. To use a database, you must first add that database to a session. (This is typically done only once, because sessions are persistent; see Working with Sessions in this manual.)

FairCom DB uses handles to manipulate databases and their tables. Before you can manipulate a database (that has been added to the session), you must first allocate a database handle and connect it to a database. You then use that handle to refer to the database when making API calls. Database handles can be reused (connected to one database, and then, later, connected to a different database), so allocating a handle and connecting it to a database are separate operations:

• The "allocate" call configures the database handle and associates it with a session.
• The "connect" call connects the database handle to one of the databases in that session.

Later, the database handle can be reused, by disconnecting it from its database and then connecting it to a different database in that session. Generally, a database handle is required before any table or data operations may take place. The exception to this rule is sessions allocated in CTSESSION_CTREE mode. These sessions do not have access to the database component, so they do not use database handles. (See Working with Sessions without Dictionary Support in this manual.)

The following are typical operations performed on a database handle:

• Allocate a database handle and associate it with a session by calling ctdbAllocDatabase().
• Connect that handle to a database in that session by calling ctdbConnect().
• Use the database handle to perform table, index, field and record operations with that database.
• When done with the database, disconnect it from the database handle by calling ctdbDisconnect().
• Release the database handle by calling ctdbFreeDatabase().

In This Section Allocating a Database Handle Connecting to a Database Database Properties Managing Tables Database Dictionary