class CTSession
Description
Objects of the CTSession class manage sessions. A session is required to allow the connection with the databases; it is used for their general management as well. CTSession is derived from CTBase.
See also
CTBase, CTDatabase, CTTable
Preconditions
Since this is the upper level for the FairCom DB API layer, it is the first required object to be created for any application.
CTSession Methods
Constructor / Destructor
- CTSession(): Creates a CTSession object
- ~CTSession(): Destroys a CTSession Object and resets all the dependent objects
Session Handling
- Create(): Creates a new session dictionary
- GetParam(): Returns the session parameter based on the parameter type.
- GetPath(): Retrieve the path (drive/directory) of the session dictionary.
- GetPathPrefix(): Get the client-side path prefix.
- GetServerName(): Returns the server name associated with the session.
- GetUserLogonName(): Returns the user name associated with the session.
- IsActive(): Checks if the session is active.
- Logon(): Logs on to c-tree Server, or c-tree instance, session.
- Logout(): Logs out from c-tree Server or from c-tree instance session and release all resources
- SetParam(): Sets the session parameter values.
- SetPath(): Sets the session dictionary path.
- SetPathPrefix(): Set the client-side path prefix.
- GetLogonOnly(): Retrieves the session logon only flag.
- SetLogonOnly(): Sets the session logon only flag. This flag, when set to YES before the session Logon, will prevent the session from using the session dictionary.
- SetCurrentNodeName(): Sets the client node name.
DataBase Handling
- AddDatabase(): Adds an existing database to the session.
- CreateDatabase(): Creates a new database
- DeleteDatabase(): Drops a database from the session and deletes the data and index files.
- DisconnectAll(): Disconnects all databases
- DropDatabase(): Drops a database from a session.
- FindActive(): Find active database by name or by uid
- FindDatabase(): Locates a database in a session.
- FirstDatabase(): Gets the first database for the session
- GetDatabaseUID(): Retrieves a database UID
- GetFirstActive(): Retrieves the first active database
- GetNextActive(): Retrieves the next active database
- NextDatabase(): Gets the Next database for the session
- GetDatabaseCount(): Retrieves the number of databases in the session dictionary.
CTSession::CTSession
Syntax
CTSessionParameters
This constructor has no parameters.
Description
This is the constructor for the CTSession class.
See also
~CTSession()
CTSession::~CTSession
Syntax
~CTSessionParameters
This destructor has no parameters.
Description
This is the destructor for the CTSession class. It checks to see if the session is still active, and closes it (logout) if so. It also frees the allocated memory of the Session.
See also
CTSession()
CTSession::AddDatabase
Syntax
void AddDatabase (const CTString& Name, const CTString& Path)Parameters
- Name [in] The database name to be added to the session
- Path [in] The database path
Description
Adds an existing database to the session.
Return
None.
Example
pSession->Logon();
try
{
pSession->AddDatabase(db_name, db_path);
printf("\nDatabase added succesfully!!");
}
catch (CTException& err)
{
printf("\n\n%d %s",err.GetErrorCode(),
err.GetErrorMsg());
return (1);
}
See also
CreateDatabase(), DeleteDatabase(), DropDatabase()
CTSession::Attach
Attaches an already initialized c-tree session to a FairCom DB API session object.
Declaration
void CTSession::Attach(CTBOOL isTransactionActive = NO);
void CTSession::Attach(const CTString& ctreeid, CTBOOL isTransactionActive = NO);
void CTSession::Attach(const CTSession& Session);Description
- isTransactionActive indicates if a transaction is active or not.
CTSession::Attach() attaches an already initialized c-tree ISAM or low-level session to a FairCom DB API session object. Attached sessions have no information on server, user name or user password, and these values are set to NULL. Parameter.
Return
void
Example
// logon to c-tree using ISAM function
INTISAMX(10, 32, 32, 10, (USERPRF_NTKEY | USERPRF_CLRCHK));
// attach session to server handle
hSession->Attach(NO);
//
// ... do something useful ...
//
// detach from session
hSession->Detach();
// perform an ISAM logout
CLISAM();
See Also
CTSession::Detach()
CTSession::BeginImpersonation
Enables the ability of the thread to support impersonation by another thread.
Declaration
void CTSession::BeginImpersonation( NINT taskId )Description
Start the impersonation of the specific task ID.
Stores the current "lock mode" in the prevlockmode session property and begins the impersonation for the given taskId (ctImpersonateTask()).
Retrieves the server side "lock mode" ctdbGetLockMode() after the impersonation and updates the lockmode session property.
Note This function is not supported by the FairCom Server by default. It requires a custom build of the server available by special request.
Return
void
See Also
CTSession::EndImpersonation()
CTSession::Create
Syntax
void Create (const CTString& dbEngine=ctdbDEFAULT_dbengine,
const CTString& user=ctdbDEFAULT_userid,
const CTString& password=ctdbDEFAULT_userword)Parameters
- dbEngine [in] The c-tree Server Name
- User [in] The user name to use when logging on to the c-tree Server.
- Password [in] The user password to use when logging on to the c-tree Server.
Description
Creates a new session dictionary.
Return
None.
See also
Logon(), SetPath()
CTSession::CreateDatabase
Syntax
void CreateDatabase(const CTString& Name, const CTString& Path)Parameters
- Name [in] the database name to be created
- Path [in] the database path
Description
Creates a new database.
Return
None.
See also
DeleteDatabase(), DropDatabase(), AddDatabase(), DisconnectAll()
CTSession::DeleteDatabase
Syntax
void DeleteDatabase(const CTString& Name)Parameters
- Name [in] the database name to be deleted
Description
Drops a database from the session and deletes the data and index files.
Return
None.
See also
CreateDatabase(), DropDatabase(), AddDatabase()
CTSession::Detach
Detaches a FairCom DB API session object from an existing c-tree connection .
Declaration
void CTSession::Detach();Description
CTSession::Detach() detaches a FairCom DB API session object from an existing c-tree connection. The c-tree ISAM or low-level un-initialization is not called, but the session object is re-initialized.
Return
void
Example
// logon to c-tree using ISAM function
INTISAMX(10, 32, 32, 10, (USERPRF_NTKEY | USERPRF_CLRCHK));
// attach session to server handle
hSession->Attach(NO);
//
// ... do something useful ...
//
// detach from session
hSession->Detach();
// perform an ISAM logout
CLISAM();
See Also
CTSession::Attach()
CTSession::DisconnectAll
Syntax
void DisconnectAll ( )Parameters
This method has no parameters.
Description
Disconnects all databases from the session.
Return
None.
See also
Disconnect(), Connect(), CTSessionCreateDatabase(), Logout()
CTSession::DropDatabase
Syntax
void DropDatabase(const CTString& Name)Parameters
- Name [in] the database name to be dropped
Description
Drops a database from the session, but does not delete the data and index files.
Return
None.
See also
DeleteDatabase(), CreateDatabase(), AddDatabase()
CTSession::EndImpersonation
Disables the ability of the thread to support impersonation by another thread.
Declaration
void CTSession::EndImpersonation()Description
Finishes current impersonation (ctImpersonateTask()) and updates the "lock mode" on the server side with the lock mode stored before the impersonation in the prelockmode session property.
Note This function is not supported by the FairCom Server by default. It requires a custom build of the server available by special request.
Return
void
See Also
CTSession::BeginImpersonation()
CTSession::FindActive
Syntax
CTDatabase* FindActive(ULONG uid)
CTDatabase* FindActive(const CTString& Name)Parameters
- uid [in] the database uid to look for in the session
- Name [in] the database name to look for in the session
Description
Finds an active database by uid or name.
Return
FindActive() returns a pointer to the database object or NULL if no database is found.
See also
GetFirstActive(), GetNextActive()
CTSession::FindDatabase
Syntax
CTBOOL FindDatabase(const CTString& Name, CTString& Path)
CTBOOL FindDatabase(const CTString& Name, CTString& Path, ULONG& uid)
CTBOOL FindDatabase(ULONG uid, CTString& Name, CTString& Path)Parameters
- Name [in or out] the database name
- Path [out] the database path
- uid [in or out] the database uid
Description
Locates a database in a session. If the prototype FindDatabase(CTString& Name, CTString& Path) is used, Name is an input, and the method returns the database path in Path. If the prototype FindDatabase(const CTString& Name, CTString& Path, ULONG& uid) is used, Name is an input, and the method returns the database path, and uid, in Path and uid, respectively. If the prototype FindDatabase(ULONG uid, CTString& Name, CTString& Path) is used, uid is an input, and the method returns the database name, and path in Name and Path respectively.
Return
FindDatabase() returns YES if the database is found, NO otherwise.
See also
FirstDatabase(), NextDatabase(), GetDatabase()
CTSession::FirstDatabase
Syntax
CTBOOL FirstDatabase(CTString& Name, CTString& Path)Parameters
- Name [out] the database name
- Path [out] the database path
Description
Gets the first database for the session.
Return
FirstDatabase() returns YES if the database is found, NO otherwise.
See also
NextDatabase(), FindDatabase(), GetDatabase()
CTSession::GetAttachMode
Declaration
CTATTACH_MODE CTSession::GetAttachMode() const;Description
Retrieve the current session attach mode. GetAttachMode() will not execute a c-tree instance switch.
Return Values
One of the following values is returned:
| Returned CTATTACH mode | Description |
| CTATTACH_NONE | Handle or Session object is not attached, or Handle not a valid session handle. |
| CTATTACH_SESSION | Handle or Session object is attached to a FairCom DB API session. |
| CTATTACH_CTREEID | Handle or Session object is attached to a c-tree instance id. |
| CTATTACH_CURRENT | Handle or Session object was attached to current c-tree instance. |
See Also
CTSession::Attach(), CTSession::Detach()
CTSession::GetDatabaseCount
Syntax
NINT GetDatabaseCount( )Parameters
This method has no parameters.
Description
Retrieves the number of databases in the session dictionary. Notice that because GetDatabaseCount() changes the "current record pointer", this method should not be used in the middle of a search. The best approach is to use it before the initial loop to retrieve to total of databases in the session, then use in connection with FirstDatabase() and NextDatabase() to retrieve all database names and paths.
Return
GetDatabaseCount() returns the number of databases in the session dictionary.
See also
FirstDatabase(), NextDatabase()
CTSession::GetDatabaseUID
Syntax
void GetDatabaseUID(const CTString& Name, ULONG& uid)Parameters
- Name [in] the database name
- uid [out] the database uid
Description
Retrieves the database UID, given the database name.
Return
None.
See also
SetDatabaseUID()
CTSession::GetFirstActive
Syntax
CTDatabase* GetFirstActive( )
CTDatabase* GetFirstActive(VRLEN& ScanRec)Parameters
- ScanRec [out] the holder of the scan status
Description
Retrieves the first active database. A database is active if it is connected. The first prototype may be used when just one scan is being done. If more than one scan must be done at the same time, GetFirstActive(VRLEN& ScanRec) must be used, with different ScanRec parameters for each scan.
Return
GetFirstActive() returns the first active database in the session or 0 if there are no active databases in the session.
See also
GetNextActive(), FindActive(), CTDatabase::Connect()
CTSession::GetLibType
Retrieves the c-tree Plus operational model used when compiling the FairCom DB API library.
DECLARATION
LIB_TYPE CTSession::GetLibType()DESCRIPTION
ctdbGetLibType() provides the ability to detect c-tree Plus operational model used when compiling a FairCom DB API C library.
RETURNS
ctdbGetLibType() returns a value of type CTLIB_TYPE.
| CTLIB_TYPE | Description |
|---|---|
| CTLIB_SINGLE | Single user libary. |
| CTLIB_MUSER | Multi-user libary. |
| CTLIB_CLIENT | Client libary |
| CTLIB_LOCLIB | LOCLIB model. |
| CTLIB_SERVER | Server side library. |
| CTLIB_THREA | Multi-threaded enabled. |
| CTLIB_TRAN | Transaction processing enabled. |
The return value has the following bits set if the library supports optional features.
| Optional Bits | Description |
|
CTLIB_THREA |
Multi-threaded enabled. |
| CTLIB_TRAN | Transaction processing enabled. |
See "FairCom DB API Errors and Return Values" for a complete listing of valid FairCom DB API error codes and return values.
CTSession::GetLogonOnly
Syntax
CTBOOL GetLogonOnly( )Parameters
This method has no parameters.
Description
Retrieves the session logon only flag. If the flag is set to YES, the user will not be able to see the session dictionary, being able to work on the tables without connection with the databases. If the flag is set to NO, the default value, the user needs a session dictionary to work with the databases or tables.
Return
GetLogonOnly() returns the session logon only flag.
See also
SetLogonOnly(), Logon()
CTSession::GetNextActive
Syntax
CTDatabase* GetNextActive( )
CTDatabase* GetNextActive(VRLEN& ScanRec)Parameters
- ScanRec [in and out] the holder of the scan status; it is returned by GetFirstActive().
Description
Retrieves the next active database. The first prototype may be used when just one scan is being done. If more than one scan must be done, the GetNextActive(VRLEN& ScanRec) must be used, with different ScanRec parameters for each scan. In order to use GetNextActive(), an active record is required. An active record is obtained using one of the retrieval methods, GetFirstActive() or FindActive().
Return
GetNextDatabase() returns the next active database in the session or 0 if there are no active databases in the session.
See also
GetFirstActive(), FindActive()
CTSession::GetParam
Syntax
NINT GetParam(const CTSESSION_PARAM ParamType) constParameters
- ParamType [in] identifies the parameter type. The valid values are:
- CT_BUFS
- CT_FILS
- CT_SECT
- CT_DBUFS
- CT_USERPROF
Description
Retrieves the session parameter based on the parameter type.
Return
GetParam() returns the session parameter value based on the parameter type.
See also
SetParam()
CTSession::GetPath
Syntax
CTString GetPath( )Parameters
This method has no parameters.
Description
Retrieves the session dictionary path (drive/directory).
Return
GetPath() returns the session dictionary path.
See also
SetPath()
CTSession::GetPathPrefix
Get the client-side path prefix.
Declaration
CTBOOL CTSession::GetPathPrefix(CTString& pathPrefix);Description
A path prefix can be set anytime after the session handle is allocated. If a path prefix is set before a session logon, the new path prefix will affect the location of the session dictionary file. If a path prefix is set after a session logon, but before a database connect, then the path prefix affects only the database dictionary and any tables that are manipulated during that session.
If a path prefix is set, GetPathPrefix() returns YES and the path is set to pathPrefix. If no path prefix is set, GetPathPrefix() returns NO and pathPrefix is cleared.
A CTException is thrown when an error occurs. Use CTException::GetErrorCode() and CTException::GetErrorMsg() to retrieve the error code and descriptive message.
Return
| Value | Symbolic Constant | Explanation |
|---|---|---|
| 0 | NO | CTSession::GetPathPrefix returns NO when no path prefix has been set. |
| 1 | YES | CTSession::GetPathPrefix returns YES when a path prefix has been returned. |
See "FairCom DB API Errors and Return Values" for a complete listing of valid FairCom DB API error codes and return values.
Example
/* get the current path prefix */
try {
if (MySession.GetPathPrefix(MyCTStringPath))
printf ("Current path prefix is : %s\n", MyCTStringPath);
else
printf ("No current path prefix is set.\n");
}
catch(CTException &E) {
printf("ERROR: (%d) - %s\n", E.GetErrorCode(), E.GetErrorMsg());
}See also
CTSession::SetPathPrefix()
CTSession::GetServerName
Syntax
CTString GetServerName( ) constParameters
This method has no parameters.
Description
Returns the server name associated with the session.
Return
GetServerName() returns the server name associated with the session.
See also
GetUserLogonName()
CTSession::IsActive
Syntax
CTBOOL IsActive( ) constParameters
This method has no parameters.
Description
Checks if a session is active. A session is active when the session handle has been allocated and the session is logged in to the server.
Return
IsActive() returns YES if the session is active, NO otherwise.
See also
Logon(), Logout()
CTSession::IsExclusive
Retrieves the status of the session exclusive flag.
Declaration
CTBOOL CTSession::IsExclusive();Description
CTSession::IsExclusive() retrieves the status of the session exclusive flag.
Return
| Value | Symbolic Constant | Explanation |
|---|---|---|
| 0 | NO | Session is not exclusive. |
| 1 | YES | Session is exclusive. |
Example
// verify an exclusive logon
CTSession hSession(CTSESSION_CTDB);
hSession.SetExclusive(YES);
hSession.Logon("FAIRCOM", "ADMIN", "ADMIN");
if (hSession.IsExclusive())
printf("Session is exclusive\n");
else
printf("Session is shared\n");
See Also
CTSession::SetExclusive(), CTDatabase::SetExclusive(), CTDatabase::IsExclusive()
CTSession::Logon
Syntax
void Logon (const CTString& dbEngine=ctdbDEFAULT_dbengine,
const CTString& user=ctdbDEFAULT_userid,
const CTString& password=ctdbDEFAULT_userword)Parameters
- dbEngine: The server or c-tree Plus instance name (default is "FAIRCOMS")
- user: The user name (default is " ")
- password: The user password (default is " ")
Description
Logs on to a c-tree Server, or a c-tree instance, session. A logon is necessary to work with the databases. After a session is logged on, its status is active.
Return
None.
Example
pSession->Logon("FAIRCOMS", "ADMIN", "ADMIN");
See also
Logout(), IsActive()
CTSession::Logout
Syntax
void Logout( )Parameters
This method has no parameters.
Description
Logs out from a c-tree Server session or from a c-tree instance session and release all resources. After a call to Logout, the handle cannot be used.
Return
None.
Example
pSession->Logout;
See also
Logon(), IsActive()
CTSession::NextDatabase
Syntax
CTBOOL NextDatabase(CTString& Name, CTString& Path)Parameters
- Name [out] the database name
- Path [out] the database path
Description
Gets the next database for the session. A database must have already been retrieved using FirstDatabase(), FindDatabase(), or GetDatabase().
Return
NextDatabase() returns YES if the database is found, NO otherwise.
See also
FirstDatabase(), FindDatabase(), GetDatabase()
CTSession::SetConfigurationFile
Stops the FairCom DB database engine .dll model.
Declaration
CTDBRET CTSession::SetConfigurationFile(void)Description
SetConfigurationFile() sets the server .dll configuration file name and path.
Returns
Returns CTDBRET_OK on success, or throws a FairCom DB API exception on failure.
Example
try
{
CTSession::SetConfigurationFile("ctsrvr.cfg");
CTSession::StartDatabaseEngine();
} catch (CTException ex)
{
HandleException();
}
...
...
try
{
CTSession::StopDatabaseEngine();
} catch (CTException ex)
{
HandleException();
}See also
CTSession::StartDatabaseEngine(), CTSession::StopDatabaseEngine()
CTSession::SetCurrentNodeName
Sets the client node name.
Declaration
void CTSession::SetCurrentNodeName(String* NodeName)Description
When monitoring c-tree Server attached users, well written FairCom DB API client applications should "register" their workstation (node) name using the standard c-tree SETNODE() (SetNodeName()) function call.
CTSession::SetCurrentNodeName() sets a client-side node name. NodeName is a string specifying the node name. The specified node name appears in the ctadmn utility under the option for "list clients". CTSession::SetCurrentNodeName() can only be called after a successful logon.
This functionality is available only with the c-tree Server. A call to CTSession::SetCurrentNodeName() on non-server environment will always return CTDBRET_OK and the node name is ignored.
Return
void
Example
CTSession->Logon("FAIRCOMS", "ADMIN", "ADMIN");
CTSession->SetCurrentNodeName("MyNode1");
See Also
CTIndex::SetDefault(), CTRecord::BuildTargetKey()
CTSession::SetLogonOnly
Syntax
void SetLogonOnly(CTBOOL flag = YES)Parameters
- flag [in] the new session logon flag.
Description
Sets the session logon only flag. This flag, when set to YES before the session Logon, will prevent the session from using the session dictionary.
Return
None.
See also
GetLogonOnly()
CTSession::SetExclusive
Sets or clears the session exclusive flag.
Declaration
void CTSession::SetExclusive(CTBOOL flag);Description
- If flag is set to YES it will set the exclusive flag, while NO will clear the exclusive flag.
CTSession::SetExclusive() sets or clears the session exclusive flag. If a session exclusive flag is set, only one CTSESSION_CTDB or CTSESSION_SQL session will be allowed. Set the session exclusive flag after instantiating a CTSession object, but before performing a logon. Setting the session exclusive flag after a session logon is performed will not have any effect during the current session.
Return
void
Example
// perform an exclusive logon
CTSession hSession(CTSESSION_CTDB);
hSession.SetExclusive(YES);
hSession.Logon("FAIRCOM", "ADMIN", "ADMIN");
See Also
CTSession::IsExclusive(), CTDatabase::SetExclusive(), CTDatabase::IsExclusive()
CTSession::SetParam
Syntax
void SetParam(const CTSESSION_PARAM ParamType, const NINT value)Parameters
- ParamType [in] identifies the parameter type. The valid values are:
- CT_BUFS
- CT_FILS
- CT_SECT
- CT_DBUFS
- CT_USERPROF
- value [in] parameter value
Description
Sets the session parameter values.
Return
None.
See also
GetParam()
CTSession::SetPath
Syntax
void SetPath(const CTString Path)Parameters
- Path [in] the session dictionary path.
Description
Sets the session dictionary path.
Return
None.
See also
GetPath(), Create()
CTSession::SetPathPrefix
Set the client-side path prefix.
Declaration
void CTSession::SetPathPrefix(const CTString& pathPrefix);
void CTSession::SetPathPrefix();Description
A path prefix can be set anytime after the session handle is allocated. If a path prefix is set before a session logon, the new path prefix will affect the location of the session dictionary file. If a path prefix is set after a session logon, but before a database connect, then the path prefix affects only the database dictionary and any tables that are manipulated during that session.
A CTException is thrown when an error occurs. Use CTException::GetErrorCode() and CTException::GetErrorMsg() to retrieve the error code and descriptive message.
Return
void
Example
/* set a path prefix */
try {
MySession.SetPathPrefix("C:\FairCom\V8.14\ctreeSDK\ctreeAPI");
}
catch(CTException &E) {
printf("SetPathPrefix error: (%d) - %s\n", E.GetErrorCode(),
E.GetErrorMsg());
}
/* clear a path prefix */
try {
MySession.SetPathPrefix("");
}
catch(CTException &E) {
printf("SetPathPrefix error: (%d) - %s\n", E.GetErrorCode(),
E.GetErrorMsg());
}
See Also
CTSession::GetPathPrefix()
CTSession::StartDatabaseEngine
Starts the FairCom DB database engine .dll model.
Declaration
CTDBRET CTSession::StartDatabaseEngine(void)Description
A developer can call CTSession::StartDatabaseEngine() once before calling any FairCom DB API methods, and then call function CTSession::StopDatabaseEngine() when finished with database activites to shutdown the database engine. CTSession::StartDatabaseEngine() must be called before any other FairCom DB API methods are performed. CTSession::StartDatabaseEngine() loads the ctsrvr.cfg configuration file, creates the data and index caches, and initializes the multithreading subsystem.
Note that automatic recovery takes place on startup which can result in short delays after making this call, especially if the process was interrupted previously and an application shutdown without calling CTSession::StopDatabaseEngine().
This is a static method and it can be invoked without the presence of a CTSession object.
Returns
StartDatabaseEngine() returns CTDBRET_OK on success, or throws a FairCom DB API exception on failure.
See also
CTSession::StopDatabaseEngine(), CTSession::SetConfigurationFile()
CTSession::StopDatabaseEngine
Stops the FairCom DB database engine .dll model.
Declaration
CTDBRET CTSession::StopDatabaseEngine(void)Description
CTSession::StopDatabaseEngine() shuts down the FairCom DB database engine .dll model. This ensures a clean shutdown, resulting in quicker startups at the next application instance. It also ensures all files are properly closed and flushed to disk.
This is a static method and it can be invoked without the presence of a CTSession object.
Returns
Returns CTDBRET_OK on success, or throws a FairCom DB API exception on failure.
See also
CTSession::StartDatabaseEngine(), CTSession::SetConfigurationFile()