|
|
|
The FairCom DB API alter table function was designed and implemented to allow the modification of table properties after it was created and possibly already populated with data.
Depending on which properties are modified, a full table rebuild may be necessary. A full table rebuild is accomplished by creating a temporary table with the correct properties, considering all changes made to the table, and then moving all of the records from the original table to the new temporary table. Once all of the data records have been moved, the original table is deleted and the temporary table renamed with the name of the original table.
During the full table rebuild phase of moving records, a CTDB_ON_TABLE_REBUILD callback is invoked for every percentage point of progress. The progress percentage is calculated by dividing the number of records moved by the total number of records in a table. The percentage value is stored in the table handle and the callback function can access this value to display, for example, a progress report during lengthy alter table operations.
If a CTDB_ON_TABLE_REBUILD callback returns a value other than CTDBRET_OK, the rebuild process will be aborted, and the alter table function will return the value.
The handle passed as a parameter with this callback is a table handle and you can safely typecast the handle parameter to a pCTDBTABLE structure pointer. You can access the percentage counter by accessing the following CTDBTABLE structure member:
CTDBTABLE Structure Member |
Explanation |
|---|---|
NINT rebuild_perc |
percentage of table rebuild with values from 0 to 100 |
Before any records are moved, the CTDB_ON_TABLE_REBUILD callback is called with rebuild_perc set to zero to indicate that the operation is about to start. After all records are copied, CTDB_ON_TABLE_REBUILD is called again, this time with rebuild_perc set to 100 to indicate the end of rebuild.
Since CTDB_ON_TABLE_REBUILD callback is called inside the alter table’s record moving loop, care must be taken with the implementation of the callback since it may adversely affect the performance of the alter table operation.
You can also call the ctdbGetRebuildProgress() function to retrieve the table rebuild percentage counter.
FairCom DB API C API Example
CTDBRET ctdbDECL OnTableRebuild(CTHANDLE Handle)
{
pCTDBTABLE pTable = (pCTDBTABLE)Handle;
/* display a dot for every 5% rebuild completed */
if (pTable)
{
if (pTable->rebuild_perc > 0 && (pTable->rebuild_perc % 5) == 0)
printf(".");
}
return CTDBRET_OK;
}
