Introduction

---

Upgrading tables is accomplished through the UpgradeTable method of the TDBISAMTable component. The properties used by the UpgradeTable method include the DatabaseName, TableName, and Exists properties. Upgrading a table takes table from a previous DBISAM table format and modifies its internal format so that it is compatible with the table format used by the version of DBISAM in use during the upgrade. DBISAM maintains a version number in all tables that indicates to DBISAM what format the table is in. You can use the TDBISAMTable VersionNum property to see what table format version a table is using.

Upgrading a Table

---

To upgrade a table, you must specify the DatabaseName and TableName properties of the TDBISAMTable component and then call the UpgradeTable method. The table component must be closed and the Active property must be False. It is usually good practice to also examine the Exists property of the TDBISAMTable component first to make sure that you don't attempt to upgrade a non-existent table. If you do attempt to upgrade a non-existent table an EDBISAMEngineError exception will be raised. The error code given when a table upgrade fails due to the table not existing is 11010 and is defined as DBISAM_OSENOENT in the dbisamcn unit (Delphi) or dbisamcn header file (C++). DBISAM will attempt to open the table exclusively before upgrading the table. If another session has the table open then an EDBISAMEngineError exception will be raised when this method is called. The error code given when upgrading a table fails due to the table being open by another session is 11013 and is defined as DBISAM_OSEACCES in the dbisamcn unit (Delphi) or dbisamcn header file (C++).

The following example shows how to upgrade the "customer" table using the UpgradeTable method:

begin
   with MyTable do
      begin
      DatabaseName:='d:\temp';
      TableName:='customer';
      if Exists then
         UpgradeTable;
      end;
end;

In addition to using the TDBISAMTable UpgradeTable method for upgrading tables, DBISAM also allows the use of the UPGRADE TABLE SQL statement.

Logging Upgrade Messages

---

During the upgrade process, DBISAM will relay detailed log messages regarding the process start and stop times and any information it deems pertinent. You can trap these log messages for further display or analysis via the TDBISAMTable and TDBISAMQuery OnUpgradeLog events.

Tracking the Upgrade Progress

---

To take care of tracking the progress of the upgrade we have provided the TDBISAMTable and TDBISAMQuery OnUpgradeProgress events.

Backup Files

---

DBISAM will make backups of a table's physical files before upgrading the table. Each physical file will have the same root table name but with a different extension. These extensions are as follows:


To restore these files in case of a mistake, simply rename them to the proper extension or copy them to the original file names. Also, these backup files will get overwritten without warning for each upgrade that occurs on the table. If you need the backup files for future use it's best to copy them to a separate directory where they will be safe.

The file extensions described above are the default extensions and can be changed. Please see the DBISAM Architecture and Customizing the Engine topics for more information.