ug_ch4a.htm

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

<p>The <b>static</b> attribute specifies that the records are never
updated when the database is opened in shared mode. This allows the
<b><i>db.*</i></b> runtime to optimize access to the static record
occurrence, yielding much better performance. Static records are
used for storing information such as menus, data entry forms, help
screens, system messages, coded value information, etc. Multi-user
database programs are not required to place locks on this data in
order to access it. Static records can only be modified when the
database is opened in exclusive access mode. Single-user
applications may modify static records at any time. The data and
key files containing static record information can only contain
static data. The system record is a special case and can be
included in a data file that contains either static or not static
records. Static records can only be used in sets which themselves
are not modified except in exclusive access mode.</p>
<h5>Example:</h5>
<pre>
<font color="#0000FF">record check {
   unique key int check_no;
   key int check_date;
   char paid_to[49];
   float amount;
}
</font>
</pre>
<p><font size="2">The <b>check</b> record type in the checking
account database contains two integer fields (one of which is a
key), a character string field, and a floating point field. File
<b>chkgacct.h</b> will contain the following definitions associated
with the check record type:</font></p>
<pre>
<font color="#0000FF">struct check {
   int  check_no;
   int  check_date;
   char  paid_to[49];
   float  amount;
};
#define CHECK 10001
</font>
</pre>
<p><font size="2">Record <b>trans</b> below contains two compound
key field declarations. (For more information, see "Use of Keys" in
section 4.4.1, "Logical Design Considerations."</font></p>
<pre>
<font color="#0000FF">record trans {
   unique key int checkno;
   int trdate;
   char vendid[8];
   long amount;
   compound key tr_key {
      trdate descending;
      vendid ascending;
   }
   compound key ven_chks {
      vendid; checkno;
   }
}
</font>
</pre>
<p><font size="2">Below are two record types and a set that might
be defined for a multi-user data entry, forms management system.
Note that both records are declared to be static, since during
normal operation of an application using the forms manager, form
and field records are not modified.</font></p>
<pre>
<font color="#0000FF">   static record form {
   unique key char form_id[11];
}
static record field {
   unique key char field_id[21]; /* Display name of field */
   int  id_row;         /* Row where field_id displayed */
   int  id_col;         /* Column where field_id displayed /
   int  data_row;      /* Row where data starts */
   int  data_col;      /* Column where data starts */
   int  field_len;      /* Editable field length */
   char required;      /* Required field */
   int  edit_fcn;      /* Editing function called on entry */
   int  disp_fcn;      /* Display function called on output /
   int  rtype;         /* Record type containing the field */
   long ftype;         /* db.* field type */
}
set form_fields {
   order last;
   owner form;
   member field;
}
</font>
</pre>
<h3><a name="Field" id="Field"></a>4.2.6 Field Declarations</h3>
<h4><a name="Data" id="Data"></a>Data Fields</h4>
<p><b><font size="2">Syntax:</font></b></p>
<pre>
<font color=
"#0000FF">   <i>[[</i>optional<i>] [</i>unique<i>]</i> key<i>]</i> type <i>fldname [ [dim]...] [</i>om_field<i>]</i> ;
or 
   <i>[[</i>optional<i>] [</i>unique<i>]</i> key<i>]</i> struct {
      field_stmt
      ...
   } <i>fldname [[dim]...]</i> ;

type =
   <i>[</i>unsigned<i>]</i> int | <i>[</i>unsigned<i>]</i> short | <i>[</i>unsigned<i>]</i> long | 
   char | float | double | DB_ADDR

om_field = 
   directref <i>recname</i>
or
   relatedto <i>recname</i> thru <i>fldname
</i></font>
</pre>
<h5>Description:</h5>
<p><font size="2">The <i>fldname</i> is an identifier that names
the particular data field. Field names may not duplicate record or
set names, nor by default other field names.</font></p>
<p>The syntax for a data field statement is similar to, although
not as general as, a C data declaration. In fact, most of the basic
data types in C are directly supported in the DDL. Arrays of any
type are available, where <i>dim</i> specifies the size of a given
array dimension.</p>
<p>One-dimensional character arrays are treated by the
<b><i>db.*</i></b> runtime functions as C strings. Thus, these
fields should always be terminated by a null byte, and the length
as specified in the field declaration should include the null byte.
If a one-dimensional character array is needed that is not intended
to be treated like a string (for example, a byte array), it should
be declared as a two-dimensional array where the second dimension
is one.</p>
<p>A data field that is also to be used as a key to the record has
the <b>key</b> attribute. Key field values are stored on the key
file in the natural order based on the data type. If only unique
keys are allowed then the field should be qualified as a <b>unique
key</b> field. The maximum length of a key field is 246 bytes.
Fields defined as a <b>unique key</b> must contain a value that
does not already exist on the key file at the time its associated
record is entered into the database. If a record is entered
(modified) with a duplicate value, in a <b>unique</b> <b>key</b>
field, the status code S_DUPLICATE is returned and the record is
not entered (or modified).</p>
<p>The <b>optional</b> attribute indicates that the data field is
an <b>optional key</b>. <b>Optional key</b> values are not inserted
into the key file until the application program calls function
<b>d_keystore</b>. Optional keys can be manually deleted using
function <b>d_keydel</b>. When an optional key is modified (through
a <b>d_recwrite</b> or <b>d_crwrite</b> call), the key file will be
updated only if the current value exists in the key file.</p>
<p>Fields declared as <b>struct</b> cannot be nested. Sub-fields of
an arrayed <b>struct</b> field cannot be defined as key fields nor
accessed individually.</p>
<p>Data fields of type <b>DB_ADDR</b> contain the database
addresses of specific record occurrences in the database. Database
addresses can be directly accessed using the currency table access
functions described in section 5.3, "Currency Tables." This allows
you to maintain your own record linkages directly, if desired.</p>
<p>Data fields will be aligned within the record in order to match
the <b>struct</b> field alignment rules followed by your particular
compiler and computer. A <b>ddlp</b> option can be used to disable
this alignment if desired (see section 4.3, "DDL Processor
Operation").</p>
<h5>Examples:</h5>
<pre>
<font color="#0000FF">unique key char code[6];
</font>
</pre>
<p><font size="2">Field <b>code</b> is a character string field of
six characters long (five characters plus one null terminator) that
is defined as a <b>unique key</b>.</font></p>
<pre>
<font color="#0000FF">float balance;
</font>
</pre>
<p><font size="2">Field <b>balance</b> is a floating point field
which, in the checking account database, contains a monetary
value.</font></p>
<pre>
<font color="#0000FF">key int check_date;
</font>
</pre>
<p><font size="2">Key field <b>check_date</b> is used to store a
date in the application-defined Julian format (for example, number
of elapsed days since January 1, 1900). Its values are stored on
the key file in integer order. Thus, check records can be retrieved
in check date order through use of the key retrieval functions (see
section 5.4.1, "Data Retrieval Using Keys").</font></p>
<pre>
<font color="#0000FF">struct {
   double imag;
   double real;
} complex[3];
</font>
</pre>
<p><font size="2">This field statement defines a structure array
field, <b>complex</b>, which stores an array of three complex
numbers composed of an imaginary part and a real part.</font></p>
<pre>
<font color="#0000FF">key long coordinates[3];
</font>
</pre>
<p><b><font size="2">Coordinates</font> is an array of three long
type variables, and is also a key. It may be used to locate an
object on a large three-dimensional grid.</b></p>
<pre>
<font color="#0000FF">int bitmap;
</font>
</pre>
<p><font size="2">Field <b>bitmap</b> is used to store a bitmap of
attribute flags, which are tested using binary operators and masks.
For example, assuming this field was declared in record type
<b>rec, rec.bitmap &amp; 0x0001</b> is non-zero if the low order
bit is set. (Note that <b><i>db.*</i></b> does not directly support
C bit fields.)</font></p>
<pre>
<font color="#0000FF">char byte_array[16][1];
</font>
</pre>
<p><font size="2">Byte array fields are implemented, as in
<b>byte_array</b>, as a two-dimensional character array where the
second dimension is one. This will force the <b><i>db.*</i></b>
runtime to manipulate all 16 bytes of the field rather than
stopping at the first null byte as it does with string
fields.</font></p>
<pre>
<font color="#0000FF">DB_ADDR ptr_array[20];
</font>
</pre>
<p><font size="2">Field <b>ptr_array</b> is an array of type
<b>DB_ADDR</b>. It is used to store an array of the database
addresses of record occurrences that are related to the record type
in which <b>ptr_array</b> is defined. Use of <b>DB_ADDR</b> fields
provides unlimited data organization possibilities to the
programmer. However, these alternatives should only be used in
those rare instances when the standard capabilities provided by
keys and sets are insufficient for a particular
requirement.</font></p>
<pre>
<font color="#0000FF">optional key struct {
   char last_name[21];
   char first_name[21];
   char initial[2];
} name;
</font>
</pre>
<p><font size="2"><b>Name</b> is a <b>struct</b> field to contain
person names and is composed of three string fields for the last
and first names and the middle initial. <b>Last_name</b> is the
first field specified since, because <b>name</b> is a key field,
the last name can be used in a partial key search to find, for
example, all the Smiths on file. Thus, the order of the fields in a
keyed <b>struct</b> field specifies the major and minor sort
sequences for the key on the key file.</font></p>
<p>This field is defined as an <b>optional key</b>. Optional keys
are often used to defer the overhead associated with storing keys
to a time when the system is less busy. For example, it might be
that the record which contains <b>name</b> needs to be stored as
rapidly as possible during the day. At night a batch program can be
run to create the optional keys.</p>
<h4><a name="Compound" id="Compound"></a>Compound Key Fields</h4>
<p><b><font size="2">Syntax:</font></b></p>
<pre>
<font color=
"#0000FF">compound <i>[</i>optional<i>] [</i>unique<i>]</i> key <i>keyname</i> {
   <i>fldname</i> <i>[</i> <u>asc</u><i>[</i>ending<i>]</i> | desc<i>[</i>ending<i>] ]</i> ;
   ...
}
</font>
</pre>
<h5>Description:</h5>
<p><font size="2">The preceding syntax is used to define a compound
key field named <i>keyname</i>. Compound keys are key field
definitions consisting of any combination of fields (not
necessarily contiguous) from a given record. Each sub-field of the
compound key can be specified to be sorted in either ascending
(default) or descending sequence. Compound keys differ from normal
key fields in that they do not define additional data fields in the
record. By using compound keys, you can have a field appear in
multiple keys within a record, without needing to duplicate the
field's value in the data file.</font></p>
<p>The compound key specifications must follow all other field
statements in a record declaration. The order in which the
sub-fields are specified determines the major and minor sort
sequences. The <i>fldname</i> must be the name of a field that is
defined in the record and is not defined as a <b>struct</b>. If the
<b>optional</b> qualifier is specified, the key will only be stored
when <b>d_keystore</b> is called. Otherwise, the key is created
when the record is created. All of the key functions that apply to
normal key fields also apply to compound keys.</p>
<p><b>ddlp</b> will create in the <b>dbname.h</b> file a
<b>struct</b> declaration named <i>keyname</i> for each compound
key defined in the schema, similar to the <b>struct</b>
declarations associated with records. These can be used in
conjunction with the key manipulation functions of the
<b><i>db.*</i></b> runtime library.</p>
<p>Because of the nature of compound keys, records containing them
can only be created using function <b>d_fillnew</b> (not
<b>d_makenew).</b>).</p>
<h5>Examples:</h5>
<pre>
<font color="#0000FF">compound key tr_key {
   trdate descending;
   vendid ascending;
}
compound key ven_chks {
   vendid;
   checkno;
}
</font>
</pre>
<p><font size="2">Assume that a record type called trans
(transaction) contains two compound key definitions. Key
<b>tr_key</b> is composed of fields <b>trdate</b> and
<b>vendid</b>. Scanning through transaction records by
<b>tr_key</b> would produce a sorted list in descending transaction
date order, and ascending vendor id order within each date. Key
<b>ven_chks</b> consists of two fields: <b>vendid</b> and
<b>checkno</b>. Scanning through transaction records by
<b>ven_chks</b> would give a sorted list in ascending vendor id
order, and in ascending check number order within each
vendor.</font></p>
<h3><a name="Set" id="Set"></a>4.2.7 Set Declarations</h3>
<p><b><font size="2">Syntax:</font></b></p>
<pre>
<i><font color=
"#0000FF">[</font> bitmap | blob | varilen ] set setname {
   order { asc[ending] | desc[ending] | first | last | next } 
   owner recname ;
   member recname [ by fldname [, fldname...] ];
   ...
}
</i>
</pre>
<h5>Description:</h5>
<p><font size="2">Set declarations define explicit, one-to-many
relationships between record types. Sets are implemented as a
linked list of member record instances connected to a single
instance of an owner record, which serves as the root or head of
the list (see "Set and Member Pointers" in section 14.2.2, "Data
File Organization"). The order in which member records are inserted
into this list is specified in the <b>set order</b>
clause.</font></p>
<p>Possible set orderings are defined as follows:</p>
<table border="0" cellpadding="7" cellspacing="0" width="542">
<tr>
<td valign="top" width="21%">
<p><b><font size="2">first</font></b></p>
</td>
<td valign="top" width="79%">