|
|
|
When operating with sessions of type CTSESSION_CTDB or CTSESSION_SQL, a session dictionary file named ctdbdict.fsd is required before a session logon is performed. The session dictionary file ctdbdict.fsd is located by default either in the server directory (client/server application) or in the execution directory (stand-alone application).
There could be situations where the c-treeDB API session dictionary file does not exist because it was deleted or this is the very first time the system is being executed. In this case it is necessary to create a session dictionary file before attempting to logon to a session. It is important to note that only one session dictionary file is necessary for the normal operation of c-treeDB API. Once created, the session dictionary file can be used for all database and table operations.
The following code fragment shows an example on how to create a new session dictionary file:
CTHANDLE hSession;
hSession = ctdbAllocSession(CTSESSION_CTDB);
if (!hSession)
FatalError("Session handle allocation failed\n");
if (ctdbCreateSession(hSession, "FAIRCOMS", "ADMIN", "ADMIN") != CTDBRET_OK)
FatalError("Error creating session dictionary file\n");
Note: The above code, as most of the pseudocode presented in this manual, does not make use of error checking. While not an appropriate programming style, it is used in this manual for clarity of the functional code presented.
These lines represent all three steps required to create the session dictionary. First, a session handle is declared. c-treeDB API uses Opaque handles, and the best approach is to use the declaration as done above with CTHANDLE, which is a pointer to void. All c-treeDB API handles should be defined this way. The next call, ctdbAllocSession(), makes the physical handle allocation. All c-treeDB API C functions are described in detail in c-treeDB API C API Function Reference.
After allocating a session handle, it is possible to log on to a session if the session dictionary already exists in the working directory. If not, a new session dictionary must be created using ctdbCreateSession().
In the above example, the session dictionary is created using ctdbCreateSession(), which requires four parameters: session handle, server name, user name, and user password. For the three last parameters, in this first example, the default values are being used.
The full network address may be required in the Server name: FAIRCOMS@10.0.0.1 or FAIRCOMS@my_machine.com. For non-server applications, the parameter is ignored and may be set to NULL.
A valid user name is required to access the c-tree Server. When the server is first installed, only the default user is permitted server access. This user name, ADMIN, is intended for the database administrator. ADMIN is also the default user name for c-treeDB API sessions. For non-server applications, the user name may be NULL. For server applications, see the c-tree Server Administrator’s Guide on how to create users and groups.
A valid user password is also required to access the c-tree Server. When the server is first installed, the default user ADMIN is associated with the default password, also ADMIN. For non-server applications, the user password may be NULL.
ctdbCreateSession() will return error DPON_ERR (19, data file already exists) if one tries to create a new session dictionary in the same directory where a session dictionary already exists.
