rm_ch3.htm

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

<pre>
<font color="#0000FF">int rtype;
   ...
/* check consistency of database */
d_cotype(HAS_PUBLISHED, &amp;rtype, task, CURR_DB);
if ( rtype != AUTHOR )
   pr_dberror();
...</font>
</pre>
<h4>See Also</h4>
<p><b><font size="2">d_cmtype, d_crtype</font></b></p>
<p>&nbsp;</p>
<hr>
<h3><a name="d_crget" id="d_crget"></a>d_crget</h3>
<p><font size="2">Get database address of current record</font></p>
<h4>Prototypes</h4>
<p><font size="2">int <b>d_crget</b>(DB_ADDR *<i>dba</i>, DB_TASK
*<i>task</i>, int <i>dbn</i>)</font></p>
<h4>Parameters</h4>
<p><font size="2">dba<br>
A pointer to a DB_ADDR variable that receives the database address
of the current record.</font></p>
<p>task<br>
A pointer to a DB_TASK structure.</p>
<p>dbn<br>
The database number.</p>
<h4>Description</h4>
<p><font size="2">This function copies the database address of the
current record into the database address variable to which
<i>dba</i> points. If the current record is null (NULL_DBA), the
error code S_NOCR is returned as a status (that is, <b>dberr</b> is
not called), and <i>*dba</i> will be set to NULL_DBA. This function
is used in conjunction with the <b>d_crset</b> function for saving
and restoring the current record.</font></p>
<blockquote><b><i>Note:</i></b> If the record type of the current
record is timestamped, you should also call function <b>d_gtscr</b>
to get its last access timestamp. When <b>d_crset</b> later
restores the current record, function <b>d_stscr</b> should also be
called to restore the last access timestamp associated with that
current record.</blockquote>
<h4>Currency Changes</h4>
<p><font size="2">None.</font></p>
<h4>Locking Requirements</h4>
<p><font size="2">None.</font></p>
<h4>Return Codes</h4>
<p><font size="2">S_NOCR<br>
The current record is null. Returned as a status code rather than
an error (that is, <b>dberr</b> is not called).</font></p>
<h4>Example</h4>
<pre>
<font color="#0000FF">DB_ADDR save_dba;
   ...
/* save current record for later retrieval */
d_crget(&amp;save_dba, task, CURR_DB);
   ...
/* later, retrieve saved record */
d_crset(&amp;save_dba, task, CURR_DB);
d_recread(&amp;irec, task, CURR_DB);
   ...</font>
</pre>
<h4>See Also</h4>
<p><b><font size="2">d_crset, d_csmget, d_csmset, d_csoget,
d_csoset, d_gtscm, d_gtsco, d_gtscr, d_stscm, d_stsco,
d_stscr</font></b></p>
<p>&nbsp;</p>
<hr>
<h3><a name="d_crread" id="d_crread"></a>d_crread</h3>
<p><font size="2">Read data from field of current record</font></p>
<h4>Prototypes</h4>
<p><font size="2">int <b>d_crread</b>(long <i>FIELD</i>, void
*<i>value</i>, DB_TASK *<i>task</i>, int <i>dbn</i>)</font></p>
<h4>Parameters</h4>
<p><font size="2">FIELD<br>
The field type read from the current record.</font></p>
<p>value<br>
A pointer to the data area that receives the field contents.</p>
<p>task<br>
A pointer to a DB_TASK structure.</p>
<p>dbn<br>
The database number.</p>
<h4>Description</h4>
<p><font size="2">The function <b>d_crread</b> copies the contents
of <i>FIELD</i> from the current record to the area to which
<i>value</i> points. If <i>FIELD</i> is an array field, the entire
array is read. Elements of an array cannot be read
individually.</font></p>
<h4>Currency Changes</h4>
<p><font size="2">This function updates the timestamp for the
current record in the currency table from the database.</font></p>
<h4>Locking Requirements</h4>
<p><font size="2">Allowed with no locks, but old or deleted data
may be read. Use a read lock to ensure that only current data is
read.</font></p>
<h4>Return Codes</h4>
<p><font size="2">S_DELETED<br>
The record has been deleted.</font></p>
<p>S_INVFLD<br>
Invalid field type. Either you did not pass a field type or you
passed a field type that is not in the current record.</p>
<p>S_NOCR<br>
The current record is null.</p>
<h4>Example</h4>
<pre>
<font color="#0000FF">char name[32];   /* author name */
   ...
/* find author of info record */
d_findco(HAS_PUBLISHED, task, 2);
d_crread(NAME, name, task, 2);</font>
</pre>
<h4>See Also</h4>
<p><b><font size="2">d_csmread, d_csoread</font></b></p>
<p>&nbsp;</p>
<hr>
<h3><a name="d_crset" id="d_crset"></a>d_crset</h3>
<p><font size="2">Set database address of current record</font></p>
<h4>Prototypes</h4>
<p><font size="2">int <b>d_crset</b>(DB_ADDR *<i>dba</i>, DB_TASK
*<i>task</i>, int <i>dbn</i>)</font></p>
<h4>Parameters</h4>
<p><font size="2">dba<br>
A pointer to a DB_ADDR variable that will become the current
record.</font></p>
<p>task<br>
A pointer to a DB_TASK structure.</p>
<p>dbn<br>
The database number.</p>
<h4>Description</h4>
<p><font size="2">This function assigns the current record from the
database address variable to which <i>dba</i> points. It is used in
conjunction with the <b>d_crget</b> function for saving and
restoring the current record.</font></p>
<blockquote><b><i>Note:</i></b> If the record type of the current
record is timestamped, you should also call function <b>d_stscr</b>
to set the last access timestamp for the record.</blockquote>
<h4>Currency Changes</h4>
<p><font size="2">curr_rec = *<i>dba</i>;</font></p>
<h4>Locking Requirements</h4>
<p><font size="2">Allowed with no locks, but may read old or
deleted data. Use read lock on <i>SET</i> to ensure current
data.</font></p>
<h4>Return Codes</h4>
<p><font size="2">S_DELETED<br>
The record has been deleted since the saving of this database
address.</font></p>
<p>S_INVADDR<br>
Invalid database address. You may have passed the database address
itself rather than a pointer to it.</p>
<h4>Example</h4>
<pre>
<font color="#0000FF">DB_ADDR save_dba;
   ...
/* save current record for later retrieval */
d_crget(&amp;save_dba, task, MY_DBN);
   ...
/* later, retrieve saved record */
d_crset(&amp;save_dba, task, MY_DBN);
d_recread(&amp;irec, task, MY_DBN);
</font>
</pre>
<h4>See Also</h4>
<p><b><font size="2">d_crget, d_csmget, d_csmset, d_csoget,
d_csoset, d_gtscm, d_gtsco, d_gtscr, d_stscm, d_stsco,
d_stscr</font></b></p>
<p>&nbsp;</p>
<hr>
<h3><a name="d_crstat" id="d_crstat"></a>d_crstat</h3>
<p><font size="2">Test timestamp status of current
record</font></p>
<h4>Prototypes</h4>
<p><font size="2">int <b>d_crstat</b>(DB_TASK *<i>task</i>, int
<i>dbn</i>)</font></p>
<h4>Parameters</h4>
<p><font size="2">task<br>
A pointer to a DB_TASK structure.</font></p>
<p>dbn<br>
The database number.</p>
<h4>Description</h4>
<p><font size="2">This function tests the status of the timestamp
in the currency table of the current record against the timestamp
on the disk. The record type of the current record must have been
specified as timestamped in the DDL schema file for the database.
The timestamp status is returned as defined below.</font></p>
<h4>Currency Changes</h4>
<p><font size="2">None.</font></p>
<h4>Locking Requirements</h4>
<p><font size="2">Allowed with no locks, but may read old or
deleted data. Use a read lock on <i>REC</i> to ensure current
data.</font></p>
<h4>Return Codes</h4>
<p><font size="2">S_DELETED<br>
The current record has been deleted since it was last
accessed.</font></p>
<p>S_OKAY<br>
The current record has not been changed by another user since it
was last accessed.</p>
<p>S_TIMESTAMP<br>
The current record type is not timestamped.</p>
<p>S_UPDATED<br>
The current record was modified since last accessed.</p>
<h4>Example</h4>
<pre>
<font color="#0000FF">if (d_crstat(task, CURR_DB) == S_OKAY )
{
   d_recwrite(&amp;info, task);
   ...
}</font>
</pre>
<h4>See Also</h4>
<p><b><font size="2">d_cmstat, d_costat, d_csstat, d_gtscr,
d_recstat, d_stscr</font></b></p>
<p>&nbsp;</p>
<hr>
<h3><a name="d_crtype" id="d_crtype"></a>d_crtype</h3>
<p><font size="2">Get record type of current record</font></p>
<h4>Prototypes</h4>
<p><font size="2">int <b>d_crtype</b>(int *<i>rectype</i>, DB_TASK
*<i>task</i>, int <i>dbn</i>)</font></p>
<h4>Parameters</h4>
<p><font size="2">rectype<br>
A pointer to an integer variable that contains the returned record
type.</font></p>
<p>task<br>
A pointer to a DB_TASK structure.</p>
<p>dbn<br>
The database number.</p>
<h4>Description</h4>
<p><font size="2">This function copies the record type of the
current record into the integer variable to which <i>rectype</i>
points.</font></p>
<h4>Currency Changes</h4>
<p><font size="2">None.</font></p>
<h4>Locking Requirements</h4>
<p><font size="2">Allowed with no locks, but may read old or
deleted data. Use a read lock to ensure current data.</font></p>
<h4>Return Codes</h4>
<p><font size="2">S_NOCR<br>
The current record is null.</font></p>
<h4>Example</h4>
<pre>
<font color="#0000FF">int rtype;
   ...
d_crtype(&amp;rtype, task, TIMS_DBN);
if ( rtype == AUTHOR )
   pr_author();
else
{
   if ( rtype == INFO )
      pr_info();
}
   ...</font>
</pre>
<h4>See Also</h4>
<p><b><font size="2">d_cmtype, d_cotype</font></b></p>
<p>&nbsp;</p>
<hr>
<h3><a name="d_crwrite" id="d_crwrite"></a>d_crwrite</h3>
<p><font size="2">Write to field in current record</font></p>
<h4>Prototypes</h4>
<p><font size="2">int <b>d_crwrite</b>(long <i>FIELD</i>, void
*<i>value</i>, DB_TASK *<i>task</i>, int <i>dbn</i>)</font></p>
<h4>Parameters</h4>
<p><font size="2">FIELD<br>
The field type from the current record.</font></p>
<p>value<br>
A pointer to the new value.</p>
<p>task<br>
A pointer to a DB_TASK structure.</p>
<p>dbn<br>
The database number.</p>
<h4>Description</h4>
<p><font size="2">Function <b>d_crwrite</b> writes the data pointed
to by <i>value</i> to data field <i>FIELD</i> in the current
record. If <i>FIELD</i> is a key field, the key will automatically
be updated. If <i>FIELD</i> is used as a sort field of an ascending
or descending ordered set, the record's position in the set will
automatically be adjusted accordingly. If <i>FIELD</i> is an array
field, the entire array is written. Elements of an array cannot be
written individually. This function cannot be used to modify fields
that constitute a compound key. Call <b>d_recwrite</b> to modify
compound keys.</font></p>
<h4>Currency Changes</h4>
<p><font size="2">None.</font></p>
<h4>Locking Requirements</h4>
<p><font size="2">Write lock on record type of current record. If
<i>FIELD</i> is named in a sorted set and is being changed, a write
lock will be required on the data files involved in the
set.</font></p>
<h4>Return Codes</h4>
<p><font size="2">S_COMKEY<br>
Records containing compound keys cannot be updated.</font></p>
<p>S_DUPLICATE<br>
Duplicate key.</p>
<p>S_INVFLD<br>
Invalid field type. Either you did not pass a field type or you
passed a field type that is not in the current record.</p>
<p>S_ISCOMKEY<br>
Illegal operation using a compound key field.</p>
<p>S_NOCR<br>
The current record is null.</p>
<p>S_NOTLOCKED<br>
Record type containing field is not locked. If <i>FIELD</i> is used
in a sorted set, the set must be locked.</p>
<p>S_TRNOTACT<br>
Transaction not active. In shared mode, changes can only be made
from within a transaction.</p>
<h4>Example</h4>
<pre>
<font color="#0000FF">/* Change info record id_code*/
chg_id(old_id, new_id)
char *old_id;
char *new_id;
{
   int stat = d_keyfind( ID_CODE, old_id, task, CURR_DB );
   if ( stat == S_OKAY )
      d_crwrite(ID_CODE, new_id, task, CURR_DB);
   else
   {
      if ( stat == S_NOTFOUND )
         printf("id_code %s not found\n", old_id);
   }
   return;
} </font>
</pre>
<h4>See Also</h4>
<p><b><font size="2">d_csmwrite, d_csowrite,
d_recwrite</font></b></p>
<p>&nbsp;</p>
<hr>
<h3><a name="d_csmget" id="d_csmget"></a>d_csmget</h3>
<p><font size="2">Get database address of current member</font></p>
<h4>Prototypes</h4>
<p><font size="2">int <b>d_csmget</b>(int <i>SET</i>, DB_ADDR
*<i>dba</i>, DB_TASK *<i>task</i>, int <i>dbn</i>)</font></p>
<h4>Parameters</h4>
<p><font size="2">SET<br>