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.
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());
}
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());
}
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());
}
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());
}
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.
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());
}
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".