|
|
|
c-treeDB API uses "sessions" to manage connections between client applications and c-tree Servers. Unlike many other types of sessions that are used by computers and computer networking systems, a c-treeDB API session has a dual nature: part of the session is persistent, and is shared between multiple client applications, and part of the session is not. It is important to understand how this works.
A c-treeDB API session consists of two separate entities, each of which resides in a different location: (1) a persistent, shared "session dictionary", and (2) a per-client "session handle".
1). Session Dictionary
The session dictionary is a persistent file that resides on the server. This file contains configuration information for the session, such as which databases are available to the users of that session, where the files for those databases are located, etc. When a client application logs into a session, it is connecting to, and using, the session dictionary file. It might help to think of the session dictionary file as maintaining the "database environment". Note that it is possible to create multiple session dictionary files on the server (using ctdbSetSessionPath() and ctdbCreateSession()), and configure each one differently, but this not commonly done. Most systems use only a single session dictionary file.
The session dictionary file is shared among all client applications that log into that session. A client application that logs into that session has access to the databases and resources that have been added to that session dictionary. Furthermore, any client application that is logged into a session can modify the contents of that session's session dictionary (by adding and removing databases from it, for example). When modifying the session dictionary, it is very important to remember that the dictionary is shared. Any changes to the session dictionary will be instantly seen by any other client applications that is currently logged into that session, or that log into it in the future. (Removing a database from a session dictionary will make that database unavailable to all other client applications that are currently logged into that session.) For this reason, modifying a session dictionary is generally considered to be a "server configuration" type of task, which is done rarely, and with deliberation and care. Generally, you add the database(s) you need to the session dictionary and then forget about the session dictionary. (Programmers who are using the single-client / single-user models of c-treeDB API do not have to worry about affecting multiple simultaneous client applications, but still need to remember that the session dictionary is persistent - it will remember the state it was in from the last time you logged onto that session.)
2). Session Handle
The other part of a session is a C pointer variable that is inside each client application program, and is called a "session handle". The session handle is private to each client application, so it is NOT shared between clients. Each client application allocates, initializes, and maintains its own session handle, and then deallocates it before exiting. The session handle represents a connection between a client and a FairCom Server database engine, and indicates the session type, the session dictionary, the server name and location of the session dictionary.
When working with c-treeDB API sessions, it is important to keep in mind which part of the session you are operating on - the shared, persistent session dictionary, or the private, volatile session handle, so you do not accidentally interfere with other client applications that are logged into the same session.
The c-treeDB API interface requires a session handle (which represents a connection to the database server) to perform any data structure initialization or manipulation. The following steps must be executed to set up a session before any database or table operations are attempted:
