rm_ch3.htm

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

<p><font size="2">int <b>d_keybuild</b>(DB_TASK *<i>task</i>, int
<i>dbn</i>)<br>
Rebuild the key files from the data in the data files</font></p>
<p><font size="2">int <b>d_keydel</b>(long <i>FIELD</i>, DB_TASK
*<i>task</i>, int <i>dbn</i>)<br>
Delete optional key</font></p>
<p><font size="2">int <b>d_keyexist</b>(long <i>FIELD</i>, DB_TASK
*<i>task</i>, int <i>dbn</i>)<br>
Determine whether an optional key exists</font></p>
<p><font size="2">int <b>d_keyfind</b>(long <i>FIELD</i>, const
void *<i>value</i>, DB_TASK *<i>task</i>, int <i>dbn</i>)<br>
Find record by key</font></p>
<p><font size="2">int <b>d_keyfree</b>(long <i>FIELD</i>, DB_TASK
*<i>task</i>, int <i>dbn</i>)<br>
Free key type read-lock</font></p>
<p><font size="2">int <b>d_keyfrst</b>(long <i>FIELD</i>, DB_TASK
*<i>task</i>, int <i>dbn</i>)<br>
Find record with first key</font></p>
<p><font size="2">int <b>d_keylast</b>(long <i>FIELD</i>, DB_TASK
*<i>task</i>, int <i>dbn</i>)<br>
Find record with last key</font></p>
<p><font size="2">int <b>d_keylock</b>(long <i>FIELD</i>, char
*<i>type</i>, DB_TASK *<i>task</i>, int <i>dbn</i>)<br>
Lock key files associated with key type</font></p>
<p><font size="2">int <b>d_keylstat</b>(long <i>FIELD</i>, char
*<i>type</i>, DB_TASK *<i>task</i>, int <i>dbn</i>)<br>
Get lock status of key type</font></p>
<p><font size="2">int <b>d_keynext</b>(long <i>FIELD</i>, DB_TASK
*<i>task</i>, int <i>dbn</i>)<br>
Find record with next key</font></p>
<p><font size="2">int <b>d_keyprev</b>(long <i>FIELD</i>, DB_TASK
*<i>task</i>, int <i>dbn</i>)<br>
Find record with previous key</font></p>
<p><font size="2">int <b>d_keyread</b>(void *<i>value</i>, DB_TASK
*<i>task</i>)<br>
Read value of last found key</font></p>
<p><font size="2">int <b>d_keystore</b>(long <i>FIELD</i>, DB_TASK
*<i>task</i>, int <i>dbn</i>)<br>
Store optional key</font></p>
<p><font size="2">int <b>d_lmclear</b>(const char *<i>username</i>,
const char <i>*lockmgr</i>, int&nbsp;<i>lockcomm</i>, DB_TASK
*<i>task</i>)<br>
Unicode version: (char *) changes to (wchar_t *)<br>
Clear a user from the lock manager's user table</font></p>
<p><font size="2">int <b>d_lmstat</b>(char *<i>username</i>, int
*<i>status</i>, DB_TASK *<i>task</i>)<br>
Unicode version: (char *) changes to (wchar_t *)<br>
Return the Lock Manager's status of the given user</font></p>
<p><font size="2">int <b>d_lock</b>(int <i>count</i>, LOCK_REQUEST
*<i>lrpkt</i>, DB_TASK *<i>task</i>, int <i>dbn</i>)<br>
Lock group of record or set types</font></p>
<p><font size="2">int <b>d_lockcomm</b>(int <i>type</i>, DB_TASK
*<i>task</i>)<br>
Set the protocol type to use to communicate with the lock
manager</font></p>
<p><font size="2">int <b>d_lockmgr</b>(const char
*<i>lockmgrname</i>, DB_TASK *<i>task</i>)<br>
Unicode version: (char *) changes to (wchar_t *)<br>
Set the name of the lock manager</font></p>
<p><font size="2">int <b>d_makenew</b>(int <i>REC</i>, DB_TASK
*<i>task</i>, int <i>dbn</i>)<br>
Make a new (empty) record</font></p>
<p><font size="2">int <b>d_mapchar</b>(unsigned char <i>inchar</i>,
unsigned char <i>outchar</i>, const char *<i>sort_as</i>,
unsigned&nbsp;char <i>subsort</i>, DB_TASK *<i>task</i>)<br>
Map character for sorting and output</font></p>
<p><font size="2">int <b>d_members</b>(int <i>SET</i>, long
*<i>count</i>, DB_TASK *<i>task</i>, int <i>dbn</i>)<br>
Get count of current set members</font></p>
<p><font size="2">int <b>d_off_opt</b>(unsigned long
<i>optflag</i>, DB_TASK *<i>task</i>)<br>
Turn off runtime options</font></p>
<p><font size="2">int <b>d_on_opt</b>(unsigned long <i>optflag</i>,
DB_TASK *<i>task</i>)<br>
Turn on runtime options</font></p>
<p><font size="2">int <b>d_open</b>(const char *<i>dbnames</i>,
const char *<i>type</i>, DB_TASK *<i>task</i>)<b><br></b> Unicode
version: <b>d_open</b>(const wchar_t *<i>dbnames</i>, const char
*<i>type</i>, DB_TASK *<i>task</i>)<br>
Open database(s)</font></p>
<p><font size="2">int <b>d_opentask</b>(DB_TASK ** task)<br>
Allocate memory for a new database task</font></p>
<p><font size="2">int <b>d_rdcurr</b>(DB_ADDR **<i>currbuff</i>,
int *<i>currsize</i>, DB_TASK *<i>task</i>, int <i>dbn</i>)<br>
Read currency tables</font></p>
<p><font size="2">int <b>d_recfree</b>(int <i>REC</i>, DB_TASK
*<i>task</i>, int <i>dbn</i>)<br>
Free record type read-lock</font></p>
<p><font size="2">int <b>d_recfrst</b>(int <i>REC</i>, DB_TASK
*<i>task</i>, int <i>dbn</i>)<br>
Find first occurrence of record type</font></p>
<p><font size="2">int <b>d_reclast</b>(int <i>REC</i>, DB_TASK
*<i>task</i>, int <i>dbn</i>)<br>
Find last occurrence of record type</font></p>
<p><font size="2">int <b>d_reclock</b>(int <i>REC</i>, char
*<i>type</i>, DB_TASK *<i>task</i>, int <i>dbn</i>)<br>
Lock files associated with record type</font></p>
<p><font size="2">int <b>d_reclstat</b>(int <i>REC</i>, char
*<i>type</i>, DB_TASK *<i>task</i>, int <i>dbn</i>)<br>
Get lock status of record type</font></p>
<p><font size="2">int <b>d_recnext</b>(DB_TASK *<i>task</i>, int
<i>dbn</i>)<br>
Find next occurrence of current record type</font></p>
<p><font size="2">int <b>d_recnum</b>(int *<i>index</i>, int
<i>REC</i>, DB_TASK *<i>task</i>, int <i>dbn</i>)<br>
Convert the record's <b>ddlp</b> <b>#define</b> into the record
table index</font></p>
<p><font size="2">int <b>d_recprev</b>(DB_TASK *<i>task</i>, int
<i>dbn</i>)<br>
Find previous occurrence of current record</font></p>
<p><font size="2">int <b>d_recread</b>(void *<i>value</i>, DB_TASK
*<i>task</i>, int <i>dbn</i>)<br>
Read contents of current record</font></p>
<p><font size="2">int <b>d_recset</b>(int <i>REC</i>, DB_TASK
*<i>task</i>, int <i>dbn</i>)<br>
Set occurrence of current record type</font></p>
<p><font size="2">int <b>d_recstat</b>(DB_ADDR <i>dba</i>, unsigned
long <i>rts</i>, DB_TASK *<i>task</i>, int <i>dbn</i>)<br>
Test timestamp status of record</font></p>
<p><font size="2">int <b>d_recwrite</b>(const void *<i>value</i>,
DB_TASK *<i>task</i>, int <i>dbn</i>)<br>
Write contents of current record</font></p>
<p><font size="2">int <b>d_renclean</b>(DB_TASK *<i>task</i>)<br>
Reset any renamed files back to the original</font></p>
<p><font size="2">int <b>d_renfile</b>(const char *<i>dbname</i>,
int <i>FILEID</i>, const char *<i>filenm</i>, DB_TASK
*<i>task</i>)<br>
Unicode version: (char *) changes to (wchar_t *)<br>
Rename database files</font></p>
<p><font size="2">int <b>d_rerdcurr</b>(DB_ADDR **<i>currbuff</i>,
DB_TASK *<i>task</i>, int <i>dbn</i>)<br>
Reread currency tables</font></p>
<p><font size="2">int <b>d_rlbclr</b>(DB_TASK *<i>task</i>, int
<i>dbn</i>)<br>
Clear record lock bit</font></p>
<p><font size="2">int <b>d_rlbset</b>(DB_TASK *<i>task</i>, int
<i>dbn</i>)<br>
Set record lock bit</font></p>
<p><font size="2">int <b>d_rlbtst</b>(DB_TASK *<i>task</i>, int
<i>dbn</i>)<br>
Test record lock bit</font></p>
<p><font size="2">int <b>d_set_dberr</b>(ERRORPROC <i>errfunc</i>,
DB_TASK *<i>task</i>)<br>
Replace default error handling with function</font></p>
<p><font size="2">int <b>d_setdb</b>(int <i>dbn</i>, DB_TASK
*<i>task</i>)<br>
Set current database</font></p>
<p><font size="2">int <b>d_setfiles</b>(int <i>num</i>, DB_TASK
*<i>task</i>)<br>
Set maximum number of open files</font></p>
<p><font size="2">int <b>d_setfree</b>(int <i>SET</i>, DB_TASK
*<i>task</i>, int <i>dbn</i>)<br>
Free set type read-lock</font></p>
<p><font size="2">int <b>d_setkey</b>(long <i>FIELD</i>, const void
*<i>value</i>, DB_TASK *<i>task</i>, int <i>dbn</i>)<br>
Set value of key field for <b>d_makenew</b></font></p>
<p><font size="2">int <b>d_setlock</b>(int <i>SET</i>, char
*<i>type</i>, DB_TASK *<i>task</i>, int <i>dbn</i>)<br>
Lock data files associated with set type</font></p>
<p><font size="2">int <b>d_setlstat</b>(int <i>SET</i>, char
*<i>type</i>, DB_TASK *<i>task</i>, int <i>dbn</i>)<br>
Get lock status of set type</font></p>
<p><font size="2">int <b>d_setmm</b>(int <i>TO_SET</i>, int
<i>FR_SET</i>, DB_TASK *<i>task</i>, int <i>dbn</i>)<br>
Set current member from current member</font></p>
<p><font size="2">int <b>d_setmo</b>(int <i>M_SET</i>, int
<i>O_SET</i>, DB_TASK *<i>task</i>, int <i>dbn</i>)<br>
Set current member from current owner</font></p>
<p><font size="2">int <b>d_setmr</b>(int <i>SET</i>, DB_TASK
*<i>task</i>, int <i>dbn</i>)<br>
Set current member from current record</font></p>
<p><font size="2">int <b>d_setnum</b>(int *<i>index</i>, int
<i>SET</i>, DB_TASK *<i>task</i>, int <i>dbn</i>)<br>
Convert the set's <b>ddlp</b> <b>#define</b> into the set table
index</font></p>
<p><font size="2">int <b>d_setom</b>(int <i>O_SET</i>, int
<i>M_SET</i>, DB_TASK *<i>task</i>, int <i>dbn</i>)<br>
Set current owner from current member</font></p>
<p><font size="2">int <b>d_setoo</b>(int <i>TO_SET</i>, int
<i>FR_SET</i>, DB_TASK *<i>task</i>, int <i>dbn</i>)<br>
Set current owner from current owner</font></p>
<p><font size="2">int <b>d_setor</b>(int <i>SET</i>, DB_TASK
*<i>task</i>, int <i>dbn</i>)<br>
Set current owner from current record</font></p>
<p><font size="2">int <b>d_setpages</b>(int <i>dbpages</i>, int
<i>ovpages</i>, DB_TASK *<i>task</i>)<br>
Set the number of virtual memory pages</font></p>
<p><font size="2">int <b>d_setrm</b>(int <i>SET</i>, DB_TASK
*<i>task</i>, int <i>dbn</i>)<br>
Set current record from current member</font></p>
<p><font size="2">int <b>d_setro</b>(int <i>SET</i>, DB_TASK
*<i>task</i>, int <i>dbn</i>)<br>
Set current record from current owner</font></p>
<p><font size="2">int <b>d_sopen</b>(const DB_SCHEMA
*<i>schema</i>, const char *<i>mode</i>, DB_TASK *<i>task</i>)<br>
Open database(s)</font></p>
<p><font size="2">int <b>d_stscm</b>(int <i>SET</i>, unsigned long
<i>ts</i>, DB_TASK *<i>task</i>, int <i>dbn</i>)<br>
Set last access timestamp of current member</font></p>
<p><font size="2">int <b>d_stsco</b>(int <i>SET</i>, unsigned long
<i>ts</i>, DB_TASK *<i>task</i>, int <i>dbn</i>)<br>
Set last access timestamp of current owner</font></p>
<p><font size="2">int <b>d_stscr</b>(unsigned long <i>ts</i>,
DB_TASK *<i>task</i>, int <i>dbn</i>)<br>
Set last access timestamp of current record</font></p>
<p><font size="2">int <b>d_stscs</b>(int <i>SET</i>, unsigned long
<i>ts</i>, DB_TASK *<i>task</i>, int <i>dbn</i>)<br>
Set last access timestamp for set</font></p>
<p><font size="2">int <b>d_timeout</b>(int <i>secs</i>, DB_TASK
*<i>task</i>)<br>
Set the lock request timeout value</font></p>
<p><font size="2">int <b>d_trabort</b>(DB_TASK *<i>task</i>)<br>
Abort transaction</font></p>
<p><font size="2">int <b>d_trbegin</b>(const char *<i>tid</i>,
DB_TASK *<i>task</i>)<br>
Unicode version: (char *) changes to (wchar_t *)<br>
Begin transaction</font></p>
<p><font size="2">int <b>d_trend</b>(DB_TASK *<i>task</i>)<br>
End transaction</font></p>
<p><font size="2">int <b>d_wrcurr</b>(DB_ADDR *<i>currbuff</i>,
DB_TASK *<i>task</i>, int <i>dbn</i>)<br>
Write currency tables</font></p>
<hr>
<h3><a name="d_checkid" id="d_checkid"></a>d_checkid</h3>
<p><font size="2">Check a DBUSERID for validity</font></p>
<h4>Prototypes</h4>
<p><font size="2">int <b>d_checkid</b>(char *<i>id</i>, DB_TASK
*<i>task</i>)</font></p>
<p>Unicode version: (char *) changes to (wchar_t *)</p>
<h4>Parameters</h4>
<p><font size="2">id<br>
The proposed DBUSERID string.</font></p>
<p>task<br>
A pointer to a DB_TASK structure.</p>
<h4>Description</h4>
<p><font size="2">This function, <b>d_checkid</b>, can be used to
validate a DBUSERID before calling <b>d_dbuserid</b> and
<b>d_open</b>. If either of the preceding functions would produce
DBUSERID-induced errors, <b>d_checkid</b> will produce a status
return without calling <b>dberr</b>.</font></p>
<p>After verifying that the string contains only numbers, letters,
or an underscore, the lock manager is asked whether the proposed
name is currently being used.</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_BADUSERID<br>
Invalid DBUSERID (not an error return).</font></p>
<p>S_DUPLICATE<br>
DBUSERID already in use.</p>
<h4>Example</h4>
<pre>
<font color="#0000FF">/* Get the proposed DBUSERID */
GetUserId( UserName );

stat = d_checkid( UserName, task );
if ( stat != S_OKAY )
{
   switch ( stat )
   {
      case S_BADUSERID:
         WarnUser( "Invalid DBUSERID string" );
         break;
      case S_DUPLICATE:
         WarnUser( "DBUSERID is in use" );
         break;
      default:
         WarnUser( "Network error, exiting" );
         return;
   }
   GetUserId( UserName );
}</font>
</pre>
<h4>See Also</h4>
<p><font size="2">None.</font></p>
<p>&nbsp;</p>
<hr>
<h3><a name="d_close" id="d_close"></a>d_close</h3>
<p><font size="2">Close database(s)</font></p>
<h4>Prototypes</h4>
<p><font size="2">int <b>d_close</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">The function <b>d_close</b> will close all open
databases. All files used by the <b><i>db.*</i></b> runtime library
are closed, and all of its dynamically allocated memory is freed.
All buffered changes made in single-user or exclusive access mode
are written to the database files.</font></p>
<blockquote><b><i>Note:</i></b> The consistency and integrity of a
database can be impaired if either a one-user or exclusive access
mode application that is not using transaction processing
terminates without first closing the database(s). For shared access
mode, user entries in the lock manager cannot be
cleared.</blockquote>
<h4>Currency Changes</h4>
<p><font size="2">The allocated memory used for the currency tables
is freed.</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">main()
{
   /* A db.* application program */
   ...
   d_open("tims", "s", task);

   ...   /* access "tims" database */

   d_close(task);
}</font>
</pre>
<h4>See Also</h4>
<p><b><font size="2">d_iclose, d_iopen, d_open</font></b></p>
<p>&nbsp;</p>
<hr>
<h3><a name="d_closeall" id="d_closeall"></a>d_closeall</h3>
<p><font size="2">Close all open file handles</font></p>
<h4>Prototypes</h4>
<p><font size="2">int <b>d_closeall</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">The <b>d_closeall</b> function can be used to
close all files that the <b><i>db.*</i></b> runtime library is
currently holding open. The library operates within the parameters