Description

The CTDatabase class deals with the Database concept. The Database can be thought as a collection of tables. Multiple databases can be connected at the same time, within the same session. The same database may open at different sessions. CTDatabase class is derived from the CTBase class.

See Also

CTBase, CTSession, CTTable

Preconditions

Before performing any tasks with a CTDatabase object, it is necessary to initialize one CTSession object.

CTDatabase Methods

Constructor / Destructor

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

Database Handling

• IsActive(): Retrieves the active state of a database (connected or disconnected state)
• Connect(): Connects to a database
• Create(): Create a new database
• CreateDatabase(): Create a new database
• Disconnect(): Disconnects from a specific database
• GetName(): Retrieves the database name
• GetPath(): Retrieves the database path

Table Handling

• FirstTable(): Locates the first table in a database
• NextTable(): Locates the next table in a database
• FindTable(): Locates a table in a database by name
• AddTable(): Adds an existing table to a database
• DeleteTable(): Drops a table from the database, and delete the files from disk
• DropTable(): Drops a table from the database, but does not delete the files from disk
• GetTableUID(): Retrieves the table UID
• CloseAll(): Closes all active tables associated with the database
• GetTableCount(): Retrieves the number of tables in the database dictionary
• GetDefaultSqlTableOwner(): Retrieve the current default SQL table owner
• SetDefaultSqlTableOwner(): Set the default SQL table owner name

CTDatabase.CTDatabase

Syntax

CTDatabase( CTSession Handle)

Parameters

• Handle [in] the CTSession object to which the CTDatabase object is to be created or connected.

Description

This is the constructor for the CTDatabase class.

See Also

CTSession.CTSession(), Dispose()

CTDatabase.AddTable

Syntax

void AddTable( String Name, String Path)

Parameters

• Name [in] - The name of the table to add to the database.
• Path [in] - The table path to add to the database.

Description

Adds an existing table to the database. It is possible to add FairCom DB files to an existing database if this file has the incremental and DODA structures stored. See Compatibility regarding compatibility issues.

A table that has been created independent from a database, or in a different database may also be added to the current database.

Return

None.

Example

ADatabase.Connect();

try

{

ADatabase.AddTable(my_old_c-tree_file, path);

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

}

catch (CTException err)

{

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

return (1);

}

See Also

CreateTable(), DeleteTable(), DropTable()

CTDatabase.CloseAll

Syntax

void CloseAll( )

Parameters

This method has no parameters.

Description

Closes all active tables associated with the database. To close one specific table, the method CTTable.Close() may be used.

Return

None.

Example

aDatabase.CloseAll();

aSession.DisconnectAll();

aSession.Logout();

See Also

CTTable.Close()

CTDatabase.Connect

Syntax

void Connect(String Name)

Parameters

• Name [in] The database name to be connected.

Description

Connects to a database

Return

None.

Example

aSession = new CTSession();

aDatabase = new CTDatabase(aSession);

aSession.Logon();

aDatabase.Connect("myDatabase");

See Also

Disconnect()

CTDatabase.Create

Syntax

void Create( String Name, String Path)

Parameters

• Name [in] The database name to be created.
• Path [in] The path where the database will be created.

Description

Creates a new database

Return

None.

See Also

CTSession.CreateDatabase()

CTDatabase.CreateDatabase

Syntax

void CreateDatabase( String Name, String Path)

Parameters

• Name [in] The database name to be created.
• Path [in] The path where the database will be created.

Description

The two methods are equivalent, CreateDatabase(...) must be used in Delphi environment.

Return

None.

See Also

CTSession.CreateDatabase()

CTDatabase.DeleteTable

Syntax

void DeleteTable(String Name, String Password)

Parameters

• Name [in] The name of the table to delete from the database.
• Password [in] The table password.

Description

Drops a table from the database, and delete the files from disk.

Return

None.

Example

aMyTable.Close(); // close the custmast table.

aMyDatabase.DeleteTable("custmast", my_table_password);

See Also

AddTable(), DropTable()

CTDatabase.Disconnect

Syntax

void Disconnect( )

Parameters

This method has no parameters.

Description

Disconnects a specific database.

Return

None.

Example

aDatabase.Connect();

aDatabase.FirstTable(tbname, tbpath);

do

{ Console.Write("\ntable name: {0}",tbname.ToString() }

while (NextTable(tbname, tbpath);

aDatabase.Disconnect();

See Also

Connect()

CTDatabase.Dispose

Syntax

Void Dispose ()

Parameters

This method has no parameters.

Description

This is the destructor for the CTDatabase class. It frees the allocated memory to the Database. No database operations are allowed after the CTDatabase destructor is called.

See Also

CTDatabase()

CTDatabase.DropTable

Syntax

void DropTable(String Name)

Parameters

• Name [in] The name of the table to drop from the database.

Description

Drops a table from the database, but does not delete the files from disk. After one table has been dropped from the database, it may be operated independent from a Database using the CTSession.SetLogonOnly() method, or it may be added to any other database in the system.

Return

None.

Example

MyTable.Close(); // close the custmast table.

MyDatabase.DropTable("custmast");

See Also

AddTable(), CTSession.SetLogonOnly(), DeleteTable()

CTDatabase.FindTable

Syntax

bool FindTable(String Name, StringBuilder Path)

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

bool FindTable(ulong uid, StringBuilder Name, StringBuilder Path)

Parameters

• Name [in or out] The name of the table. When using the FindTable(ulong uid, StringBuilder Name, StringBuilder Path) prototype, Name is an output parameter. Otherwise, it is an input, and it is used to locate the table.
• Path [out] The table path, and it is returned by the method.
• uid [in or out] The table UID. When using the FindTable(String Name, StringBuilder Path, out ulong uid) prototype, uid is an output parameter. When using the FindTable(ulong uid, StringBuilder Name, StringBuilder Path) prototype, uid is an input parameter.

Description

Locates a table in a database. If the prototype FindTable(String Name, StringBuilder Path) is used, the table is searched by Name, and the method retrieves its Path. If the prototype FindTable(String Name, StringBuilder Path, out ulong uid) is used, the table is searched by Name, and the method retrieves its Path and uid. If the prototype FindTable(ulong uid, StringBuilder Name, StringBuilder Path) is used, the table is searched by uid, and the method retrieves its Name and Path.

Return

FindTable() returns true if the table is found, false otherwise.

See Also

FirstTable()

CTDatabase.FirstTable

Syntax

bool FirstTable(StringBuilder Name, StringBuilder Path)

Parameters

• Name [out] The name of the first table in the database
• Path [out] The path of the first table in the database.

Description

Locates the first table in a database.

Return

FirstTable() returns true if one table is found, no otherwise.

Example

aDatabase.Connect();

aDatabase.FirstTable(tbname, tbpath);

do

{ Console.Write("\ntable name: {0}",tbname.ToString()); }

while (NextTable(tbname, tbpath);

See Also

FindTable(), GetFirstActive(), NextDaTable()

CTDatabase.GetDefaultSqlTableOwner

SYNTAX

String GetDefaultSqlTableOwner( )

PARAMETERS

This method has no parameters.

DESCRIPTION

Retrieve the current default FairCom DB SQL table owner.

RETURN

Returns the owner name.

SEE ALSO

SetDefaultSqlTableOwner()

CTDatabase.GetName

Syntax

String GetName( )

Parameters

This method has no parameters.

Description

Retrieves the database name.

Return

GetName() returns the database name.

See Also

GetPath()

CTDatabase.GetPath

Syntax

String GetPath( )

Parameters

This method has no parameters.

Description

Retrieves the database path.

Return

GetPath() returns the database path.

See Also

GetName()

CTDatabase.GetTableCount

Syntax

int GetTableCount( )

Parameters

This method has no parameters.

Description

Retrieves the number of tables in the database dictionary.

Return

GetTableCount() returns the number of tables in the database.

Example

aDatabase.Connect();

n = aDatabase.GetTableCount();

Console.Write("\nThere are {0} tables in this database.",n);

CTDatabase.GetTableUID

Syntax

void GetTableUID( String Name, out ulong uid)

Parameters

• Name [in] The table name, given to the method.
• uid [out] The table UID, returned by the method.

Description

Retrieves the table UID.

Return

None.

See Also

SetTableUID()

CTDatabase.IsActive

Syntax

bool IsActive( )

Parameters

This method has no parameters.

Description

Retrieves the active state of a database (connected or disconnected state).

Return

IsActive() returns true if the database is connected, or false if database is disconnected.

Example

if (!aDatabase.IsActive())

aDatabase.Connect();

See Also

FindActive()

CTDatabase.IsExclusive

Retrieves the status of the database exclusive flag.

Declaration

bool CTDatabase.IsExclusive();

Description

CTDatabase.IsExclusive() retrieves the status of the database exclusive flag.

Return

Example

// verify an exclusive logon and connect

CTSession hSession(CTSESSION_CTDB);

CTDatabase hDatabase(hSession);
 

hSession.SetSessionExclusive(true);

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

if (hSession.IsExclusive())

printf("Session is exclusive\n");

else

printf("Session is shared\n");
 

hDatabase.SetExclusive(true);

hDatabase.Connect("MyData");

if (hDatabase.IsExclusive())

printf("Database is exclusive\n");

else

printf("Database is shared\n");
 

See Also

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

CTDatabase.NextTable

Syntax

bool NextTable(StringBuilder Name, StringBuilder Path)

Parameters

• Name [out] The name of the next table in the database.
• Path [out] The path of the next table in the database.

Description

Locates the next table in a database. FirstTable() must be used before using NextTable() for the first time in a database.

Return

NextTable() returns true if one table is found, false otherwise.

Example

aDatabase.Connect();

aDatabase.FirstTable(tbname, tbpath);

do

{ Console.Write("\ntable name: {0}",tbname.ToString(); }

while (NextTable(tbname, tbpath);

See Also

FirstTable()

CTDatabase.RenameTable

Declaration

CTDatabase.RenameTable(string OldName, string NewName)

Description

• OldName a string containing the original table name
• NewName a string containing the new table name

Return Values

None. Throws a CTException if an error occurs.

CTDatabase.SetDefaultSqlTableOwner

SYNTAX

void SetDefaultSqlTableOwner(String Name)

PARAMETERS

The owner name.

DESCRIPTION

Set the default FairCom DB SQL table owner name.

RETURN

None.

SEE ALSO

GetDefaultSqlTableOwner()

CTDatabase.SetExclusive

Sets or clears the database exclusive flag.

Declaration

void CDatabase.SetExclusive(bool flag);

Description

CTDatabase.SetExclusive() sets or clears the database exclusive flag. If a database exclusive flag is set, only one connection will be allowed on this database. Set the database exclusive flag after allocating the database handle, and before performing a connection. Setting the database exclusive flag after a database is connected will not have any effect during the current connection. flag will set or clear the database exclusive flag.

Return

Void

Example

// performs an exclusive logon and connect

CTSession hSession(CTSESSION_CTDB);

CTDatabase hDatabase(hSession);
 

hSession.SetExclusive(true);

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

hDatabase.SetExclusive(true);

hDatabase.Connect("MyData");
 

See Also

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