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 c-tree Plus for .NET layer, it is the first required object to be created for any application.

CTSession Methods

Constructor / Destructor

• CTSession(): Creates a CTSession object.
• Dispose(): Destroys a CTSession object and resets all the dependent objects.

Session Handling

• Create(): Creates a new session dictionary.
• CreateSession(): Creates a new session dictionary.
• ClearPathPrefix(): Clear the previous path prefix.
• GetParam(): Returns the session parameter based on the parameter type.
• GetPath(): Retrieve the path (drive/directory) of the session dictionary.
• GetPathPrefix(): Retrieve the current session wide 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(): Sets the current session wide path prefix.
• GetLogonOnly(): Retrieves the session logon only flag.
• SetLogonOnly(): Sets the session logon only flag. This flag, when set to true before the session Logon, will prevent the session from using the session dictionary.
• GetSessionType(): Retrieves the current session type.
• SetSessionType(): Change the session type.

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.
• FindDatabase(): Locates a database in a session.
• FirstDatabase(): Gets the first database for the session.
• GetDatabaseUID(): Retrieves a database UID.
• NextDatabase(): Gets the Next database for the session.
• GetDatabaseCount(): Retrieves the number of databases in the session dictionary.

Others

• GetLibType(): Retrieves the current library type.
• SetCurrentNodeName(): Sets a client side node name.

CTSession.CTSession

Syntax

CTSession

Parameters

This constructor has no parameters.

Description

This is the constructor for the CTSession class.

See Also

Dispose()

CTSession.Dispose

Syntax

Void Dispose()

Parameters

This method 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 (String Name, String 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

aSession.Logon();

try

{

aSession.AddDatabase(db_name, db_path);

Console.Write("\nDatabase added succesfully!!");

}

catch (CTException err)

{

Console.Write("\n\n{0} {1}",err.GetErrorCode(),

err.GetErrorMsg());

return (1);

}

See Also

CreateDatabase(), DeleteDatabase(), DropDatabase()

CTSession.Attach

Attaches an already initialized c-tree session to a c-tree.NET session object.

Declaration

void CTSession.Attach(bool isTransactionActive);

Description

CTSession.Attach() attaches an already initialized c-tree ISAM or low-level session to a FairCom DB API .NET session object. Attached sessions have no information concerning the server, user name or user password. Parameter isTransactionActive should indicate if a transaction is active or not.

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

//

// ... do something useful ...

//
 

// detach from session

hSession.Detach();
 

// perform an ISAM logout

CLISAM();
 

See Also

CTSession.Detach()

CTSession.ClearPathPrefix

SYNTAX

void ClearPathPrefix( )

PARAMETERS

This method has no parameters.

DESCRIPTION

Clear a previous path prefix.

RETURN

None.

SEE ALSO

GetPathPrefix(), SetPathPrefix()

CTSession.Create

Syntax

void Create ()

void Create (String dbEngine, String user, String password)

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.

Create() overload uses the default dbEngine, user and password.

Return

None.

See Also

Logon(), SetPath()

CTSession.CreateDatabase

Syntax

void CreateDatabase(String Name, String Path)

Parameters

• Name [in] the database name to be created
• Path [in] the database path

Description

Creates a new database.

Return

None.

See Also

AddDatabase(), DeleteDatabase(), DisconnectAll(), DropDatabase()

CTSession.CreateSession

Syntax

void CreateSession ()

void CreateSession (String dbEngine, String user, String password)

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

The Create() and CreateSession() methods are equivalent. CreateSession(...) must be used in Delphi environment

Return

None.

See Also

Logon(), SetPath()

CTSession.DeleteDatabase

Syntax

void DeleteDatabase(String 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

AddDatabase(), CreateDatabase(), DropDatabase()

CTSession.Detach

Detaches a c-tree.NET session object from an existing c-tree connection.

Declaration

void CTSession.Detach();

Description

CTSession.Detach() detaches a FairCom DB API .NET 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(false);
 

//

// ... 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

Connect(), CTSessionCreateDatabase(), Disconnect(), Logout()

CTSession.DropDatabase

Syntax

void DropDatabase(String 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

AddDatabase(), CreateDatabase(), DeleteDatabase()

CTSession.FindDatabase

Syntax

bool FindDatabase( String Name, StringBuilder Path)

bool FindDatabase( String Name, StringBuilder Path, out ulong uid)

bool FindDatabase(ulong uid, StringBuilder Name, StringBuilder 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(String Name, StringBuilder Path) is used, Name is an input, and the method returns the database path in Path. If the prototype FindDatabase(String Name, StringBuilder Path, out 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, StringBuilder Name, StringBuilder Path) is used, uid is an input, and the method returns the database name, and path in Name and Path respectively.

Return

FindDatabase() returns true if the database is found, false otherwise.

See Also

FirstDatabase(), GetDatabase(), NextDatabase()

CTSession.FirstDatabase

Syntax

bool FirstDatabase(StringBuilder Name, StringBuilder Path)

Parameters

• Name [out] the database name
• Path [out] the database path

Description

Gets the first database for the session.

Return

FirstDatabase() returns true if the database is found, false otherwise.

See Also

FindDatabase(), GetDatabase(), NextDatabase()

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:

See Also

CTSession.Attach(), CTSession.Detach()

CTSession.GetDatabaseCount

Syntax

int 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(String Name, out 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.GetLibType

Syntax

LIB_TYPE GetLibType( )

Parameters

This method has no parameters.

Description

Return the current library type (LIB_TYPE enumeration).

Return

GetLogonOnly() returns the current library type.

CTSession.GetLogonOnly

Syntax

bool GetLogonOnly( )

Parameters

This method has no parameters.

Description

Retrieves the session logon only flag. If the flag is set to true, 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 false, 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

Logon(), SetLogonOnly()

CTSession.GetParam

Syntax

int GetParam(SESSION_PARAM ParamType)

Parameters

• ParamType [in] identifies the parameter type. The valid values are:
  • SESSION_PARAM.BUFS
  • SESSION_PARAM.FILS
  • SESSION_PARAM.SECT
  • SESSION_PARAM.DBUFS
  • SESSION_PARAM.USERPROF

Description

Retrieves the session parameter based on the parameter type.

For more details, see Session Properties.

Return

GetParam() returns the session parameter value based on the parameter type.

See Also

SetParam()

CTSession.GetPath

Syntax

String 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

SYNTAX

String GetPathPrefix( )

PARAMETERS

This method has no parameters.

DESCRIPTION

Retrieve the current session wide path prefix. You can use GetPathPrefix() to check if a path prefix is set or not. If GetPathPrefix() return an empty string, then no path prefix is set.

RETURN

Return the current path prefix.

SEE ALSO

ClearPathPrefix(), SetPathPrefix()

CTSession.GetServerDateTime

Syntax

CTDateTime GetServerDateTime()

Description

Reports server-side date and time.

Return Values

See FairCom DB Error Codes for a complete listing of valid c-tree error values.

CTSession.GetServerName

Syntax

String GetServerName( )

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.GetSessionType

Syntax

SESSION_TYPE GetSessionType( )

Parameters

This method has no parameters.

Description

Retrieves the current session type.

Return

GetSessionType() returns the current session type.

See Also

SetSessionType()

CTSession.GetUserLogonName

Syntax

String GetUserLogonName( )

Parameters

This method has no parameters.

Description

Returns the user name associated with the session.

Return

GetUserLogonName() returns the user name associated with the session.

See Also

GetServerName()

CTSession.IsActive

Syntax

bool IsActive( )

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 true if the session is active, false otherwise.

See Also

Logon(), Logout()

CTSession.IsExclusive

Retrieves the status of the session exclusive flag.

Declaration

bool CTSession.IsExclusive();

Description

CTSession.IsExclusive() retrieves the status of the session exclusive flag.

Return

Example

// verify an exclusive logon

CTSession hSession(CTSESSION_CTDB);
 

hSession.SetExclusive(true);

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

void Logon(String dbEngine, String user, String password)

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.

The Logon() overload logs using the default values.

Return

None.

Example

aSession.Logon("FAIRCOMS", "ADMIN", "ADMIN");

See Also

IsActive(), Logout()

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

aSession.Logout;

See Also

IsActive(), Logon()

CTSession.NextDatabase

Syntax

bool NextDatabase(StringBuilder Name, StringBuilder 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 true if the database is found, false otherwise.

See Also

FindDatabase(), FirstDatabase(), GetDatabase()

CTSession.SetConfigurationFile

Sets the server .dll configuration file name and path if it's not located in the local working directory for the application that is loading the Server DLL. Note this function must be called before the Server DLL is loaded (e.g., started).

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 .NET 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

Syntax

void SetCurrentNodeName(String NodeName)

Parameters

• NodeName [in] the client side node name.

Description

Set a client side node name. The specified node name appears in the ctadmn utility under the option for "list clients".

SetCurrentNodeName() must be called after a successful logon.

Return

None.

CTSession.SetExclusive

Sets or clears the session exclusive flag .

Declaration

void CTSession.SetExclusive(bool flag);

Description

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

hSession.Logon("FAIRCOM", "ADMIN", "ADMIN");
 

See Also

CTSession.IsExclusive(), CTDatabase.SetExclusive(), CTDatabase.IsExclusive()

CTSession.SetLogonOnly

Syntax

void SetLogonOnly()

void SetLogonOnly(bool flag)

Parameters

• flag [in] the new session logon flag.

Description

Sets the session logon only flag. This flag, when set to true before the session Logon(), will prevent the session from using the session dictionary.

The SetLogonOnly() overload defaults to true.

Return

None.

See Also

GetLogonOnly()

CTSession.SetParam

Syntax

void SetParam(SESSION_PARAM ParamType, int value)

Parameters

• ParamType [in] identifies the parameter type. The valid values are:
  • SESSEION_PARAM.BUFS
  • SESSEION_PARAM.FILS
  • SESSEION_PARAM.SECT
  • SESSEION_PARAM.DBUFS
  • SESSEION_PARAM.USERPROF
• value [in] parameter value

Description

Sets the session parameter values.

For more details, see Session Properties.

Return

None.

See Also

GetParam()

CTSession.SetPath

Syntax

void SetPath(String Path)

Parameters

• Path [in] the session dictionary path.

Description

Sets the session dictionary path.

Return

None.

See Also

Create(), GetPath()

CTSession.SetPathPrefix

SYNTAX

void SetPathPrefix( String path )

PARAMETERS

Path prefix or NULL if you wish to remove the current path prefix.

DESCRIPTION

The FairCom DB API path prefix feature is similar to c-tree Server’s LOCAL_DIRECTORY configuration keyword. When SetPathPrefix() is called with a value, this value will be attached to the beginning of any file name that is not absolute.

Note: Path prefix does not became a permanent part of the file name. The path prefix is kept by the session handle and it is not persisted to disk. When the session handle is destroyed, the path prefix information is also destroyed.

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 affect only the database dictionary and any tables that are manipulated during that session. A path prefix can be removed at any time by passing a cleared or empty string as the path prefix or by calling ClearPathPrefix(). You can use GetPathPrefix() to check if a path prefix is set or not.

If GetPathPrefix() return NULL, then no path prefix is set.

RETURN

None.

SEE ALSO

ClearPathPrefix(), GetPathPrefix()

CTSession.SetSessionType

Syntax

void SetSessionType(SESSION_TYPE SessionType)

Parameters

• SessionType [in] the session type to set.

Description

Change the session type. The session type is initially set when CTSession() is created.

SetSessionType() allow users to change the session type after it has been allocated.

Return

None

See Also

GetSessionType()

CTSession.StartDatabaseEngine

Starts the FairCom DB database engine .dll model.

Declaration

CTDBRET CTSession::StartDatabaseEngine(void)

Description

A developer can call the CTSession.StartDatabaseEngine() method once before making any other FairCom DB API .NET calls and then call the CTSession.StopDatabaseEngine() method when finished with database activity to shutdown the database engine. CTSession.StartDatabaseEngine() must be called before any other FairCom DB API .NET calls 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 .NET exception on failure.

See also

CTSession.StopDatabaseEngine(), CTSession.SetConfigurationFile()

CTSession.StopDatabaseEngine

Stops the FairCom DB database engine .dll model.

Declaration

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