|
|
|
Once the user performs a successful Session Logon, the session handle can be used to operate on databases.
Every time a new database is created, or an existing database is added to a session, the database properties such as database name and path are placed in an entry of the session dictionary file.
Every time a user activates a database by connecting using ctdbConnect(), the handle of that database is placed in a list of active (connected) databases within the session handle. When a database is deactivated or disconnected by calling ctdbDisconnect(), the database handle is removed from the list of active databases in that session handle. A user may query the active database list in a given session handle by locating the first active database, the next active database, or finding a specific active database. A database is "active" for a given client application if that client has a database handle that is currently connected to that database. Note that this does not make the database "active" for any other client applications that might be connected to that session dictionary. In other words, if a database is "active" for one client that is logged into the session, it is not necessarily "active" for any other clients that are logged into the same session.
|
|
|
Use ctdbCreateDatabase() to create a new database dictionary. ctdbCreateDatabase() takes a session or a database handle, the database name, and the path where the database dictionary file is to be located. If the database path is NULL or empty ("") the database is created in the server directory for client/server applications, or in the execution directory for standalone applications.
/* create a new database MyDatabase */
if (ctdbCreateDatabase(hSession, "MyDatabase", "") != CTDBRET_OK)
{
printf("Create database failed\n");
}
ctdbCreateDatabase() creates a new database dictionary file with the database name and extension .FDD (FairCom Database Dictionary). Using the example above, the database dictionary file created is MyDatabase.fdd. Note that ctdbCreateDatabase() adds the new database to the specified session dictionary.
|
|
|
Use ctdbAddDatabase() to add an existing database to the current session dictionary. ctdbAddDatabase() takes a session or a database handle, the database name and the path where the database is located.
/* add MyDatabase to the current session */
if (ctdbAddDatabase(hSession, "MyDatabase", "") != CTDBRET_OK)
{
printf("Add database failed\n");
}
|
|
|
When you drop a database from a session, the database information is removed from the session dictionary, but the database dictionary file is left untouched. The drop database operation can be reversed with an add database operation. Drop a database from a session dictionary by calling ctdbDropDatabase().
/* drop MyDatabase from current session dictionary */
if (ctdbDropDatabase(hSession, "MyDatabase") != CTDBRET_OK)
{
printf("Drop database failed\n");
}
|
|
|
When you delete a database from a session, the database information is removed from the session dictionary and the database dictionary file is deleted. The delete database operation cannot be reversed and the database dictionary data will be lost. Delete a database from a session by calling ctdbDeleteDatabase().
/* delete MyDatabase from current session dictionary and from disk */
if (ctdbDeleteDatabase(hSession, "MyDatabase") != CTDBRET_OK)
{
printf("Delete database failed\n");
}
|
|
|
ctdbFirstDatabase() retrieves the name and path of the first database in a session dictionary. If the session dictionary has no databases, ctdbFirstDatabase() returns an INOT_ERR (101) code.
|
|
|
ctdbNextDatabase() retrieves the name and path of the next database in a session dictionary. ctdbNextDatabase() returns INOT_ERR (101) after it has listed all of the databases in that session dictionary.
/* display all databases in a session */
CTDBRET DisplayDatabases(CTHANDLE hSession)
{
CTDBRET Retval;
TEXT dbName[MAX_NAME];
TEXT dbPath[MAX_NAME];
if ((Retval = ctdbFirstDatabase(hSession, dbName, sizeof(dbName), dbPath, sizeof(dbPath)) == CTDBRET_OK)
do
{
printf("Database: %s Path:%s\n", dbName, dbPath);
Retval = ctdbNextDatabase(hSession,
dbName, sizeof(dbName), dbPath, sizeof(dbPath));
}
while (Retval = CTDBRET_OK);
if (Retval == INOT_ERR)
Retval = CTDBRET_OK;
return Retval;
}
|
|
|
ctdbFindDatabase() retrieves the path of a specific database in a session dictionary given the database name. If the database is not in the session dictionary, ctdbFindDatabase() returns INOT_ERR (101).
/* return YES if database exist or NO if database does not exit */
CTBOOL DatabaseExist(CTHANDLE hSession, pTEXT dbName)
{
TEXT dbPath[MAX_NAME];
return (ctdbFindDatabase(hSession, dbName, dbPath,
sizeof(dbPath)) == CTDBRET_OK) ? YES : NO;
}
The three functions just discussed are used to obtain the name and/or path of any databases that are in the session dictionary. The following three functions are used to obtain the database handles of the databases in the session dictionary. These functions have "Active" in their names because they only return the handles of "active" databases, ie. databases that are currently connected to the session via a database handle. These functions can not return database handles of non-active databases, because non-active databases do not have database handles.
|
|
|
ctdbGetFirstActiveDatabase() retrieves the database handle of the first active/connected database in the session. ctdbGetFirstActiveDatabase() returns NULL if the session contains no active databases.
|
|
|
ctdbGetNextActiveDatabase() retrieves the database handle of the next active/connected database in the session. When the handle of the last active/connected database has already been retrieved, ctdbGetNextActiveDatabase() returns NULL.
/* Display all active databases */
void DisplayActiveDatabases(CTHANDLE hSesssion)
{
VRLEN hScan;
CTHANDLE hDatabase;
if ((hDatabase = ctdbGetFirstActiveDatabase(hSession, &hScan)) != NULL)
{
do
{
printf("Database: %s Path: %s\n", ctdbGetDatabaseName(hDatabase),
ctdbGetDatabasePath(hDatabase));
hDatabase = ctdbGetNextActiveDatabase(hSession, &hScan);
}
while (hDatabase != NULL;
}
}
|
|
|
ctdbFindActiveDatabase() retrieves the handle of a specific active/connected database in the session. If the named database is not in the session dictionary, or is not active/connected, ctdbFindActiveDatabase() returns NULL.
/* Check if database is active */
CTBOOL IsDatabaseActive(CTHANDLE hSession, pTEXT dbName)
{
return (ctdbFindActiveDatabase(hSession, dbName) != NULL) ? YES : NO;
}
The function above is shown for example only. The FairCom DB API API function ctdbIsActiveDatabase() provides a more efficient way to check if a database is active.
|
|
|
When a database is created or added to a session dictionary, an automatic and unique identifier is associated with the database. (Note that creating a database implicitly adds it to the specified session dictionary.) A database UID is unique within the session that the database is associated with. In other words, as long as a database is left in the session dictionary, the database’s UID will not change. Removing the database from the session dictionary and then re-adding it to the session dictionary will very likely change the UID.
A database UID is an unsigned long value that can be used as an alternative method to operate on databases, once the database is created or added to the session.
|
|
|
ctdbFindDatabaseByUID() retrieves the name and path of any database in a session dictionary given the database UID. ctdbFindDatabaseByUID() requires a session handle or the handle of any database that is currently connected to the session you wish to search. The following example shows how to implement a database connect procedure using the database UID instead of the database name.
/* Database Connect using UID */
CTDBRET ConnectByUID(CTHANDLE hDatabase, ULONG uid)
{
TEXT dbName[MAX_NAME];
TEXT dbPath[MAX_PATH];
CTDBRET Retval;
Retval = ctdbFindDatabaseByUID(hDatabase, uid, dbName, sizeof(dbName), Path,
sizeof(dbPath));
if (Retval == CTDBRET_OK)
{
Retval = ctdbConnect(hDatabase, dbName);
}
return Retval;
}
|
|
|
ctdbFindActiveDatabaseByUID() retrieves the database handle of an active/connected database in the session dictionary given its UID. The following example shows how to check if a database is active using its UID.
/* check if database is active, by UID */
CTBOOL IsActiveDatabaseByUID(CTHANDLE hSession, ULONG uid)
{
return (ctdbFindActiveDatabaseByUID(hSession, uid) != NULL) ? YES : NO;
}
