ug_ch14.htm

db.* (pronounced dee-be star) is an advanced, high performance, small footprint embedded database fo

<td width="18%" valign="top">
<p><b><font size="2">contents</font></b></p>
</td>
<td width="82%" valign="top">
<p><font size="2">Number of key table entries</font></p>
</td>
</tr>
<tr>
<td width="18%" valign="top">&nbsp;</td>
<td width="82%" valign="top">&nbsp;</td>
</tr>
<tr>
<td width="18%" valign="top">
<p><b><font size="2">name</font></b></p>
</td>
<td width="82%" valign="top">
<p><b><font size="2">file_table</font></b></p>
</td>
</tr>
<tr>
<td width="18%" valign="top">
<p><b><font size="2">offset</font></b></p>
</td>
<td width="82%" valign="top">
<p><font size="2">22</font></p>
</td>
</tr>
<tr>
<td width="18%" valign="top">
<p><b><font size="2">length</font></b></p>
</td>
<td width="82%" valign="top">
<p><b><font size="2">ftlen = size_ft *
sizeof(FILE_ENTRY)</font></b></p>
</td>
</tr>
<tr>
<td width="18%" valign="top">
<p><b><font size="2">contents</font></b></p>
</td>
<td width="82%" valign="top">
<p><font size="2">File definitions table</font></p>
</td>
</tr>
<tr>
<td width="18%" valign="top">&nbsp;</td>
<td width="82%" valign="top">&nbsp;</td>
</tr>
<tr>
<td width="18%" valign="top">
<p><b><font size="2">name</font></b></p>
</td>
<td width="82%" valign="top">
<p><b><font size="2">record_table</font></b></p>
</td>
</tr>
<tr>
<td width="18%" valign="top">
<p><b><font size="2">offset</font></b></p>
</td>
<td width="82%" valign="top">
<p><b><font size="2">ftlen + 22</font></b></p>
</td>
</tr>
<tr>
<td width="18%" valign="top">
<p><b><font size="2">length</font></b></p>
</td>
<td width="82%" valign="top">
<p><b><font size="2">rtlen = size_rt *
sizeof(RECORD_ENTRY)</font></b></p>
</td>
</tr>
<tr>
<td width="18%" valign="top">
<p><b><font size="2">contents</font></b></p>
</td>
<td width="82%" valign="top">
<p><font size="2">Record definitions table</font></p>
</td>
</tr>
<tr>
<td width="18%" valign="top">&nbsp;</td>
<td width="82%" valign="top">&nbsp;</td>
</tr>
<tr>
<td width="18%" valign="top">
<p><b><font size="2">name</font></b></p>
</td>
<td width="82%" valign="top">
<p><b><font size="2">field_table</font></b></p>
</td>
</tr>
<tr>
<td width="18%" valign="top">
<p><b><font size="2">offset</font></b></p>
</td>
<td width="82%" valign="top">
<p><b><font size="2">ftlen + rtlen + 22</font></b></p>
</td>
</tr>
<tr>
<td width="18%" valign="top">
<p><b><font size="2">length</font></b></p>
</td>
<td width="82%" valign="top">
<p><b><font size="2">fdlen = size_fd *
sizeof(FIELD_ENTRY)</font></b></p>
</td>
</tr>
<tr>
<td width="18%" valign="top">
<p><b><font size="2">contents</font></b></p>
</td>
<td width="82%" valign="top">
<p><font size="2">Field definitions table</font></p>
</td>
</tr>
<tr>
<td width="18%" valign="top">&nbsp;</td>
<td width="82%" valign="top">&nbsp;</td>
</tr>
<tr>
<td width="18%" valign="top">
<p><b><font size="2">name</font></b></p>
</td>
<td width="82%" valign="top">
<p><b><font size="2">set_table</font></b></p>
</td>
</tr>
<tr>
<td width="18%" valign="top">
<p><b><font size="2">offset</font></b></p>
</td>
<td width="82%" valign="top">
<p><b><font size="2">ftlen + rtlen + fdlen + 22</font></b></p>
</td>
</tr>
<tr>
<td width="18%" valign="top">
<p><b><font size="2">length</font></b></p>
</td>
<td width="82%" valign="top">
<p><b><font size="2">stlen = size_st *
sizeof(SET_ENTRY)</font></b></p>
</td>
</tr>
<tr>
<td width="18%" valign="top">
<p><b><font size="2">contents</font></b></p>
</td>
<td width="82%" valign="top">
<p><font size="2">Set definitions table</font></p>
</td>
</tr>
<tr>
<td width="18%" valign="top">&nbsp;</td>
<td width="82%" valign="top">&nbsp;</td>
</tr>
<tr>
<td width="18%" valign="top">
<p><b><font size="2">name</font></b></p>
</td>
<td width="82%" valign="top">
<p><b><font size="2">member_table</font></b></p>
</td>
</tr>
<tr>
<td width="18%" valign="top">
<p><b><font size="2">offset</font></b></p>
</td>
<td width="82%" valign="top">
<p><b><font size="2">ftlen + rtlen + fdlen + stlen +
22</font></b></p>
</td>
</tr>
<tr>
<td width="18%" valign="top">
<p><b><font size="2">length</font></b></p>
</td>
<td width="82%" valign="top">
<p><b><font size="2">mtlen = size_mt *
sizeof(MEMBER_ENTRY)</font></b></p>
</td>
</tr>
<tr>
<td width="18%" valign="top">
<p><b><font size="2">contents</font></b></p>
</td>
<td width="82%" valign="top">
<p><font size="2">Set member table</font></p>
</td>
</tr>
<tr>
<td width="18%" valign="top">&nbsp;</td>
<td width="82%" valign="top">&nbsp;</td>
</tr>
<tr>
<td width="18%" valign="top">
<p><b><font size="2">name</font></b></p>
</td>
<td width="82%" valign="top">
<p><b><font size="2">sort_table</font></b></p>
</td>
</tr>
<tr>
<td width="18%" valign="top">
<p><b><font size="2">offset</font></b></p>
</td>
<td width="82%" valign="top">
<p><b><font size="2">mtlen + ftlen + rtlen + fdlen + stlen +
22</font></b></p>
</td>
</tr>
<tr>
<td width="18%" valign="top">
<p><b><font size="2">length</font></b></p>
</td>
<td width="82%" valign="top">
<p><b><font size="2">srtlen = size_srt *
sizeof(SORT_ENTRY)</font></b></p>
</td>
</tr>
<tr>
<td width="18%" valign="top">
<p><b><font size="2">contents</font></b></p>
</td>
<td width="82%" valign="top">
<p><font size="2">Set sort fields table</font></p>
</td>
</tr>
<tr>
<td width="18%" valign="top">&nbsp;</td>
<td width="82%" valign="top">&nbsp;</td>
</tr>
<tr>
<td width="18%" valign="top">
<p><b><font size="2">name</font></b></p>
</td>
<td width="82%" valign="top">
<p><b><font size="2">key_table</font></b></p>
</td>
</tr>
<tr>
<td width="18%" valign="top">
<p><b><font size="2">offset</font></b></p>
</td>
<td width="82%" valign="top">
<p><b><font size="2">srtlen + mtlen + ftlen + rtlen + fdlen + stlen
+ 22</font></b></p>
</td>
</tr>
<tr>
<td width="18%" valign="top">
<p><b><font size="2">length</font></b></p>
</td>
<td width="82%" valign="top">
<p><b><font size="2">size_kt * sizeof(KEY_ENTRY)</font></b></p>
</td>
</tr>
<tr>
<td width="18%" valign="top">
<p><b><font size="2">contents</font></b></p>
</td>
<td width="82%" valign="top">
<p><font size="2">Compound key field table</font></p>
</td>
</tr>
</table>
<p><font size="2">The end of the table space in the dictionary file
contains the record, field, and set names in ASCII format. The
names are variable in length and separated with newline characters.
The <b>size_rt</b> record names are listed first, followed by the
<b>size_fd</b> field names and the <b>size_st</b> set
names.</font></p>
<p>The runtime function, <b>d_open,</b> will allocate memory for
the seven tables and read them into memory from the dictionary
file. The size of the tables as reported by <b>ddlp</b> is the
amount of required memory.</p>
<p>The dictionary tables for a database contain several references
to each other. For example, the record table points to a range of
definitions of fields within the field table. Each field definition
will also contain a reference back to the record table. Each table
is an array of structures, and each inter-table reference is an
index into an array, which can be used to directly access the
definition. The following sections define the table elements, and
section 14.3.9, "Dictionary Tables Example," summarizes them with
an example.</p>
<h3><a name="FileTable" id="FileTable"></a>14.3.2 File Table</h3>
<p><font size="2">The file table contains information about all
data and key files in a database. One entry is used for each file.
If transaction logging is active, then an additional entry, the
transaction log file, is added to the file table during the
database open. The file table contains no references to other
tables, but is referenced by the record and field tables. The
<b>file_table</b> declaration is given below.</font></p>
<pre>
<font color="#0000FF">typedef struct {
   char       ft_name[FILENMLEN];
   DB_SHORT   ft_desc;
   char       ft_status;
   char       ft_type;
   DB_SHORT   ft_slots;
   DB_SHORT   ft_slsize;
   DB_SHORT   ft_pgsize;
   DB_SHORT   ft_flags;
} FILE_ENTRY;</font>
</pre>
<p><font size="2">The <b>ft_name</b> element contains the file name
in an ASCII string. The name may have path or drive information
embedded in it. The maximum length of the field, <b>FILENMLEN</b>,
is 256 characters.</font></p>
<p>The <b>ft_desc</b> element contains the file descriptor returned
by the <b>open</b> call. If the file is not open, the value will be
zero. This element is modified every time the <b>ft_status</b>
element is modified.</p>
<p>The <b>ft_status</b> element contains the current status of the
file; either open or closed. It is used during runtime file opening
and closing. The possible values are:</p>
<ul>
<li>'o' = opened</li>
<li>'c' = closed</li>
</ul>
<p>The <b>ft_type</b> element is the file type, with possible
values:</p>
<ul>
<li>'d' = data file</li>
<li>'k' = key file</li>
<li>'o' = overflow (transaction log) file</li>
</ul>
<p>The <b>ft_slots</b> element contains the number of record or key
slots on one page in this file.</p>
<p>The <b>ft_slsize</b> element contains the slot size, in bytes,
of the slots in this file.</p>
<p>The <b>ft_pgsize</b> element contains the page size, in bytes,
used for this file.</p>
<p>The <b>ft_flags</b> element is a bit map for the file options.
See <b>dbtype.h</b> for a list.</p>
<h3><a name="RecordTable" id="RecordTable"></a>14.3.3 Record
Table</h3>
<p><font size="2">The record table contains one entry for each
record type defined in the schema for this database. All size
information about the record is stored, along with references to
field table entries that define the fields included in the record.
The record table references the file and field tables, and is
referenced by the field, set, and member tables. The declaration of
<b>record_table</b> is shown below.</font></p>
<pre>
<font color="#0000FF">typedef struct {
   DB_SHORT   rt_file;
   DB_SHORT   rt_len;
   DB_SHORT   rt_data;
   DB_SHORT   rt_fields;
   DB_SHORT   rt_fdtot;
   DB_SHORT   rt_flags;
} RECORD_ENTRY;</font>
</pre>
<p><font size="2">The <b>rt_file</b> element is a reference to the
file table entry that defines the file containing this record
type.</font></p>
<p>The <b>rt_len</b> element is the total length of the record. If
this record is the largest in its file, the value of
<b>file_table[rt_file].ft_slsize</b> is equal to <b>rt_len</b>.
This value is required, however, because files can also contain
smaller records within the full slot size.</p>
<p>The <b>rt_data</b> element is the offset from the start of the
record to the first data field.</p>
<p>The <b>rt_fields</b> element is the index of the first field
definition in the field table.</p>
<p>The <b>rt_fdtot</b> element is a count of the number of fields
in this record type.</p>
<p>The <b>rt_flags</b> element is a bit map for the record options.
See <b>dbtype.h</b> for a list.</p>
<h3><a name="FieldTable" id="FieldTable"></a>14.3.4 Field
Table</h3>
<p><font size="2">The field table contains one entry for each field
defined in the schema. It also contains one entry for each compound
key defined. It fully defines each field's data type and length, as
well as array dimension limits.</font></p>
<p>The field table references the record, file, and key tables, and
is referenced by the record, key, and sort tables. The
<b>field_table</b> declaration is given below.</p>