Understanding Database Template Files (.DBT)

OpenInsight's database management system is based on pluggable storage implementations, called filing systems.  The most common example is Linear Hash, which is implemented by the RTP57 filing system function.  The configuration information for those filing systems, which primarily defines the set of tables available to an application, is stored persistently (i.e., is not lost when you log out of OpenInsight) in a .DBT file.

In OpenInsight terms, a table is available if it is attached, and thus can be opened. As a result, without additional coding, a table is not available unless it is in the application's .DBT file.  The .DBT table is stored as a DOS file in the same folder as the OpenInsight executable (typically, X:\Revsoft\OInsight).  A separate .DBT file is created for each application: for example,  the .DBT file for EXAMPLES is called EXAMPLES.DBT.   A .DBT file is created when a database is defined.

The .DBT file should be updated when any of the following actions occurs:

A table has been created that will be part of the application's database;

A table has been deleted that was part of the application's database;

A table has been attached that will be part of the application's database;

A table has been detached that was and will no longer be part of the application's database;

An index has been added to a table that is part of the application's database and that previously did not have an index;

The last index on a table that is part of the application's database has been removed;

One or more tables that are part of the application's database have been moved.

A .DBT file should be deleted only if the following are true:

The database that it defines no longer exists;

The database definition is no longer used;

You are certain that a backup exists of the .DBT (just in case.)

In OpenInsight's ancestor programs (Revelation and Advanced Revelation), .DBT tables did not exist, which meant that when the user logged on, the logic to attach all the tables required for the application had to be either programmed, or attached by entering commands.  This was a laborious process.  The centralized table definition in one .DBT file makes managing the attaching process more efficient.  Database Manager and Table Builder, among other tools, make extensive use of the application's .DBT table, allowing you to see at a glance which tables and volumes are attached.

DBT File Structure

The .DBT file is a "core dump" of three things:

The information in SYSVOLUMES;

The information in SYSTABLES

The set of known filing systems used in the database.   This list is maintained by operations such as the OPEN statement, which will add a filing system function name to the list after the filing system successfully completes its INSTALL operation. The list is used by the system for two main operations: FLUSH and UNLOCK ALL. When either one of these BASIC+ commands is executed, the engine sends the corresponding call to each known filing system.

The .DBT file is @rm-delimited, with volume records, followed by a blank record, followed by table records, followed by a blank record, followed by the filing system list.

The volume records are @fm-delimited, and contain seven fields:

The SYSVOLUMES key;

Field 1 of the SYSVOLUMES record;

Field 2 of the SYSVOLUMES record;

Field 3 of the SYSVOLUMES record;

Field 4 of the SYSVOLUMES record;

Blank;

Field 6 of the SYSVOLUMES record.

The table records are @fm-delimited, and contain five fields:

The SYSTABLES key;

Field 1 of the SYSTABLES record;

Field 2 of the SYSTABLES record;

Field 3 of the SYSTABLES record;

Field 4 of the SYSTABLES record;

The filing system list is @fm-delimited.


Problems with DBT Files

There are several problems with .DBT files, which are:

An attached table is missing;

An index, just added, doesn't work;

The .DBT file is corrupt, resulting in inability to login to the application

The first problem, a missing table, has one of two probable causes:

After creating/copying/attaching the table, the database definition was not updated (using Define_Database, for example);

Somehow the volume and table information for this table was out of sync, and the auto-synchronization code (see below) removed the table from the database.

Almost always, it is the first problem. To solve this, attach the table and use Define_Database to save the database definition. The fastest way to run Define_Database in OpenInsight is to open Database Manager and choose Save from the Database menu.

The second problem is similar to the first, but it shows itself in a different manner - a non-working index. When an index is added to a table that has no indexes, the system creates a new table to store the index information. This table is called a "bang table", because its name is the same as the data table but has an exclamation point (a "bang") glued on the front. The solution is to attach the data table (which will automatically attach the dictionary and index tables, if they exist) and then use Define_Database to save the database definition.

The last problem happens rarely, but it has happened. The easiest way to fix this is to pull the affected .DBT from a backup.  

Note:  If the backup .DBT is lost, use the following procedure to recover:

Assuming your database name is EXAMPLES, so your .DBT file is named EXAMPLES.DBT;

Rename EXAMPLES.DBT to EXAMPLES.BAK, making a temporary backup;

Make a copy of SYSPROG.DBT; name the copy EXAMPLES.DBT;

Log into the EXAMPLES application.

What this does is start the EXAMPLES database out with just the system tables attached. Now you have to go back into Database Manager (or use the command line) to attach the tables necessary for your application. Once you have done that, use Define_Database to save the database definition. After you are happy that EXAMPLES is working well again, make a back up.

You should update your .DBT (using Define_Database) whenever the following occur:

A table has been created that will be part of the application's database;

A table has been deleted that was part of the application's database;

A table has been attached that will be part of the application's database;

A table has been detached that was and will no longer be part of the application's database;

An index has been added to a table that is part of the application's database and that previously did not have an index;

The last index on a table that is part of the application's database has been removed;

One or more tables that are part of the application's database have been moved.

Note:  When using the system tools (as opposed to the command line), the .DBT file is usually updated in each of these cases except in the case of adding and removing indexes.