CTSession Class

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

CTSession

Parameters

This constructor has no parameters.

Description

This is the constructor for the CTSession class.

See also

~CTSession()

 

CTSession::~CTSession

Syntax

~CTSession

Parameters

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) const

Parameters

  • 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( ) const

Parameters

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( ) const

Parameters

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()