CTDatabase Class

class CTDatabase

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
  • ~CTDatabase(): 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
  • 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.
  • GetFirstActive(): Retrieves the first active table in the database.
  • GetNextActive(): Retrieves the next active table in the database.
  • FindActive(): Retrieves active table
  • CloseAll(): Closes all active tables associated with the database.
  • GetTableCount(): Retrieves the number of tables in the database dictionary.

 

CTDatabase::CTDatabase

Syntax

CTDatabase(const CTSession& Handle)
CTDatabase(const CTSession* Handle)

Parameters

  • Handle [in] the CTSession object, or a pointer to 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

~CTDatabase(), CTSession()

 

CTDatabase::~CTDatabase

Syntax

~CTDatabase

Parameters

This destructor 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::AddTable

Syntax

void AddTable(const CTString& Name, const CTString& 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 c-tree Plus 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


pDatabase->Connect();
try
{
   pDatabase->AddTable(my_old_c-tree_file, path);
   printf("\nTable added succesfully!!");
}
catch (CTException& err)
{
   printf("\n\n%d  %s",err.GetErrorCode(),
                             err.GetErrorMsg());
   return (1);
}
 

See also

DropTable(), DeleteTable(), CreateTable()

 

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


pDatabase->CloseAll();
pSession->DisconnectAll();
pSession->Logout();
 

See also

CTTable::Close()

 

CTDatabase::Connect

Syntax

void Connect(const CTString& Name)

Parameters

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

Description

Connects to a database

Return

None.

Example


pSession = new CTSession;
pDatabase = new CTDatabase(pSession);
pSession->Logon();
pDatabase->Connect("myDatabase");
 

See also

Disconnect()

 

CTDatabase::Create

Syntax

void Create(const CTString& Name, const CTString& 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::DeleteTable

Syntax

void DeleteTable(const CTString& Name, const CTString& 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


pMyTable->Close(); // close the custmast table.
pMyDatabase->DeleteTable("custmast", my_table_password);
 

See also

DropTable(), AddTable()

 

CTDatabase::Disconnect

Syntax

void Disconnect( )

Parameters

This method has no parameters.

Description

Disconnects a specific database.

Return

None.

Example


pDatabase->Connect();
pDatabase->FirstTable(tbname, tbpath);
do
    {  printf("\ntable name: %s",tbname.c_str();  }
while (NextTable(tbname, tbpath);
pDatabase->Disconnect();
 

See also

Connect()

 

CTDatabase::DropTable

Syntax

void DropTable(const CTString& 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


pMyTable->Close(); // close the custmast table.
pMyDatabase->DropTable("custmast");
 

See also

DeleteTable(), AddTable(), CTSession::SetLogonOnly()

 

CTDatabase::FindActive

Syntax

CTTable* FindActive(const CTString& Name)
CTTable* FindActive(ULONG uid)

Parameters

  • Name [in] The table name
  • uid [in] The table uid

Description

Retrieves active table. If the prototype FindActive(const CTString& Name) is used, the table name is searched. If the prototype FindActive(const CTString& Name) is used, the table uid is searched.

Return

FindActive() returns the table object handle, or null if the table no exists or is not active.

See also

FirstActive(), IsActive()

 

CTDatabase::FindTable

Syntax

CTBOOL FindTable(const CTString& Name, CTString& Path)
CTBOOL FindTable(const CTString& Name, CTString& Path, ULONG& uid)
CTBOOL FindTable(ULONG uid, CTString& Name, CTString& Path)

Parameters

  • Name [in or out] The name of the table. When using the FindTable(ULONG uid, CTString& Name, CTString& 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(const CTString& Name, CTString& Path, ULONG& uid) prototype, uid is an output parameter. When using the FindTable(ULONG uid, CTString& Name, CTString& Path) prototype, uid is an input parameter.

Description

Locates a table in a database. If the prototype FindTable(const CTString& Name, CTString& Path) is used, the table is searched by name, and the method retrieves its path. If the prototype FindTable(const CTString& Name, CTString& Path, ULONG& uid) is used, the table is searched by name, and the method retrieves its path and uid. If the prototype FindTable(ULONG uid, CTString& Name, CTString& Path) is used, the table is searched by uid, and the method retrieves its name and path.

Return

FindTable() returns YES if the table is found, NO otherwise.

See also

FirstTable()

 

CTDatabase::FirstTable

Syntax

CTBOOL FirstTable(CTString& Name, CTString& 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 YES if one table is found, NO otherwise.

Example


pDatabase->Connect();
pDatabase->FirstTable(tbname, tbpath);
do
    {  printf("\ntable name: %s",tbname.c_str();  }
while (NextTable(tbname, tbpath);
 

See also

NextDaTable(), FindTable(), GetFirstActive()

 

CTDatabase::GetFirstActive

Syntax

CTTable* GetFirstActive( )
CTTable* GetFirstActive(VRLEN& ScanRec)

Parameters

  • ScanRec [out] Holds the state of the first or next scan, and is returned by the method if the prototype GetFirstActive(VRLEN& ScanRec) is used.

Description

Retrieves the first active table in the database. One table is active if it is open. 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 table object pointer.

Example


pTable=pDatabase->GetFirstActive();
printf("\nFirst Active table: %s",
          pTable->GetName().c_str());
 

See also

GetNextActive(), FirstTable(), IsActive()

 

CTDatabase::GetNextActive

Syntax

CTTable* GetNextActive
CTTable* GetNextActive(VRLEN& ScanRec)

Parameters

  • ScanRec [in and out] Holds the state of the first or next scan. It is an input to the method, and it is at the same time, an output from the method when the prototype GetNextActive(VRLEN& ScanRec) is used.

Description

Retrieves the next active table in the database. One table is active if it is open. If more than one scan must be done at the same time, GetNextActive(VRLEN& ScanRec) must be used, with different ScanRec parameters for each scan.

Return

GetNextActive() returns the table object pointer.

See also

GetFirstActive(), IsActive()

 

CTDatabase::GetName

Syntax

CTString GetName( )

Parameters

This method has no parameters.

Description

Retrieves the database name.

Return

GetName() returns the database name.

See also

GetPath()

 

CTDatabase::GetPath

Syntax

CTString GetPath( )

Parameters

This method has no parameters.

Description

Retrieves the database path.

Return

GetPath() returns the database path.

See also

GetName()

 

CTDatabase::GetTableCount

Syntax

NINT 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


pDatabase->Connect();
n=pDatabase->GetTableCount();
printf("\nThere are %d tables in this database.",n);
 
 

CTDatabase::GetTableUID

Syntax

void GetTableUID(const CTString& Name, 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

CTBOOL IsActive( )

Parameters

This method has no parameters.

Description

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

Return

IsActive() returns YES if the database is connected, or NO if database is disconnected.

Example


if (!pDatabase->IsActive())
        pDatabase->Connect();
 

See also

FindActive()

 

CTDatabase::IsExclusive

Retrieves the status of the database exclusive flag.

Syntax

CTBOOL CTDatabase::IsExclusive() const;

Description

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

Return

Value Symbolic Constant Explanation
0 NO Database is shared.
1 YES Database is exclusive.

Example


// verify an exclusive logon and connect
CTSession hSession(CTSESSION_CTDB);
CTDatabase hDatabase(hSession);

hSession.SetSessionExclusive(YES);
hSession.Logon("FAIRCOMS", "ADMIN", "ADMIN");
if (hSession.IsExclusive())
    printf("Session is exclusive\n");
else
    printf("Session is shared\n");

hDatabase.SetExclusive(YES);
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

CTBOOL NextTable(CTString& Name, CTString& 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 YES if one table is found, NO otherwise.

Example


pDatabase->Connect();
pDatabase->FirstTable(tbname, tbpath);
do
    {  printf("\ntable name: %s",tbname.c_str();  }
while (NextTable(tbname, tbpath);
 

See also

FirstTable()

 

CTDatabase::RenameTable

Declaration

CTDatabase::RenameTable(const CTString& OldName, const CTString& 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.

See Also

 

CTDatabase::SetExclusive

Sets or clears the database exclusive flag.

Declaration

void CDatabase::SetExclusive(CTBOOL flag);

Description

flag will set or clear the database exclusive flag.

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, but before performing a connect. Setting the database exclusive flag after a database is connected will not have any effect during the current connection.

Return

void

Example


// perform an exclusive logon and connect
CTSession hSession(CTSESSION_CTDB);
CTDatabase hDatabase(hSession);

hSession.SetExclusive(YES);
hSession.Logon("FAIRCOMS", "ADMIN", "ADMIN");
hDatabase.SetExclusive(YES);
hDatabase.Connect("MyData");
 

See Also

CTSession::SetExclusive(), CTSession::IsExclusive(), CTDatabase::IsExclusive()

 

ctclass database

Was this article helpful?

Give feedback about this article

Related Articles