ug_ch5c.htm

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

   {
      printf("database(s) not currently available\n");
      exit(1);
   }
}
</font>
</pre>
<p><font size="2">Whether the databases are opened all at once, or
incrementally, they may all be closed with the <b>d_close</b> call.
They may be incrementally closed with the <b>d_iclose</b> call. For
example, after the above opens, the call:</font></p>
<pre>
<font color="#0000FF">d_iclose(1, task);
</font>
</pre>
<p><font size="2">will close the <b>acctsrec</b> database. All
database numbers will shift accordingly (in this case, the database
number for <b>acctspay</b> will shift from two to one). If database
2 (<b>acctspay</b>) was the current database, then database 1
(still <b>acctspay</b>) will be the current database following the
<b>d_iclose</b>.</font></p>
<p>In addition to the current database, a current record is
maintained for each database. Whenever the current database is
changed, the current record for the old database is saved and the
current record for the database that is to be made current is
restored.</p>
<h3><a name="Accessing" id="Accessing"></a>5.9.2 Accessing Multiple
Databases</h3>
<p><font size="2">There are two methods for accessing multiple
databases. Every database-specific function must be called with a
database number (<i>dbn</i>). The <i>dbn</i> may be -1, which
causes the current database to be used. The <b>db.star.h</b> header
file contains a <b>#define</b> constant called CURR_DB that is
equal to -1. The current database may be altered by the
<b>d_iopen</b> or <b>d_setdb</b> functions. Alternatively, the
<i>dbn</i> parameter may be a positive number that explicitly
selects a database. These methods may be used
interchangeably.</font></p>
<p>If only one database is opened, the database number parameter is
still required and must be zero (0) or CURR_DB.</p>
<blockquote>Note<b><i>:</i></b> When a module (that is, a <b>.c</b>
file) is to access multiple databases, care must be taken to ensure
that there are no record, field, or set name conflicts between
those databases. If there are, the compiler will only recognize the
last <b>#define</b> statement from the <b><i>dbname</i>.h</b> files
containing the duplicate names.</blockquote>
<h4>Method 1</h4>
<p><font size="2">In this method, function <b>d_setdb</b> is called
to set the current database. The <i>dbn</i> parameter must be -1
(or its equivalent CURR_DB). An example of this technique
follows.</font></p>
<pre>
<font color="#0000FF">#include "db.star.h"
...

d_open("genledg;acctsrec", "s", task);
   ...
/* enter billing record into acctsrec database */
d_setdb(1, task);
d_fillnew(BILLING, &amp;bill, task, CURR_DB);

/* find and update ledger account in genledg database */
d_setdb(0, task);
d_keyfind(ACCT_ID, bill.gl_id, task, CURR_DB);
d_recread(&amp;glacct, task, CURR_DB);
   ..   /* update gen. ledger account record */
d_recwrite(&amp;glacct, task, CURR_DB);
</font>
</pre>
<h4>Method 2</h4>
<p><font size="2">In this method, the database number is passed as
to the <b><i>db.*</i></b> functions that access or control database
content. An example of this technique follows.</font></p>
<pre>
<font color="#0000FF">d_open("genledg;acctsrec", "s", task);
   ...
/* enter billing record into acctsrec database */
d_fillnew(BILLING, &amp;bill, task, 1);

/* find and update ledger account in genledg database */
d_keyfind(ACCT_ID, bill.gl_id, task, 0);
d_recread(&amp;glacct, task, 0);
   ..   /* update gen. ledger account record */
d_recwrite(&amp;glacct, task, 0);
</font>
</pre>
<h4>Mixed Method</h4>
<p><font size="2">It is possible to use <b>d_setdb</b> to set the
current database, but override it with an explicit database number
when necessary.</font></p>
<pre>
<font color="#0000FF">d_open("genledg;acctsrec", "s", task);
   ...
/* enter billing record into acctsrec database */
d_setdb(0, task);
d_fillnew(BILLING, &amp;bill, task, 1);

/* find and update ledger account in genledg database */
d_keyfind(ACCT_ID, bill.gl_id, task, CURR_DB);
d_recread(&amp;glacct, task, CURR_DB);
   ..   /* update gen. ledger account record */
d_recwrite(&amp;glacct, task, CURR_DB);
</font>
</pre>
<h2><a name="MultipleTasks" id="MultipleTasks"></a>5.10 Multiple
Tasks</h2>
<p><font size="2">An application always has a <i>current state</i>.
This includes such factors as which database is open, the current
record, current set owners and members, record and set locks, and
many other items that represent the situation of the application.
Below is a list of the most significant task-specific
data:</font></p>
<ul>
<li>Whether there is an open database</li>
<li>The DBUSERID</li>
<li>The DBDPATH</li>
<li>The DBFPATH</li>
<li>The CTBPATH</li>
<li>The status of all key files (position, last found value,
etc.)</li>
<li>The database options</li>
<li>The names of renamed files</li>
<li>The default page size of database(s)</li>
<li>The current record</li>
<li>The current set owners</li>
<li>The current set members</li>
<li>The complete data dictionary (or dictionaries, if multiple
databases are open)</li>
<li>The status of all record, set, and key locks</li>
<li>The country table</li>
<li>All in-memory timestamp information</li>
<li>The current records as used by the sequential scanning
functions</li>
<li>The database address of the system record</li>
<li>The transaction id</li>
<li>The transaction log file name</li>
</ul>
<p>A <i>task</i> is a db.* structure used to store state
information, and is established by a call to <b>d_opentask</b>. The
one parameter to this function is a pointer to a pointer of type
DB_TASK. The <b>d_opentask</b> function will allocate a structure
to contain all of the task-specific state information and point the
task pointer to it. The <b>d_closetask</b> function should always
be called to clean up and free all memory allocated by
<b>d_opentask</b>.</p>
<pre>
<font color="#0000FF">#include "db.star.h"
 
main()
{
   DB_TASK *task;

   d_opentask(&amp;task);         /* New task */

   d_open("db", "x", task);   /* Open database in task */
      /* Use the database */
   d_close(task);

   d_closetask(task);         /* Close task, free memory */
}
</font>
</pre>
<p><font size="2">The DB_TASK parameter must be supplied for
(nearly) every <b><i>db.*</i></b> function, and at least one call
must be made to <b>d_opentask</b>. The task parameter is placed
before the database number parameter for those functions that use a
database number. Otherwise, it is the last argument.</font></p>
<p>A <b><i>db.*</i></b> task defines as an independent unit of code
execution, or it could also be referred to as a <i>session</i>. In
addition to maintaining state information, each task may represent
a different transaction. This is a deliberately broad definition.
You can program multiple database tasks within a single process.
You also may open a task for multiple <i>threads</i> within a
process. The <b><i>db.*</i></b> functions are thread-safe, provided
one task is used only within one thread.</p>
<p>A separate task can be opened for the purpose of accessing
additional databases in a different open mode. For example, you may
have a database open in shared mode, but then want to open an
additional database exclusively.</p>
<p>The following code shows a simple single-process application
using two contexts.</p>
<pre>
<font color="#0000FF">#include "db.star.h"

DB_TASK *ControlTask;
DB_TASK *ClientTask;

main()
{
   struct client cl2;
   d_opentask(&amp;ControlTask);
   d_open("ctrl", "x", ControlTask);
   /* Initialize control database */
   ...
   d_opentask(&amp;ClientTask);
   d_open("client1;client2;client3", "s", ClientTask);
   ...
   /* Access client3 database */
   d_fillnew(CLIENT, &amp;cl2, ClientTask, 2);
   ...
   d_close(ClientTask);
   d_closetask(ClientTask);
   ...
   d_close(ControlTask);
   d_closetask(ControlTask);
}
</font>
</pre>
<p><font size="2">In this example, two variables of type *DB_TASK
are defined. One task is created to open a single control database
in exclusive access mode. Then a second task is created to open a
group of shared databases, each representing one client. One or
more client database may be updated by a transaction within the
client task.</font></p>
<p>There are two functions that do not take a task parameter. They
are:</p>
<div style="margin-left: 4em">
<p>d_decode_dba</p>
<p>d_encode_dba</p>
</div>
<h2><a name="International" id="International"></a>5.11
International Character Sets</h2>
<p><font size="2">In <b><i>db.*</i></b>, support for international
character sets provides the ability to redefine the display and
collating sequence of any character in the ASCII character set. An
additional effect is the ability to ignore the case of letters in
sorting. For example, the German "&Auml;" is just a different way
of writing "AE" and needs to be sorted as such. However, the
standard ASCII tables, which define the normal sort orders, put the
letter "A" at 65 and the "&Auml;" at well over 127 (depending on
the code page being used by your computer), causing the normal sort
order to be far from what is desired.</font></p>
<p>At the center of this capability is the country table. The
country table contains one entry for each character that is to be
recognized as a displayable character, or that is to be sorted in
an order other than its normal sequence. An optional country table
directive allows all lowercase letters to be mapped into uppercase
letters during sorting.</p>
<p>The country table is contained in a file named
<b>db.star.ctb</b>. <b><i>db.*</i></b> will read the country table
file, if present, during each database open. The country table file
is found by searching the directory indicated in the CTBPATH
environment variable (the country table path can also be
established with the <b>d_ctbpath</b> function or the
<b>db.star.ini</b> file). If CTBPATH has not been set, then the
current directory will be searched.</p>
<p>Note: A database that is built with a particular country table
must always use the same country table, because sorted sets and
keys will appear to be corrupted to <b><i>db.*</i></b> because they
are out of order if the table is changed or omitted.</p>
<p>When a country table is being used for sorting purposes, single
character fields will be compared using the country table when they
are declared as signed (e.g.,<b>char my_field;</b>). Unsigned
character fields will be sorted without the use of the country
table.</p>
<p>The country table has the following format:</p>
<p>w,x,y,zz<br>
w,x,y,zz<br>
...</p>
<p>where:</p>
<table cellspacing="0" border="0" cellpadding="7" width="528">
<tr>
<td width="6%" valign="top">
<p><font size="2"><b>w</b></font></p>
</td>
<td width="94%" valign="top">
<p><font size="2">= Input character as stored on disk</font></p>
</td>
</tr>
<tr>
<td width="6%" valign="top">
<p><font size="2"><b>x</b></font></p>
</td>
<td width="94%" valign="top">
<p><font size="2">= Output character as displayed</font></p>
</td>
</tr>
<tr>
<td width="6%" valign="top">
<p><font size="2"><b>y</b></font></p>
</td>
<td width="94%" valign="top">
<p><font size="2">= Subsort value, described below (value 0 or
1)</font></p>
</td>
</tr>
<tr>
<td width="6%" valign="top">
<p><font size="2"><b>z</b></font></p>
</td>
<td width="94%" valign="top">
<p><font size="2">= Sort-as character(s) (up to two)</font></p>
</td>
</tr>
</table>
<p><font size="2">The input character, <b>w</b>, will be displayed
as the character <b>x</b> in <b>ida</b>, <b>datdump</b>, and
<b>keydump,</b> since these utilities interpret the data. It will
be sorted as though it were <b>z</b>. The <b>y</b> (or subsort)
value indicates what to do when this character sorts to a value
equal to an existing character. The <b>z</b> (or sort-as) field can
contain one or two characters. If it contains two characters, then
the input character will be sorted as though it were two
characters. By default any character not listed as an input
character within the country table gets sorted and displayed as
itself.</font></p>
<p>When two or more characters are mapped to the same subsort
character(s), they become members of a grouping. The subsort value
controls how characters in a group are subsorted within the group.
A zero means that the two input characters will be treated as
identical. A one means that the input characters are considered
part of the same group, but are sorted by ASCII value within the
group.</p>
<p>As an example, look at the country table and data below:</p>
<table cellspacing="0" border="0" cellpadding="7" width="460">
<tr>
<td width="18%" valign="top">
<p><font size="2"><b>a,a,0,A</b></font></p>
</td>
<td width="82%" valign="top">
<p><font size="2"><b>ab1</b></font></p>
</td>
</tr>
<tr>
<td width="18%" valign="top">
<p><font size="2"><b>b,b,0,B</b></font></p>
</td>
<td width="82%" valign="top">
<p><font size="2"><b>AB2</b></font></p>
</td>
</tr>
<tr>
<td width="18%" valign="top">
<p><font size="2"><b>c,c,0,C</b></font></p>
</td>
<td width="82%" valign="top">
<p><font size="2"><b>AA3</b></font></p>
</td>
</tr>
<tr>
<td width="18%" valign="top">
<p><font size="2"><b>...</b></font></p>
</td>
<td width="82%" valign="top">
<p><font size="2"><b>aa4</b></font></p>
</td>
</tr>
<tr>