Tcl Database Engine and API's

# Introduction

The database engine built by Future Lab is called Bbuuzzb. The engine is based on typeless string data with variable field and record size. Any number of fields may be present in the record and records may have a different number of fields.

The database engine uses special ASCII characters to delimit records and fields. Here are the delimiters used by the database engine:

- record delimiter - DBENG_RM - 255
- field delimiter - DBENG_FM - 254
- subfield delimiter - DBENG_SFM - 253
- subsubfield delimiter - DBENG_SSFM - 252

The above list starts with a description of the database delimiter constant (defined in dbeng.tcl) and the actual ASCII character code.

In theory the size of a record/field is only limited to the amount of memory that can be allocated (actually, there is a 9,999,999,999 record/field size limit due to the record header [see below]).

Each database table represents one physical OS file. The database engine does not use container files. The physical structure of each data file is a series of records with each record delimited by the record delimiter. Each field within the record is delimited by the field delimiter. At the beginning of each record there is a 12 byte record header consisting of:

       A|DnnnnnnnnnnFM

Where the first byte of the record header is either A for an active record or D for a record marked for deletion. The next 10 bytes (denoted above by nnnnnnnnnn) consists of the length of the record in question. Note that since all engine data is string based, the length is also stored in character form. The last byte of the record header (denoted above by FM) is the field mark.

Access to the data table by the engine is sequential. At the moment, there is no provision for indexes. When a record is re-written, the old record is marked for deletion and a new record is written. New records are always written to the end of the table. As the table builds the number of records marked for deletion, the pack procedure should be run against the specific table (autopack may also be used).

The database engine has no concept of a key field. The notion of a key field must be imposed by the developer. Since there is no key field concept, duplicates are allowed in any field. Duplicate key detection and handling must be handled by the developer.

The database engine relies on the word parsing abilities in the library module parse.tcl.

The database has two main API's: one for single user (dbeng.tcl) and one for client/server applications (dbcs.tcl). Each application should use one or the other but not both.

The database engine also contains configuration options specified in the database configuration file.

# Differences Between the Tcl Version and the C Version

This Tcl version of the Bbuuzzb database engine uses a pseudo two-dimemsional array to store the data for all tables that are in use. This is in contrast to the C version which uses a link list to store the same data. I use the term pseudo two-dimensional to describe the array although, in reality, there is only one dimension to the dbeng_table array. The full element index used to refer to the dbeng_table array is in the form:

       $tid,ename

Where $tid is the table tid usually stored in a variable and ename is the element within the table. For example, the channel variable used to read and write the table data is referred to as:

       $tid,handle

This Tcl version also has no concept of low level and high level procedures as they are not necessary. As a result, there are no modules with the names:

- dblocal
- dblocfg

There are only the single user API's and the client/server API's. Only one of them should sourceed by our application at any one time.

# Database Modules

## Dbcomm.tcl

This module contains the definition file for all the database commands used by the db/dbm applications.

## Dbeng.tcl

This module is the database engine. All engine operations that deal with file I/O are contained within this module.

## Dbengcat.tcl

This module contains the procedures to implement the system catalog. This module must be used with every application (single user or client/server) that uses the Bbuuzzb database.

## Dbengcfg.tcl

This module is used to manage single user database configuration details.

## Dbengsrt.tcl

This module contains the database sort routines.

## Dbfxp.tcl

This module contains procedures to get and put fixed-point numbers to and from database tables.

## Dbiocode.tcl

This module contains functions to translate Bbuuzzb engine codes to an English phrase.. This module must be used by every application that uses the Bbuuzzb database.

## Dbmess.tcl

This module contains the definition file for all the Bbuuzzb error, send and reply codes. This module must be used by every application that uses the Bbuuzzb database.

## Iexlib.tcl

This module is strictly not part of the database engine but is used to import ASCII data into Bbuuzzb tables based on a template.

Goto Top | Tcl Applications | Tcl Software Overview | Tcl Library Overview
| Future Lab Home | Contact Webmaster | Feedback

Copyright © 2006 Future Lab, Last Updated Jul 01, 2006