ug_ch4a.htm

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

<p><font size="2">New member records are connected (that is,
inserted) at the front of the list.</font></p>
</td>
</tr>
<tr>
<td valign="top" width="21%">
<p><b><font size="2">last</font></b></p>
</td>
<td valign="top" width="79%">
<p><font size="2">New member records are connected at the end of
the list.</font></p>
</td>
</tr>
<tr>
<td valign="top" width="21%">
<p><b><font size="2">ascending</font></b></p>
</td>
<td valign="top" width="79%">
<p><font size="2">New member records are connected in ascending
order based on the contents of the data fields specified in the
<b>by</b> part of the <b>member</b> clause of the <b>set</b>
statement.</font></p>
</td>
</tr>
<tr>
<td valign="top" width="21%">
<p><b><font size="2">descending</font></b></p>
</td>
<td valign="top" width="79%">
<p><font size="2">New member records are connected in descending
order based on the contents of the data fields specified in the
<b>by</b> part of the <b>member</b> clause of the <b>set</b>
statement.</font></p>
</td>
</tr>
<tr>
<td valign="top" width="21%">
<p><b><font size="2">next</font></b></p>
</td>
<td valign="top" width="79%">
<p><font size="2">New member records are connected immediately
following the current member of the set, or, if the current member
is null, at the front of the list.</font></p>
</td>
</tr>
</table>
<p><font size="2">The <b>by</b> part of the <b>member</b> clause is
only supplied when <b>ascending</b> or <b>descending</b> order is
specified. For sorted sets having more than one member record type,
the sort field(s) of those record types should correspondingly be
of the same type and length and be listed on the <b>by</b> clause
in the same order.</font></p>
<p>When the sort field values of new member records of a sorted set
duplicate existing members, the new members are added in front of
the members with matching values.</p>
<p>The set owner may be specified as <b>system</b>. Use of the
system record is not required. If one is used, do not declare it in
a DDL record statement. <b>ddlp</b> automatically creates the
system record when it is specified in a data file statement. There
is only one occurrence of the system record in the database. It is
used as the owner of any number of sets providing the means whereby
records can be connected to the top or root of the network. When a
database is opened, the current record and the current owner of all
system-owned sets are initialized to the system record (see section
5.3, "Currency Tables," for a discussion of currency).</p>
<p>Connecting member records to sets of order <b>first</b>,
<b>last</b>, or <b>next</b> is faster than connecting to sets of
order <b>ascending</b> or <b>descending</b>. This is because the
list of member records associated with <b>ascending</b> or
<b>descending</b> sets must be scanned each time a new member is
connected, in order to find the proper insertion point. Thus, a
connection to an <b>ascending</b> or <b>descending</b> set with a
large number of members can be relatively slow. If you need a large
sorted set, explore alternative approaches using keys or reverse
ordering to maintain the ordering.</p>
<blockquote><i>Note</i>: <b><i>db.*</i></b> does not implement
<b>ascending</b> or <b>descending</b> sets through an index. As
with all sets, they are implemented as a linked list (or chained)
structure. <b><i>db.*</i></b> does provide a keyed record access
(through a B-tree index) but it is totally distinct from sets. A
record can both have keys and be an owner and/or member of sets,
but sets do not use keys and keys do not use sets. Thus, sort
fields of ascending or descending sets do not need to be declared
as key fields.</blockquote>
<h5>Examples:</h5>
<pre>
<font color="#0000FF">set transactions {
   order last;
   owner budget;
   member check;
}
</font>
</pre>
<p><font size="2"><b>Transactions</b> is a set between the
<b>budget</b> record and the <b>check</b> record in the checking
account database. Each check written is to be applied to a
particular budget account. Each budget account has a set of checks
that have been written against it. As a new check is written and
entered into the database, it is connected to the
<b>transactions</b> set instance, where the appropriate
<b>budget</b> record has been identified as the current owner of
the set. The new <b>check</b> record will be connected to the end
of the set. Thus (assuming checks are written in order), they will
be stored in check number order (and probably date order as
well).</font></p>
<p>To ensure that checks are stored in date order, the set
specification could be modified as follows:</p>
<pre>
<font color="#0000FF">set transactions {
   order ascending;
   owner budget;
   member check by check_date;
}
</font>
</pre>
<p><font size="2">Here the order has been changed to
<b>ascending</b> and the member clause now includes the <b>by</b>
part to indicate that the set is to be sorted on the
<b>check_date</b> field of the <b>check</b> record. Again, the
connect operation will be slower than if the order is <b>last</b>.
However, if the sort field is known to usually force the insertion
to be at the end of the set instance, the ordering of the set could
be reversed so that the set remained sorted and so that the
insertion was usually made quickly at the front of the
list.</font></p>
<pre>
<font color="#0000FF">set comment {
   order first;
   owner note;
   member project;
   member task;
   member work_day;
}
</font>
</pre>
<p><font size="2">The <b>comment</b> set illustrates a use of
multiple member sets to reduce unnecessary space overhead. Each of
the <b>project</b>, <b>task</b>, and <b>work_day</b> record types
in a project management database can have an optional comment
associated with it in the <b>note</b> record. In this example, an
occurrence of <b>project</b>, <b>task</b>, or <b>work_day</b> can
be associated with only a single occurrence of <b>note</b>. Thus
each set instance is strictly one-to-one. Use of a single set is
preferred over three separate sets because it will use less space
for the set overhead (one set pointer is needed instead of three).
See section 4.4.2, "Physical Design Considerations," for more
information.</font></p>
<h2><a name="Operation" id="Operation"></a>4.3 DDL Processor
Operation</h2>
<h3><a name="Execution" id="Execution"></a>4.3.1 DDL Processor
Execution</h3>
<p><font size="2">The Database Definition Language Processor,
<b>ddlp</b>, is executed as follows:</font></p>
<p><b>ddlp</b> <i>[</i>-r<i>] [</i>-x<i>] [[</i>-c<i>]
[</i>-l<i>n]] [</i>-d<i>] [</i>-n<i>] [</i>-s<i>[</i>-<i>]]
[</i>-oxxxx<i>] [</i>-z<i>] [</i>-axxx<i>]</i> <i>ddlspec</i></p>
<p>File <b>ddlspec</b> is the name of the text file containing the
DDL specification. This file is sometimes called the schema
file.</p>
<p>The <b>ddlp</b> will compile the DDL in file <b>ddlspec</b> and
report any errors to <b>stdout</b> with the line number where the
error was detected.</p>
<p>The compiled DDL is stored in the database dictionary file for
use by the <b><i>db.*</i></b> runtime library functions. The name
of the dictionary is taken from the <i>dbname</i> of the database
DDL statement and given an extension <b>.dbd</b>, forming
<b>dbname.dbd</b>. The amount of dynamically allocated memory
required by the <b><i>db.*</i></b> runtime for storage of the
dictionary is reported by <b>ddlp</b> upon completion, if no errors
were detected. Otherwise, the dictionary file is not created.</p>
<p>If the <b>-r</b> option is specified, <b>ddlp</b> will display
(in <b>stdout</b>) the File Structure Report. (See "<b>ddlp</b>
File Structure Report" in section 4.4.2 for an explanation of the
use of this report.)</p>
<p>If the <b>-x</b> option is given, a cross-reference listing of
the records, fields, and set identifiers is displayed in
<b>stdout</b>. An example report is shown below for the checking
account schema.</p>
<pre>
<font color=
"#0000FF">db.* 1.0.0, DDL X-Ref Listing of File: ckngacct.ddl
Tue Feb 29 14:12:24 2000
alloc        field      13
amount       field      22
balance      field      14
budget       record     3   5    9    27
cat_desc     field      12
check        record     5   17   28
check_date   field      7   20
check_no     field      7   19
code         field      6   11
paid_to      field      21
transactions set        24
</font>
</pre>
<p><font size="2">The names are listed in alphabetical order, with
the associated type and the line numbers in the DDL file where the
name is referenced.</font></p>
<p>With the <b>-d</b> option, <b>ddlp</b> allows duplicate field
names, such that field types within different record types may have
the same name. The record structures created by <b>ddlp</b> will
contain the name as specified in the schema. The constant
definitions for all fields will be a concatenation of the record
type and field type, separated by an underscore. For example:</p>
<pre>
<font color="#0000FF">record ticket {
   .
   .
   float unit_cost;
}

record invoice {
   .
   float unit_cost
}
</font>
</pre>
<p><font size="2">will cause the following constant
definitions:</font></p>
<pre>
<font color="#0000FF">#define TICKET_UNIT_COST 4005
#define INVOICE_UNIT_COST 6014
</font>
</pre>
<p><font size="2">If duplicate field names are used with key
fields, then each reference to the key field name in the <b>key
file</b> statement must have a prefix showing the record type that
contains the field. The syntax is
<b>recname.fldname</b>.</font></p>
<p>The <b>-n</b> option instructs <b>ddlp</b> to omit writing the
ASCII record, set, and field names to the dictionary file. This
creates a smaller dictionary file, but makes names unavailable to
utilities such as <b>ida</b>, <b>dal</b>, and <b>dbimp</b>.</p>
<p><b>ddlp</b> creates C <b>struct</b> declarations for each record
type and compound key field defined in the DDL and stored with file
id, record, field, and set constants in a header file also named
from the <i>dbname</i> of the <b>database</b> statement forming
<b>dbname.h</b>. By default, case is preserved on all of the names
used. The <b>-s-</b> option may be used to instruct <b>ddlp</b> to
convert all of the names to lowercase to be compatible with
previous versions.</p>
<p>The <b>ddlp</b> can process constants, <b>#define</b>s,
predefined structures, and typedefs. All of these keywords must be
used before <b>ddlp</b> recognizes the keyword <b>database</b>.
Everything before the keyword <b>database</b> is copied to the
resulting header file, so the application will not need to redefine
anything.</p>
<p>As an example, the contents of file <b>ckngacct.h</b>, which was
created when the checking account schema (as given in section
4.2.1, "DDL Basics") was processed by <b>ddlp</b>, is shown
below.</p>
<pre>
<font color="#0000FF">#ifndef CKNGACCT_H
#define CKNGACCT_H

/* db.* 1.0.0 */

/* database ckngacct record/key structure declarations */

struct budget {
   char  code[6];
   char  cat_desc[48];
   float  alloc;
   float  balance;
};
struct check {
   int  check_no;
   int  check_date;
   char  paid_to[48];
   float  amount;
};
/* record, field and set table entry definitions */

/* File Id Constants */
#define DATFILE 0
#define KEYFILE1 1
#define KEYFILE2 2

/* Record Name Constants */
#define BUDGET 10000
#define CHECK 10001

/* Field Name Constants */
#define CODE 0L
#define CAT_DESC 1L
#define ALLOC 2L
#define BALANCE 3L
#define CHECK_NO 1000L
#define CHECK_DATE 1001L
#define PAID_TO 1002L
#define AMOUNT 1003L
/* Set Name Constants */
#define TRANSACTIONS 20000
/* Field Sizes */
#define SIZEOF_CODE 6
#define SIZEOF_CAT_DESC 48
#define SIZEOF_ALLOC 4
#define SIZEOF_BALANCE 4
#define SIZEOF_CHECK_NO 2
#define SIZEOF_CHECK_DATE 2
#define SIZEOF_PAID_TO 48
#define SIZEOF_AMOUNT 4

#endef    /* CKNGACCT_H */
</font>
</pre>
<p><font size="2">The <b>#define</b> constants are passed to
runtime library functions to identify the particular file, record,
field, or set type involved in the operation. The actual values
represent entries into the tables that make up the database
dictionary. The constants also have some additional control
information encoded, as follows:</font></p>
<div style="margin-left: 2em">
<p><font size="2"><i>Record name constants</i> consist of a record
number (record 0 is the first record defined in the DDL, record 1
is the second, and so on) plus 10000.</font></p>
<p><i>Set name constants</i> consist of a set number (numbered
sequentially, as are records) plus 20000. This information is used
by <b><i>db.*</i></b> runtime functions to distinguish between
record and set constants.</p>
</div>
<p><font size="2">Field name constants are formed using the
following formula:</font></p>
<div style="margin-left: 2em">
<p><font size="2">(record number * 1000) + number of field within
record</font></p>
</div>
<p><font size="2">This can simplify the work involved in adding a
new field to a record. With this technique, if a new field is only
added to the end of a record, only those modules that need to
reference the new field need to be recompiled. Note that field
constants are long integers, whereas file, record, and set
constants are standard integers.</font></p>
<p><font size="2">The <b>SIZEOF_??????</b> constants are added in
the header file as a convenience of the user. If they are not
needed, or are causing problems with large databases, they can be
removed with a <b>-z</b> option.</font></p>
<p><font size="2">The database header file should be
<b>#include</b>d in every C source module that needs to access the
database.</font></p>
<p><a href="UG_Ch4b.htm">Next Page</a></p>
</body>
</html>