rm_ch3.htm

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

of the <b>d_setfiles</b> function, or uses the 8 default file
handles. If at some point in an application more file handles are
needed, this function may be called.</font></p>
<blockquote><b><i>Note:</i></b> Care should be taken in designing
the application so that extra handles are released, allowing
<b><i>db.*</i></b> to reopen the files on an as-needed
basis.</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">None.</font></p>
<h4>Example</h4>
<pre>
<font color="#0000FF">/* Open a report file */
rpt[i] = fopen( rpt_name, "w" );
if ( rpt[i] == NULL )
{
   /* Try to obtain more handles */
   d_closeall(task);
   rpt[i] = fopen( rpt_name, "w" );
   if ( rpt[i] == NULL )
   {
      /* None available */
      fprintf( stderr, "Out of file handles\n" );
      d_close(task);
      exit(1);
   }
}
/* Produce the report */
...
fclose(rpt[i]);</font>
</pre>
<h4>See Also</h4>
<p><font size="2">None.</font></p>
<p>&nbsp;</p>
<hr>
<h3><a name="d_closetask" id="d_closetask"></a>d_closetask</h3>
<p><font size="2">Close a database task</font></p>
<h4>Prototypes</h4>
<p><font size="2">int <b>d_closetask</b>(DB_TASK
*<i>task</i>)</font></p>
<h4>Parameters</h4>
<p><font size="2">task<br>
A pointer to a DB_TASK structure.</font></p>
<h4>Description</h4>
<p><font size="2">This function will free the memory associated
with a database task. The <b>dt_opentask</b> function must
previously have created the task, and any databases opened within
the task must first be closed.</font></p>
<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_DBCLOSE<br>
Task not opened.</font></p>
<p>S_INVPTR<br>
Invalid task pointer.</p>
<h4>Example</h4>
<pre>
<font color="#0000FF">DB_TASK task;

d_opentask(&amp;task);
d_open("db", "o", &amp;task);
d_makenew(REC, &amp;task, 0);
d_close(&amp;task);
d_closetask(&amp;task);</font>
</pre>
<h4>See Also</h4>
<p><b><font size="2">d_opentask</font></b></p>
<p>&nbsp;</p>
<hr>
<h3><a name="d_cmstat" id="d_cmstat"></a>d_cmstat</h3>
<p><font size="2">Test timestamp status of current
member</font></p>
<h4>Prototypes</h4>
<p><font size="2">int <b>d_cmstat</b>(int <i>SET</i>, DB_TASK
*<i>task</i>, int <i>dbn</i>)</font></p>
<h4>Parameters</h4>
<p><font size="2">SET<br>
The set whose current member's status is checked.</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">The <b>d_cmstat</b> function tests the status of
the timestamp in the currency table of the current member of
<i>SET</i> against the timestamp on the disk. The current member
record type 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>SET</i> to ensure current
data.</font></p>
<h4>Return Codes</h4>
<p><font size="2">S_DELETED<br>
The current member has been deleted since it was last
accessed.</font></p>
<p>S_INVSET<br>
Invalid set type. Probably passed a record type instead of a set
type.</p>
<p>S_OKAY<br>
The current member has not been changed by another user since last
accessed.</p>
<p>S_TIMESTAMP<br>
The current member record type is not timestamped.</p>
<p>S_UPDATED<br>
The current member was modified since last accessed.</p>
<h4>Example</h4>
<pre>
<font color=
"#0000FF">if ( d_cmstat(HAS_PUBLISHED, task, CURR_DB) == S_OKAY )
{
   d_csmread(HAS_PUBLISHED, INFO_TITLE, title, task, CURR_DB);
   ...
}</font>
</pre>
<h4>See Also</h4>
<p><b><font size="2">d_costat, d_crstat, d_csstat, d_gtscm,
d_recstat, d_stscm</font></b></p>
<p>&nbsp;</p>
<hr>
<h3><a name="d_cmtype" id="d_cmtype"></a>d_cmtype</h3>
<p><font size="2">Get record type of current member</font></p>
<h4>Prototypes</h4>
<p><font size="2">int <b>d_cmtype</b>(int <i>SET</i>, int
*<i>rectype</i>, DB_TASK *<i>task</i>, int <i>dbn</i>)</font></p>
<h4>Parameters</h4>
<p><font size="2">SET<br>
The set type to which the current member record type is
returned.</font></p>
<p>rectype<br>
A pointer to an integer variable that contains the returned record
type.</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 <i>SET</i> member into the integer variable to which
<i>rectype</i> points. This function is particularly useful in
determining the type of the current member of multiple member
sets.</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 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_INVSET<br>
Invalid set type. A record or field type, instead of a set type,
was probably passed.</font></p>
<p>S_NOCM<br>
The current member for the specified set is null.</p>
<h4>Example</h4>
<pre>
<font color="#0000FF">int rtype;      /* record type */
long fld;       /* field type */
char txt[80];   /* comment text */
...
d_cmtype(COMMENTS, &amp;rtype, task, CURR_DB); 
switch ( rtype )
{
   case TEXT30:
      fld = T30_LINE;
      break;
   case TEXT55:
      fld = T55_LINE;
      break;
   case TEXT80:
      fld = T80_LINE;
      break;
}
d_csmread(COMMENTS, fld, &amp;txt, task, CURR_DB);</font>
</pre>
<h4>See Also</h4>
<p><b><font size="2">d_cotype, d_crtype</font></b></p>
<p>&nbsp;</p>
<hr>
<h3><a name="d_connect" id="d_connect"></a>d_connect</h3>
<p><font size="2">Connect current record to set</font></p>
<h4>Prototypes</h4>
<p><font size="2">int <b>d_connect</b>(int <i>SET</i>, DB_TASK
*<i>task</i>, int <i>dbn</i>)</font></p>
<h4>Parameters</h4>
<p><font size="2">SET<br>
The set type to which the current record is connected.</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">The function <b>d_connect</b> connects the
current record to the current owner of <i>SET</i>. The record is
placed into <i>SET</i> in the order specified in the DDL for the
database. Upon successful completion, the current record becomes
the current member of <i>SET</i>.</font></p>
<h4>Currency Changes</h4>
<p><font size="2">curr_mem[<i>SET</i>] = curr_rec;</font></p>
<h4>Locking Requirements</h4>
<p><font size="2">Write lock on <i>SET</i>, or write locks on owner
and member record types. Key files need not be locked.</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_ISOWNED<br>
The current record is already owned as a member of <i>SET</i>. If
you want to change a set connection, you first need to disconnect
the record from the current owner, set the current owner of
<i>SET</i> to the new owner record, and then connect the current
record to the new owner record.</p>
<p>S_NOCO<br>
The current owner for the specified set is null. Find the correct
owner record occurrence, and set the current owner of <i>SET</i> to
the located record (for example, using function
<b>d_setor</b>).</p>
<p>S_NOCR<br>
The current record is null.</p>
<p>S_NOTLOCKED<br>
A data file named in the definition of <i>SET</i> has not been
locked.</p>
<p>S_NOTRANS<br>
In shared mode, changes can only be made from within a transaction
except when the affected files are exclusively locked.</p>
<h4>Example</h4>
<pre>
<font color="#0000FF">struct info irec;   /* tech. info record */
...
/* make author record current owner of has_published */
d_setor(HAS_PUBLISHED, task, CURR_DB);
...
/* create new info record */
if ( d_fillnew(INFO, &amp;irec, task, CURR_DB) == S_OKAY )
   /* connect new record to has_published set */
   d_connect(HAS_PUBLISHED, task, CURR_DB);</font>
</pre>
<h4>See Also</h4>
<p><b><font size="2">d_discon, d_disdel</font></b></p>
<p>&nbsp;</p>
<hr>
<h3><a name="d_costat" id="d_costat"></a>d_costat</h3>
<p><font size="2">Test timestamp status of current owner</font></p>
<h4>Prototypes</h4>
<p><font size="2">int <b>d_costat</b>(int <i>SET</i>, DB_TASK
*<i>task</i>, int <i>dbn</i>)</font></p>
<h4>Parameters</h4>
<p><font size="2">SET<br>
The set whose current owner's status is checked.</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 tests the status of the timestamp
in the currency table of the current owner of <i>SET</i> against
the timestamp on the disk. The current owner record type 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">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>Locking Requirements</h4>
<p><font size="2">None.</font></p>
<h4>Return Codes</h4>
<p><font size="2">S_DELETED<br>
The current owner has been deleted since it was last
accessed.</font></p>
<p>S_INVSET<br>
Invalid set type. Probably passed a record type instead of a set
type.</p>
<p>S_OKAY<br>
The current owner has not been changed by another user since it was
last accessed.</p>
<p>S_TIMESTAMP<br>
The current owner record type is not timestamped.</p>
<p>S_UPDATED<br>
The current owner was modified since last accessed.</p>
<h4>Example</h4>
<pre>
<font color=
"#0000FF">if ( d_costat(HAS_PUBLISHED, task, CURR_DB) == S_OKAY )
{
   d_csoread(HAS_PUBLISHED, INFO_TITLE, title, task, CURR_DB);
   ...
}</font>
</pre>
<h4>See Also</h4>
<p><b><font size="2">d_cmstat, d_crstat, d_csstat, d_gtsco,
d_recstat, d_stsco</font></b></p>
<p>&nbsp;</p>
<hr>
<h3><a name="d_cotype" id="d_cotype"></a>d_cotype</h3>
<p><font size="2">Get record type of current owner</font></p>
<h4>Prototypes</h4>
<p><font size="2">int <b>d_cotype</b>(int <i>SET</i>, int
*<i>rectype</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 record type is to be
returned.</font></p>
<p>rectype<br>
A pointer to an integer variable that contains the returned record
type.</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 owner of <i>SET</i> 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 on <i>SET</i> to ensure current
data.</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 for the specified set is null.</p>
<h4>Example</h4>