Product Documentation

c-treeDB API for C++ - Developers Guide

Previous Topic

Next Topic

Managing Tables

Once the user performs a successful database connect, the database handle can be used to operate on tables.

Every time a new table is created, or an existing table is added to a database, some of the table properties such as table name, path, data file extension, index file extension, etc, are placed in an entry of the database dictionary file.

Every time a user activates a table by opening it with CTTable::Open() method, the table is placed in a list of active (opened) tables within the database. When a table is deactivated, or closed by calling CTTable::Close() method, the table is removed from the list of active tables in the database. A user may query the active table list by locating the first active table, the next active table and finding a specific active table.

In This Section

Adding an existing table

Adding an existing table under transaction control

Dropping a table

Dropping a table under transaction control

Deleting a table

Deleting a table under transaction control

First Table

Previous Topic

Next Topic

Adding an existing table

An existing table may be added or imported to a database by calling the CTDatabase::AddTable() method. CTDatabase:AddTable() takes as parameters the table name and the table path.

// add MyTable to the current database

try

{

ADatabase.AddTable("MyTable", "");

}

catch (CTException &err)

{

printf("Add table failed with error %d\n", err.GetErrorCode());

}

Previous Topic

Next Topic

Adding an existing table under transaction control

An extra level of data integrity can be achieved when you add an existing table to a database under transaction control. When the transaction is committed, the database dictionary data for the table is committed to disk. If the transaction is aborted, the dictionary data for the table is automatically removed from the database dictionary.

The code fragment below shows how to add an existing table under transaction control.

// begin a transaction

ADatabase.Begin();

try

{

// add MyTable to the current database

ADatabase.AddTable("MyTable", "");

// commit the transaction

ADatabase.Commit();

}

catch (CTException &err)

{

// abort the transaction

ADatabase.Abort();

printf("Add table failed with code %d\n", err.GetErrorCode());

}

Previous Topic

Next Topic

Dropping a table

When you drop a table from a database, the table information is removed from the database dictionary, but the table data and index files are left untouched. The drop table operation can be reversed with an add table operation. Drop a table from a database by calling CTDatabase::DropTable() method.

// drop MyTable from current database

try

{

ADatabase.DropTable("MyTable");
}

catch (CTException &err)

{

printf("Drop table failed with code %d\n", err.GetErrorCode());

}

Previous Topic

Next Topic

Dropping a table under transaction control

An extra level of data integrity can be achieved when you drop a table from a database under transaction control. When the transaction is committed, the changes to the database dictionary data for the table are committed to disk. If the transaction is aborted, the dictionary data for the table is automatically restored to the database dictionary.

The code fragment below shows how to drop an existing table under transaction control. No error checking is included in the sample code:

// start a transaction

ADatabase.Begin();

try

{

// drop MyTable from current database

ADatabase.DropTable("MyTable");

// commit the transaction

ADatabase.Commit();

}

catch (CTException &err)

{

// abort the transaction

ADatabase.Abort();

printf("Drop table failed with code %d\n", err.GetErrorCode());

}

Previous Topic

Next Topic

Deleting a table

When you delete a table from a database, the table information is removed from the database dictionary and the table data and index files are deleted from disk. The delete table operation can be reversed only when used under transaction control. Without transaction control, a delete table operation will delete the data and index files and the table data will be lost. Delete a table from a database by calling CTDatabase::DeleteTable() method. Example:

// delete MyTable from current database

try

{

CTString password;

ADatabase.DeleteTable("MyTable", password);

}

catch (CTException &err)

{

printf("Delete table failed with code %d\n", err.GetErrorCode());

}

Note: The DeleteTable() method takes as parameters the table name and the table password. Set the password parameter to an empty CTString object if a table was created without passwords.

Previous Topic

Next Topic

Deleting a table under transaction control

An extra level of data integrity can be achieved when you delete a table from a database under transaction control. When the transaction is committed, the changes to the database dictionary data for the table are committed to disk and the table and index files are deleted from disk. If the transaction is aborted, the dictionary data for the table is automatically restored to the database dictionary and the original data and index files are restored to their original state.

The code fragment below shows how to delete an existing table under transaction control. No error checking is included in the sample code:

// start a transaction

try

{

// delete MyTable from current database

CTString password;

ADatabase.DeleteTable("MyTable", password);


// commit the transaction

ADatabase.Commit();

}
catch (CTException &err)

{

// abort the transaction

ADatabase.Abort();

printf("Delete table failed with code %d\n", err.GetErrorCode());

}

Previous Topic

Next Topic

First Table

CTDatabase::FirstTable() retrieves the name and path of the first table in a session. If the session has no tables, CTDatabase::FirstTable() returns NO (false). See the example in "Next Table".

TOCIndex