ug_ch5c.htm

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

are used as sort fields in an ascending or descending set, and
function <b>d_recwrite</b> is used to modify the contents of both
fields, better performance will result if you first disconnect the
record from the set before calling <b>d_recwrite</b> and then
reconnect the record after returning from <b>d_recwrite</b>.
Otherwise, <b><i>db.*</i></b> will still adjust the position of the
set for each field.</blockquote>
<p><font size="2">Optional keys are automatically modified if a key
existed for the old value when its field was modified. If a key
entry did not exist for the old value, none will be created for the
new value. However, the field's value in the record is
updated.</font></p>
<h2><a name="Deletion" id="Deletion"></a>5.7 Data Deletion</h2>
<p><font size="2">The functions involved in data deletion appear in
Table 5-7.</font></p>
<p align="center"><b>Table 5-7. Data Deletion Functions</b></p>
<table cellspacing="0" border="0" cellpadding="7" width="542">
<tr>
<td width="39%" valign="top">
<p><font size="2"><b>d_delete</b>(<i>task, dbn</i>)</font></p>
</td>
<td width="61%" valign="top">
<p><font size="2">Delete current record.</font></p>
</td>
</tr>
<tr>
<td width="39%" valign="top">
<p><font size="2"><b>d_keydel</b>(<i>KEY</i>, <i>task,
dbn</i>)</font></p>
</td>
<td width="61%" valign="top">
<p><font size="2">Delete optional key value.</font></p>
</td>
</tr>
<tr>
<td width="39%" valign="top">
<p><font size="2"><b>d_discon</b>(<i>SET</i>, <i>task,
dbn</i>)</font></p>
</td>
<td width="61%" valign="top">
<p><font size="2">Disconnect current member from set.</font></p>
</td>
</tr>
<tr>
<td width="39%" valign="top">
<p><font size="2"><b>d_disdel</b>(<i>task, dbn</i>)</font></p>
</td>
<td width="61%" valign="top">
<p><font size="2">Disconnect current record from all sets and
delete it.</font></p>
</td>
</tr>
</table>
<p><font size="2">A record can only be deleted if it is not
connected as an owner or member of any sets. The general deletion
procedure is, therefore, to disconnect a record from all sets for
which it is a member and disconnect all members from sets owned by
that record, and then delete the record. All disconnections and the
delete can be performed with one call by using function
<b>d_disdel</b>.</font></p>
<p>Function <b>d_keydel</b> is used to delete the key entry of an
optional key field in the current record. The field value in the
record itself, however, does not change. All key entries, including
optional keys, are deleted from their respective key files when a
record is deleted using either function <b>d_delete</b> or
<b>d_disdel</b>.</p>
<p>Below is the code for function <b>del_info</b>, which deletes an
<b>info</b> record from the <b>tims</b> database.</p>
<pre>
<font color="#0000FF">#include &lt;stdio.h&gt;
#include "db.star.h"
#include "tims.h"

/* Delete technical information records from tims database */
del_info()
{
   struct info irec;   
   long count;
   char id[SIZEOF_ID_CODE], name[SIZEOF_NAME];

   /* find info to be deleted */
   printf("id_code: " );
   gets(id);
   if (d_keyfind(ID_CODE, id, task, CURR_DB) == S_NOTFOUND)
   {
      printf("id_code %s not on file\n", id);
      return;
   }
   d_recread(&amp;irec, task, CURR_DB);

   /* get author name */
   d_findco(HAS_PUBLISHED, task, CURR_DB);
   d_crread(NAME, name, task, CURR_DB);
   ... /* confirm delete request */
   ... /* disconnect and delete any listed articles */
   ... /* disconnect and delete borrowers */
   
   /* disconnect and delete abstract */
   d_setom(ABSTRACT, HAS_PUBLISHED, task, CURR_DB);
   while (d_findfm(ABSTRACT, task, CURR_DB) == S_OKAY)
   {
      d_discon(ABSTRACT, task, CURR_DB);
      d_delete(task, CURR_DB);
   }
   
   /* disconnect and delete intersect and (possibly) key word */
   d_setom(INFO_TO_KEY, HAS_PUBLISHED, task, CURR_DB);
   while (d_findfm(INFO_TO_KEY, task, CURR_DB) == S_OKAY)

   {
      d_discon(INFO_TO_KEY, task, CURR_DB);
      d_setmr(KEY_TO_INFO, task, CURR_DB);
      d_discon(KEY_TO_INFO, task, CURR_DB);
      d_delete(task, CURR_DB);
      d_members(KEY_TO_INFO, &amp;count, task, CURR_DB);
      if (count == 0L) 
      {
         /* delete key word */
         d_setro(KEY_TO_INFO, task, CURR_DB);
         d_delete(task, CURR_DB);
      }
   }
   /* disconnect info record from author and delete */
   d_discon(HAS_PUBLISHED, task, CURR_DB);
   d_delete(task, CURR_DB);

   /* delete author too, if he has no other pubs */
   d_members(HAS_PUBLISHED, &amp;count, task, CURR_DB);
   if (count == 0L) 
   {
      d_setmo(AUTHOR_LIST, HAS_PUBLISHED, task, CURR_DB);
      d_discon(AUTHOR_LIST, task, CURR_DB);
      d_delete(task, CURR_DB);
   }
}
</font>
</pre>
<p><font size="2">Function <b>del_info</b> first prompts the user
for the id code of the <b>info</b> record to be deleted. If the id
code is on file, the <b>info</b> record contents are read into
variable <b>irec</b>, the author name is found from the owner of
<b>info</b> through set <b>has_published</b>, and a confirmation of
the delete is requested by displaying the data (not
shown).</font></p>
<p>If the info item to be deleted is a journal or magazine, any
articles contained in it must also be deleted. This is done first
(not shown).</p>
<p>Next, any <b>borrower</b> records that are members of that info
item are disconnected and deleted (also not shown).</p>
<p>The abstract is deleted by repeatedly disconnecting and deleting
the first member of the <b>abstract</b> set until there are no more
members. Note that the current owner of <b>abstract</b> had to be
initially set to the <b>info</b> record that is the current member
of <b>has_published</b> (as established by the earlier
<b>d_findco</b>(HAS_PUBLISHED) call).</p>
<p>Deletion of the key words associated with the <b>info</b> record
is similar, but more complicated. Intersect records are deleted
just like the abstract was, except that they need to be
disconnected from set <b>key_to_info</b> as well as from set
<b>info_to_key</b>. If the <b>key_to_info</b> set is empty after
deleting the intersect record, the <b>key_word</b> must also be
deleted. Note the call to <b>d_setro</b> to set the current record
from the current owner of set <b>key_to_info</b> (that is, the
<b>key_word</b> record). This is necessary because function
<b>d_delete</b> deletes the current record, and the <b>key_word</b>
record was not the current record.</p>
<p>The <b>info</b> record is disconnected from its final set,
<b>has_published</b>, and can now be deleted. Function
<b>d_discon</b> disconnects the current member from the specified
set and makes the deleted record the current record.</p>
<p>One last task is a check to see if the author has other
<b>info</b> items in the database. If not, then the <b>author</b>
record is disconnected from set <b>author_list</b> and is deleted
as well.</p>
<h2><a name="Error" id="Error"></a>5.8 Database Error
Reporting</h2>
<p><font size="2">All <b><i>db.*</i></b> runtime functions return
an integer database status code as the value of the function. These
status codes are classified into the following three
categories:</font></p>
<table cellspacing="0" border="0" cellpadding="7" width="529">
<tr>
<td width="27%" valign="top">
<p><font size="2"><b>Function Statuses</b></font></p>
</td>
<td width="73%" valign="top">
<p><font size="2">These indicate normal statuses, such as record
not found or end of set. Function status codes range from 0 to
99.</font></p>
</td>
</tr>
<tr>
<td width="27%" valign="top">
<p><font size="2"><b>User</b> <b>Errors</b></font></p>
</td>
<td width="73%" valign="top">
<p><font size="2">These correspond to programming errors, such as
passing a record type to a function with a set type as its
argument. User error codes range from -1 to -99.</font></p>
</td>
</tr>
<tr>
<td width="27%" valign="top">
<p><font size="2"><b>System</b> <b>Errors</b></font></p>
</td>
<td width="73%" valign="top">
<p><font size="2">These errors occur when <b><i>db.*</i></b>
detects an abnormal database condition, such as no more file space.
System error codes range from -900 to -999.</font></p>
</td>
</tr>
</table>
<p><font size="2">When user errors are reported, either the
arguments to a <b><i>db.*</i></b> function are not correct or the
database environment has not been properly set up for the called
function. For example, function <b>d_csoread</b> will return user
error S_NOCO if the current owner of the specified set is NULL_DBA.
All user errors in a <b><i>db.*</i></b> program should be
corrected.</font></p>
<p>Only one system error is recoverable. The system error S_NOSPACE
is returned when there is no more space available on the disk, but
it is recoverable. A recovery technique is described with function
<b>d_trend</b> in the <i><b>db.*</b> Reference Manual</i>. All
other system errors (and sometimes even error S_NOSPACE) indicate
that a serious error has occurred and processing should be
terminated immediately. Usually, these errors result from an
application programming error that corrupts the <b><i>db.*</i></b>
runtime environment. These errors are caused by improper use of
pointers, by memory mismanagement, and by operations on strings
that are not terminated by a null byte. The most common pointer
error is passing a function argument by value rather than by
reference (that is, rather than by using a pointer).</p>
<p>The standard <b><i>db.*</i></b> C header file, <b>db.star.h</b>,
contains constant definitions for all status and error codes that
can be returned from a <b><i>db.*</i></b> function. This file
should be <b>#include</b>d in each C source file that uses
<b><i>db.*</i></b>. Detailed explanations for each status code can
be found in the <b><i>db.*</i> Reference Manual</b>.</p>
<p>The internal function <b>dberr</b> is automatically called by
the <b><i>db.*</i></b> runtime functions whenever a user or system
error occurs. Whenever a user or system error occurs, this version
of <b>dberr</b> will display the error code and description, and
then prompt for a &lt;Return&gt; to continue. You may need to
customize the error reporting to make it more suitable for the user
interface style of your application.</p>
<p>The recommended method is to use <b>d_set_dberr</b>, which
allows you to supply the <b><i>db.*</i></b> runtime with a callback
function to call when reporting an error. After calling
<b>d_set_dberr</b>, the <b>dberr</b> function will call the
function you supply, instead of printing the message itself. Your
error reporting function should be declared as follows:</p>
<pre>
<font color="#0000FF">void EXTERNAL_FIXED my_dberr(int, char *);
</font>
</pre>
<p><font size="2">The first parameter is the error number, and the
second parameter is the textual message that <b>dberr</b> would
have printed regarding the error. The void EXTERNAL_FIXED preceding
the function name ensures that its declaration will match that
expected by <b><i>db.*</i></b>. The macros are defined in
<b>db.star.h</b>. Use the function as follows:</font></p>
<pre>
<font color="#0000FF">#define "db.star.h"

void EXTERNAL_FIXED my_dberr(int, char *);
...
main()
{
   ...
   d_set_dberr(my_dberr, task);
   ...
}
void EXTERNAL_FIXED my_dberr(int err_no, char *err_msg)
{
   /* Special handling of some error codes here */
   if (err_no &lt;= -900)
   {
      /* take care in calling d_close, because it may
         call dberr again */
      exit(err_no);
   }
   ...
   /* You may choose to ignore some codes */
   if (err_no == S_NOCM) 
      return;
   ...
   /* Report errors */
   ...
   return;
}
</font>
</pre>
<h2><a name="Multiple" id="Multiple"></a>5.9 Multiple Database
Access</h2>
<p><font size="2">Using <b><i>db.*</i></b>, more than one database
can be open and accessed within a single application program. This
capability has been implemented with very little performance impact
for those <b><i>db.*</i></b> applications that only need to access
a single database. Section 4.4.1, "Logical Design Considerations,"
described some of the uses of multiple database access from a
database design standpoint. This section explains how to open and
access multiple databases.</font></p>
<h3><a name="Opening" id="Opening"></a>5.9.1 Opening Multiple
Databases</h3>
<p><font size="2">To open more than one database, the desired
database names are passed, separated by a semicolon (;), as the
first argument to function <b>d_open</b> or <b>d_iopen</b>. No
white space (that is, spaces, tabs, etc.) should be embedded
between the database names. An improperly constructed list will
result in error S_INVDB being returned. Any number of databases may
be opened, limited only by the amount of available memory. All
opened databases are opened in the same mode. It is not possible to
open some in exclusive access and others in shared or one-user
access. You can, however, open all databases in shared mode and
then place exclusive locks on all of the files in one or more
databases.</font></p>
<p>A currency value is defined called current database. The current
database will be zero (that is, the first one listed) after
execution of <b>d_open</b>. See the example below:</p>
<pre>
<font color=
"#0000FF">if ((status=d_open("genledg;acctsrec;acctspay", "s", task)) != S_OKAY) {
   if (status == S_UNAVAIL)
      printf("database(s) not currently available\n");
   exit(1);
}
</font>
</pre>
<p><font size="2">Here, the databases named <b>genledg</b>,
<b>acctsrec</b> and <b>acctspay</b> are all opened for shared
access. Each is assigned a number by the system in order from left
to right, beginning with zero. Thus database 0 is <b>genledg</b>,
database 1 is <b>acctsrec</b>, and database 2 is <b>acctspay</b>.
These numbers are used to specify to the runtime functions which
database to access. After the <b>d_open</b> call, database
<b>genledg</b> will be the current database.</font></p>
<p>It is not necessary to open all databases at one time. The
function <b>d_iopen</b> will incrementally open a new (set of)
database(s) in the same open mode as the already opened databases.
The following statements would be equivalent to the example above,
except that the current database will be two instead of zero:</p>
<pre>
<font color=
"#0000FF">if ((status = d_open("genledg", "s", task)) != S_OKAY ||
    (status = d_iopen("acctsrec", task)) != S_OKAY    ||
    (status = d_iopen("acctspay", task)) != S_OKAY)) 
{
   if (status == S_UNAVAIL)