ug_ch14.htm

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

<pre>
<font color="#0000FF">typedef struct {
  char      fd_key;
  char      fd_type;
  DB_SHORT  fd_len;
  DB_SHORT  fd_dim[MAXDIMS];
  DB_SHORT  fd_keyfile;
  DB_SHORT  fd_keyno;
  DB_SHORT  fd_ptr;
  DB_SHORT  fd_rec;
  DB_SHORT  fd_flags;
} FIELD_ENTRY;</font>
</pre>
<p><font size="2">The <b>fd_key</b> element defines the type of key
that this field is:</font></p>
<ul>
<li>'n' = not a key</li>
<li>'d' = non-unique key (duplicates allowed)</li>
<li>'u' = unique key</li>
</ul>
<p>The <b>fd_type</b> element defines the data type of this
field:</p>
<ul>
<li>'c' = char</li>
<li>'s' = short</li>
<li>'i' = int</li>
<li>'l' = long</li>
<li>'d' = <b>DB_ADDR</b></li>
<li>'f' = float</li>
<li>'F' = double</li>
<li>'g' = grouped (struct)</li>
<li>'k' = compound key</li>
</ul>
<p>The 'g' (grouped), and 'k' (compound key) fields have no data of
their own, as the rest of the field types do.</p>
<p>A group of fields is ordered in a specific way. First, the group
definition occurs, then the elements of the group occur, each
having a flag set (see <b>fd_flags</b>) indicating that they are
group elements. The group ends when there is a field without this
flag set, or at the end of the table.</p>
<p>If the field is flagged as a compound key field ('k'), it will
always follow the normal field definitions in a record. This
compound key field redefines the purpose of <b>fd_ptr</b> so that
it points to an entry in the key table rather than marking the byte
offset from the start of the record to the contents of this
field.</p>
<p>The <b>fd_len</b> element is the length of the field in bytes.
If the field is an array, this length is the basic data type length
times the dimensions of the array.</p>
<p>The <b>fd_dim[MAXDIMS]</b> element is a three-element
(<b>MAXDIMS</b> is three) array containing the values of any
declared dimensions. By default, all are zeros. If one dimension is
declared with the field type, then <b>fd_dim[0]</b> will contain
that value, and the others will remain zero.</p>
<p>If this field is a key field (that is, <b>fd_key</b> is 'd' or
'u'), then <b>fd_keyfile</b> is an index into the file table that
references the key file that contains this field.</p>
<p>The <b>fd_keyno</b> element is the key prefix number, which is
stored in the first two bytes of each key of this type (see section
14.2.3, "Key File Organization").</p>
<p>The <b>fd_ptr</b> element is the byte offset from the start of
the record to the contents of this field in a record. If this field
type is 'k' (compound key), this is an index into the key table of
the first field definition of the compound key.</p>
<p>The <b>fd_rec</b> element is an index into the record table of
the record that contains this field.</p>
<p>The <b>fd_flags</b> element is a bit map for field options. The
high-order six bits store non-zero optional key numbers. The
low-order 10 bits store the options for the field.</p>
<h3><a name="SetTable" id="SetTable"></a>14.3.5 Set Table</h3>
<p><font size="2">The set table contains one entry for every set
defined in the schema. It defines the set ordering and the position
of the set pointers in the record. Since there may be many members,
the member record types for this set type are defined in the member
table, which is referenced by this table. The set table references
the member and record tables, and is referenced only by the sort
table. The <b>set_table</b> declaration is given below.</font></p>
<pre>
<font color="#0000FF">typedef struct {
   DB_SHORT   st_order:
   DB_SHORT   st_own_rt;
   DB_SHORT   st_own_ptr;
   DB_SHORT   st_members;
   DB_SHORT   st_memtot;
   DB_SHORT   st_flags;
} SET_ENTRY;</font>
</pre>
<p><font size="2">The <b>st_order</b> element defines the set
ordering:</font></p>
<ul>
<li>'f' = order first</li>
<li>'l' = order last</li>
<li>'a' = order ascending</li>
<li>'d' = order descending</li>
<li>'n' = order next</li>
</ul>
<p>The <b>st_own_rt</b> element is an index to the record table of
the record type owning the set type.</p>
<p>The <b>st_own_ptr</b> element is the offset in the record of the
set pointers used for this set.</p>
<p>The <b>st_members</b> element is an index into the member table
of the first set member definition.</p>
<p>The <b>st_memtot</b> element is the total number of member
record types in this set.</p>
<p>The <b>st_flags</b> element is a bit map for set options. See
<b>dbtype.h</b> for a list.</p>
<h3><a name="MemberTable" id="MemberTable"></a>14.3.6 Member
Table</h3>
<p><font size="2">The member table contains one entry for each set
member in a database. Since one set may contain multiple members,
the set table will point to a range of consecutive entries in the
member table. Since a set member may be sorted by multiple fields,
each member entry may point to a range of consecutive entries in
the sort table.</font></p>
<p>The member table references the record and sort tables, and is
referenced by the set table.</p>
<pre>
<font color="#0000FF">typedef struct {
   DB_SHORT   mt_record;
   DB_SHORT   mt_mem_ptr;
   DB_SHORT   mt_sort_fld;
   DB_SHORT   mt_totsf;
} MEMBER_ENTRY;</font>
</pre>
<p><font size="2">The <b>mt_record</b> element is an index into the
record table of the member record type.</font></p>
<p>The <b>mt_mem_ptr</b> element is the offset, in the record, of
the member pointers.</p>
<p>The <b>mt_sort_fld</b> element is an index into the first entry
of the sort table of a sort field definition, if the set is
sorted.</p>
<p>The <b>mt_totsf</b> element is the number of sort table entries
used by this set member. This contains zero if the set is not
sorted.</p>
<h3><a name="SortTable" id="SortTable"></a>14.3.7 Sort Table</h3>
<p><font size="2">The sort table contains one entry for each field
that is referenced in an <b>order by</b> clause in a set
definition. The list of sorting fields occurs in the set
definition, following the naming of a member record type. The
member table refers to a range of entries in the sort table in
order to locate the field table entries involved in
sorting.</font></p>
<pre>
<font color="#0000FF">typedef struct {
   DB_SHORT   se_fld;
   DB_SHORT   se_set;
} SORT_ENTRY;</font>
</pre>
<p><font size="2">The <b>se_fld</b> element is an index into the
field table of one field definition involved in the field
sort.</font></p>
<p>The <b>se_set</b> element is an index into the set table of the
set type that owns this sorted list of members.</p>
<h3><a name="KeyTable" id="KeyTable"></a>14.3.8 Compound Key
Table</h3>
<p><font size="2">The compound key table contains one entry for
each field listed in each compound key statement. One compound key
statement may list several fields. For each compound key statement,
there is one entry in the field table, which points to a range of
entries in the compound key table. This range of entries is used to
form a single key from the fields referenced by the key table
entries.</font></p>
<p>Each entry in this table refers to the compound key and an
associated field, the position of the field in the key, and whether
the field is ascending or descending.</p>
<pre>
<font color="#0000FF">typedef struct {
   DB_SHORT   kt_key;
   DB_SHORT   kt_field;
   DB_SHORT   kt_ptr;
   DB_SHORT   kt_sort;
} KEY_ENTRY;</font>
</pre>
<p><font size="2">The <b>kt_key</b> element is an index into the
field table of the compound key definition in which this entry is
included.</font></p>
<p>The <b>kt_field</b> element is an index into the field table of
a field used in the compound key.</p>
<p>The <b>kt_ptr</b> element is an offset from the start of the
actual key to where the contents of this field begins.</p>
<p>The <b>kt_sort</b> element is the sorting order of this field.
The possible values are:</p>
<ul>
<li>'a' = ascending</li>
<li>'d' = descending</li>
</ul>
<h3><a name="Example" id="Example"></a>14.3.9 Dictionary Tables
Example</h3>
<p><font size="2">This section provides a simple example of a
schema and shows the tables that are generated as a result. This
short example contains most of the elements of a <b><i>db.*</i></b>
schema, and uses all seven table types. The text of the schema
is:</font></p>
<pre>
<font color="#0000FF">database mgrs {
   data file "data" contains manager, dept;
   key file "keys" contains name, emp_no;

   record manager {
      key long emp_no;
      char last_name[20];
      char first_name[20];
      compound optional key name {
         last_name ascending;
         first_name ascending;
      }
   }
   record dept {
      char title[10];
      int loc_code;
      float budget;
   }
   set manages {
      order ascending;
      owner manager;
      member dept by title, loc_code;
   }
}</font>
</pre>
<p><font size="2">The <b>prdbd</b> utility can be used to print the
contents of the dictionary tables. The report from a run of
<b>prdbd -c</b> on the above DDL specification is shown
below.</font></p>
<pre>
<font color="#0000FF">db.* Version 1.0.0 Ansi [29-Feb-2000]
Database Dictionary Tables for Database: mgrs
DBD Version: 3.00

REQUIRED MEMORY: 792 BYTES


------------------------------------------------------------------
FILE TABLE:

file sta type slots sl sz pg sz  initial     next pct flgs name
---- --- ---- ----- ----- ----- -------- -------- --- ---- ----
  0    c    d    15    64  1024        0        0   0 0000 data
  1    c    k    20    50  1024        0        0   0 0000 keys


------------------------------------------------------------------
RECORD TABLE:

                                       [#]first          tot
   [#]record      file    len  data      field      flds flags
-------------- ---------- ---- ---- --------------- ---- -----
[ 0]MANAGER    data.d00     63   19 [  0]EMP_NO        3 0010
[ 1]DEPT       data.k01     38   18 [  4]TITLE         3 0000


------------------------------------------------------------------
FIELD TABLE:

                              key   key record
   [#]field     key type len  file  num offset  [#]record    flags dims
--------------- --- ---- --- ------ --- ------ -------------- ----- ----
[  0]EMP_NO       d    l   4 keys.k   0     19 [ 0]MANAGER   0000
[  1]LAST_NAME    n    c  20          0     23 [ 0]MANAGER   0010  [20]
[  2]FIRST_NAME   n    c  20          0     43 [ 0]MANAGER   0010  [20]
[  3]NAME         d    k  40 keys.k   1      0 [ 0]MANAGER   0400
[  4]TITLE        n    c  10          0     18 [ 1]DEPT      0001  [10]
[  5]LOC_CODE     n    i   4          0     30 [ 1]DEPT      0001
[  6]BUDGET       n    f   4          0     34 [ 1]DEPT      0000



------------------------------------------------------------------
SET TABLE:

                         [#]owner    own ptr first  total
    [#]set      order     record     offset  member members flags
--------------- ----- -------------- ------- ------ ------- -----
[  0]MANAGES        a [ 0]MANAGER          7      0       1 0000


------------------------------------------------------------------
MEMBER TABLE:

                     mem ptr  # of 1st  total
mem #   [#]record    offset   sort fld  sort flds
----- -------------- -------  --------  ---------
   0  [ 1]DEPT             6         0          2


------------------------------------------------------------------
SORT TABLE:

sort #     [#]field          [#]set
------  ---------------  ---------------
     0  [  4]TITLE       [  0]MANAGES   
     1  [  5]LOC_CODE    [  0]MANAGES   


------------------------------------------------------------------
COMPOUND KEY TABLE:

         [#]compound    [#]component
key #     key field         field        ptr  order
-----  ---------------  ---------------  ---  -----
    0  [  3]NAME        [  1]LAST_NAME     0      a
    1  [  3]NAME        [  2]FIRST_NAME   20      a</font>
</pre>
<p><font size="2">Figure 14-15 shows the values that would be
contained in the dictionary tables for this database. The values
correspond to the element definitions contained in the above
sections. The table interrelationships are also shown.</font></p>
<p align="center"><b><img alt="dbstar_14-15.gif - 11765 Bytes"
border="0" height="458" src="dbstar_14-15.gif" width="462"></b></p>
<p align="center">Fig. 14-15. Dictionary Table
Interrelationships</p>
<h3><a name="Database" id="Database"></a>14.3.10 Database
Table</h3>
<p><font size="2">The database table is not contained in the
database dictionary file because it contains information that
pertains to multiple database usage.</font></p>
<p>When multiple databases are opened, the various dictionary
tables are, in effect, concatenated into larger tables so that they
appear to represent one large database. The inter-table references
are all offset to point directly to their new positions in the
tables.</p>
<p>When a <b><i>db.*</i></b> runtime function is called, first the
current database number is determined (if not supplied in the
call). Using the current database number as an index into the
database table, the offsets to the starting positions in the tables
for that database are obtained. If any adjustments are necessary to
the function parameters, the offset values stored in this table
will be used. For example, a record type might be passed to
<b>d_fillnew</b> that would require translation to a higher number
if the current database is not the first one.</p>
<p>The structure of the database table is as follows:</p>
<pre>
<font color="#0000FF">typedef struct {
   DB_SHORT   size_ft;
   DB_SHORT   ft_offset;
   DB_SHORT   size_rt;
   DB_SHORT   rt_offset;
   DB_SHORT   size_fd;
   DB_SHORT   fd_offset;
   DB_SHORT   size_st;
   DB_SHORT   st_offset;
   DB_SHORT   size_mt;
   DB_SHORT   mt_offset;
   DB_SHORT   size_srt;
   DB_SHORT   srt_offset;
   DB_SHORT   size_kt;
   DB_SHORT   kt_offset;
   DB_SHORT   key_offset;
   DB_ADDR    sysdba;
   DB_ADDR    curr_dbt_rec;
   DB_ULONG   curr_dbt_ts;
   DB_SHORT   page_size;
   char       db_path[PATHLEN];
   char       db_name[DBNMLEN];
} DB_ENTRY;</font>
</pre>
<p><font size="2">The <b>size_ft</b> element is the number of
elements in this database's file table.</font></p>
<p>The <b>ft_offset</b> element is the index in the global file
table to the first element of this database's file table.</p>
<p>The <b>size_rt</b> element is the number of elements in this
database's record table.</p>
<p>The <b>rt_offset</b> element is the index in the global record
table to the first element of this database's record table.</p>
<p>The <b>size_fd</b> element is the number of elements in this
database's field table.</p>
<p>The <b>fd_offset</b> element is the index in the global field
table to the first element of this database's field table.</p>
<p>The <b>size_st</b> element is the number of elements in this
database's set table.</p>
<p>The <b>st_offset</b> element is the index in the global set
table to the first element of this database's set table.</p>
<p>The <b>size_mt</b> element is the number of elements in this
database's member table.</p>
<p>The <b>mt_offset</b> element is the index in the global member
table to the first element of this database's member table.</p>
<p>The <b>size_srt</b> element is the number of elements in this
database's sort table.</p>
<p>The <b>srt_offset</b> element is the index in the global sort
table to the first element of this database's sort table.</p>
<p>The <b>size_kt</b> element is the number of elements in this
database's key