rm_ch3.htm

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

The set type for which the current member's database address is to
be returned.</font></p>
<p>dba<br>
A pointer to a DB_ADDR variable that receives the database address
of the current member.</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 member of <i>SET</i> into the database address variable to
which <i>dba</i> points. This function is used in conjunction with
the <b>d_csmset</b> function for saving and restoring the current
member of a set. If the current member is null (NULL_DBA), code
S_NOCM is returned as a status (that is, <b>dberr</b> is not
called) and <i>*dba</i> will receive the null database
address.</font></p>
<blockquote><b><i>Note:</i></b> If the record type of the current
member is timestamped, you should also call function <b>d_gtscm</b>
to get the last access timestamp for the current member. Later,
when <b>d_csmset</b> restores the current member, function
<b>d_stscm</b> should also be called to restore the last access
timestamp associated with that current member 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_INVSET<br>
Invalid set type. Probably passed a record or field type instead of
a set type.</font></p>
<p>S_NOCM<br>
The current member is null. S_NOCOM is returned as a status not an
error.</p>
<h4>Example</h4>
<pre>
<font color="#0000FF">/* print keywords for info record */

DB_ADDR dba;
   ...
/* save current member of key_to_info set in
   case info record was retrieved from a keyword scan */
d_csmget(KEY_TO_INFO, &amp;dba, task, TIMS_DBN);
   ...      /* print keywords thru info_to_key */
/* restore current member */
d_csmset(KEY_TO_INFO, &amp;dba, task, TIMS_DBN);</font>
</pre>
<h4>See Also</h4>
<p><b><font size="2">d_crget, d_crset, d_csmset, d_csoget,
d_csoset, d_gtscm</font></b></p>
<p>&nbsp;</p>
<hr>
<h3><a name="d_csmread" id="d_csmread"></a>d_csmread</h3>
<p><font size="2">Read data from field of current member</font></p>
<h4>Prototypes</h4>
<p><font size="2">int <b>d_csmread</b>(int <i>SET</i>, 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">SET<br>
The set type for which the current member will be read.</font></p>
<p>FIELD<br>
The field type to be read from the current member.</p>
<p>value<br>
A pointer to the data area that will receive 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">Function <b>d_csmread</b> copies the contents of
<i>FIELD</i> from the current member of <i>SET</i> to the area to
which <i>value</i> points.</font></p>
<h4>Currency Changes</h4>
<p><font size="2">This function updates the timestamp in the
currency table for the current member of the set from the
database.</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>SET</i> member record type to
ensure current data.</font></p>
<h4>Return Codes</h4>
<p><font size="2">S_DELETED<br>
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 member.</p>
<p>S_INVSET<br>
Invalid set type. Probably passed a record or field type instead of
a set type.</p>
<p>S_NOCM<br>
The current member is null.</p>
<h4>Example</h4>
<pre>
<font color="#0000FF">char name[32];   /* author name /
int status;
   ...
/* print all authors in the database */
for ( status = d_findfm(AUTHOR_LIST, task, TIMS_DBN); 
   status == S_OKAY; 
   status = d_findnm(AUTHOR_LIST, task, TIMS_DBN) ) 
{
   d_csmread(AUTHOR_LIST, NAME, name, task, TIMS_DBN);
   printf("%ss\n", name);
}</font>
</pre>
<h4>See Also</h4>
<p><b><font size="2">d_crread, d_csoread</font></b></p>
<p>&nbsp;</p>
<hr>
<h3><a name="d_csmset" id="d_csmset"></a>d_csmset</h3>
<p><font size="2">Set database address of current member</font></p>
<h4>Prototypes</h4>
<p><font size="2">int <b>d_csmset</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>
The set type for the current member to be assigned.</font></p>
<p>dba<br>
A pointer to the database address that becomes the current member
of <i>SET</i>.</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_csmset</b> copies the database
address pointed to by <i>dba</i> to the current member of
<i>SET</i>. The current owner of <i>SET</i> becomes the record that
is the current owner of the new member. This function is generally
used in conjunction with <b>d_csmget</b> (it can also be used with
<b>d_crget</b> or <b>d_csoget</b>) for saving and restoring the
current member of a set.</font></p>
<blockquote><b><i>Note:</i></b> If the record type of the current
member is timestamped, <b>d_stscm</b> should also be called to set
the last access timestamp for the current member.</blockquote>
<h4>Currency Changes</h4>
<p><font size="2">curr_mem[<i>SET</i>] = *<i>dba</i>;</font></p>
<p>curr_own[<i>SET</i>] = owner of *<i>dba</i> through
<i>SET</i>;</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>SET</i> to ensure current
data.</font></p>
<h4>Return Codes</h4>
<p><font size="2">S_INVADDR<br>
Invalid database address. You may have passed the database address
itself rather than a pointer to it.</font></p>
<p>S_INVMEM<br>
Record type is not a legal member of the specified set.</p>
<p>S_INVSET<br>
Invalid set type. Probably passed a record or field type instead of
a set type.</p>
<h4>Example</h4>
<pre>
<font color="#0000FF">/* print keywords for info record */
DB_ADDR dba;
   ...
/* save current member of key_to_info set in
   case info record was retrieved from a keyword scan */
d_csmget(KEY_TO_INFO, &amp;dba, task, CURR_DB);
   ...      /* print keywords thru info_to_key */
/* restore current member */
d_csmset(KEY_TO_INFO, &amp;dba, task, CURR_DB);</font>
</pre>
<h4>See Also</h4>
<p><b><font size="2">d_crset, d_csmget, d_csoset, d_gtscm,
d_stscm</font></b></p>
<p>&nbsp;</p>
<hr>
<h3><a name="d_csmwrite" id="d_csmwrite"></a>d_csmwrite</h3>
<p><font size="2">Write to field in current member</font></p>
<h4>Prototypes</h4>
<p><font size="2">int <b>d_csmwrite</b>(int <i>SET</i>, long
<i>FIELD</i>, const void *<i>value</i>, DB_TASK *<i>task</i>, int
<i>dbn</i>)</font></p>
<h4>Parameters</h4>
<p><font size="2">SET<br>
The set type of the current member to be written.</font></p>
<p>FIELD<br>
The field type from the current member.</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_csmwrite</b> writes the data
pointed to by <i>value</i> to data field <i>FIELD</i> in the
current member of <i>SET</i>. If <i>FIELD</i> is a key field, the
key is automatically 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 is automatically adjusted accordingly. If
<i>FIELD</i> is an array field, the entire array is written.
Elements of an array cannot be written individually. Fields used in
a compound key cannot be modified with this function; use
<b>d_recwrite</b> instead.</font></p>
<h4>Currency Changes</h4>
<p><font size="2">None.</font></p>
<h4>Locking Requirements</h4>
<p><font size="2">Write lock on <i>SET</i> and key file containing
<i>FIELD</i>, or write lock on <i>SET</i> member record
type.</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 member.</p>
<p>S_INVSET<br>
Invalid set type. Probably passed a record or field type instead of
a set type.</p>
<p>S_ISCOMKEY<br>
Illegal operation using a compound key field.</p>
<p>S_NOCM<br>
The current member is null.</p>
<p>S_NOTLOCKED<br>
Record type containing <i>FIELD</i> is not 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">char name[32];   /* author name */
int status;
   ...
/* change author "Worth" to "Wirth" */
for ( status = d_findfm(AUTHOR_LIST, task, CURR_DB); 
   status == S_OKAY;
   status = d_findnm(AUTHOR_LIST, task, CURR_DB) ) 
{
   d_csmread(AUTHOR_LIST, NAME, name, task, CURR_DB);
   if ( strcmp(name, "Worth") == 0 )
      d_csmwrite(AUTHOR_LIST, NAME, "Wirth", task, CURR_DB);
}</font>
</pre>
<h4>See Also</h4>
<p><b><font size="2">d_crwrite, d_csowrite,
d_recwrite</font></b></p>
<p>&nbsp;</p>
<hr>
<h3><a name="d_csoget" id="d_csoget"></a>d_csoget</h3>
<p><font size="2">Get database address of current owner</font></p>
<h4>Prototypes</h4>
<p><font size="2">int <b>d_csoget</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>
The set type for which the current owner's database address is to
be returned.</font></p>
<p>dba<br>
A pointer to a DB_ADDR variable that receives the database address
of the current owner.</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 owner of <i>SET</i> into the database address variable to
which <i>dba</i> points. This function is used in conjunction with
the <b>d_csoset</b> function for saving and restoring the current
owner of a set. If the current owner is null (NULL_DBA), code
S_NOCO is returned as a status (that is, <b>dberr</b> is not
called), and *<i>dba</i> will receive the null database
address.</font></p>
<blockquote><b><i>Note:</i></b> If the record type of the current
owner is timestamped, you should also call function <b>d_gtsco</b>
to get the last access timestamp for the current owner. Then, when
the current owner is later restored by <b>d_csoset</b>, function
<b>d_stsco</b> should also be called to restore the last access
timestamp associated with that current owner 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_INVSET<br>
Invalid set type. Probably passed a record or field type instead of
a set type.</font></p>
<p>S_NOCO<br>
The current owner is null. Returned as a status, not an error.</p>
<h4>Example</h4>
<pre>
<font color="#0000FF">DB_ADDR dba;
...
/* save current author on the stack for later processing */
d_csoget(HAS_PUBLISHED, &amp;dba, task, my_dbn);
...
/* restore saved author as owner of has_published */
d_csoset(HAS_PUBLISHED, &amp;dba, task, my_dbn);</font>
</pre>
<h4>See Also</h4>
<p><b><font size="2">d_crget, d_csmget, d_gtsco,
d_stsco</font></b></p>
<p>&nbsp;</p>
<hr>
<h3><a name="d_csoread" id="d_csoread"></a>d_csoread</h3>
<p><font size="2">Read data from field of current owner</font></p>
<h4>Prototypes</h4>
<p><font size="2">int <b>d_csoread</b>(int <i>SET</i>, 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">SET<br>
The set type for which the current owner will be read.</font></p>
<p>FIELD<br>
The field type to be read from the current owner.</p>
<p>value<br>
The pointer to the data area that will receive 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">Function <b>d_csoread</b> copies the contents of
<i>FIELD</i> from the current owner of <i>SET</i> 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 timestamps in the
currency table for the current owner of the set and for the set
from the database.</font></p>
<h4>Locking Requirements</h4>
<p><font size="2">