mu_ch4.htm

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

<h4>Return Codes</h4>
<p><font size="2">S_USERID<br>
No user ID was specified.</font></p>
<p>S_INVLOCK<br>
The specified lock manager type is invalid.</p>
<p>S_LMCERROR<br>
The attempt to communicate with the lock manager failed.</p>
<p>S_NOLOCKMGR<br>
The specified lock manager was not found.</p>
<p>S_DUPUSERID<br>
The specified user ID is the same as the user ID currently in use.
When calling <b>d_lmclear</b>, you must call it from a task with a
different user ID than the one you are clearing.</p>
<p>S_UNAVAIL<br>
Internal or General lock manager error.</p>
<hr>
<h3><a name="lmstat" id="lmstat"></a>d_lmstat</h3>
<p><font size="2">Returns the status of the specified
user</font></p>
<h4>Prototype</h4>
<pre>
<font color=
"#0000FF">d_lmstat(char *<i>username</i>, int <i>*userstatus, </i>DB_TASK *<i>task</i>)</font>
</pre>
<h4>Parameters</h4>
<p><font size="2">username<br>
The name of the user whose status is to be queried.</font></p>
<p>userstatus<br>
The user's status is returned here.</p>
<p>task<br>
A pointer to the application's task variable.</p>
<h4>Description</h4>
<p><font size="2">This function queries the lock manager associated
with the current DB_TASK for the status of the specified user. The
following status codes are returned in
<i>userstatus</i>:</font></p>
<h5>Status Codes</h5>
<p><font size="2">U_EMPTY<br>
The username is invalid or unknown to the lock manager.</font></p>
<p>U_LIVE<br>
The user is active in the lock manager.</p>
<p>U_DEAD<br>
The username corresponds to a DB_TASK, which has disconnected from
the lock manager.</p>
<p>U_BEING_REC<br>
This user is performing a recovery for another, disconnected
user.</p>
<p>U_REC_MYSELF<br>
This user was disconnected and is now doing its own recovery.</p>
<p>U_HOLDING_X<br>
This user has closed all databases and is holding an exclusive lock
on at least one file.</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_LMCERROR<br>
The attempt to communicate with the lock manager failed.</font></p>
<p>S_DBOPEN<br>
This function can only be called once a database has been
successfully opened or this error is returned.</p>
<hr>
<h3><a name="lock" id="lock"></a>d_lock</h3>
<p><font size="2">Locks group of record or set types</font></p>
<h4>Prototype</h4>
<pre>
<font color=
"#0000FF">d_lock(int <i>count</i>, LOCK_REQUEST <i>*lrpkt</i>, DB_TASK *<i>task</i>, int <i>dbn</i>)</font>
</pre>
<h4>Parameters</h4>
<p><font size="2">count<br>
The number of items to be locked.</font></p>
<p>lrpkt<br>
A pointer to a lock request packet array.</p>
<p>task<br>
A pointer to the application's task variable.</p>
<p>dbn<br>
Database number.</p>
<h4>Description</h4>
<p><font size="2">Function <b>d_lock</b> provides a grouped lock
request capability whereby more than one record or set type can be
locked in a single request. Two parameters are passed to
<b>d_lock</b>. The first parameter is an integer that contains a
count of the number of items to be locked. The second parameter is
a pointer to a lock request packet array. Each lock request is
placed in a LOCK_REQUEST structure entry as defined below and
declared in file <b>db.star.h</b>.</font></p>
<pre>
<font color="#0000FF">typedef struct {
  int item;  /* record or set type to be locked */
  char type; /* type of lock */
} LOCK_REQUEST;</font>
</pre>
<p><font size="2">Structure field <b>item</b> contains the record
or set type of the record or set to be locked. Field <b>type</b>
contains the type of lock to be applied as follows:</font></p>
<table border="1" cellspacing="1" cellpadding="7" width="193">
<tr>
<td width="38%" valign="top">
<p><b><font size="2">Type</font></b></p>
</td>
<td width="62%" valign="top">
<p><b><font size="2">Description</font></b></p>
</td>
</tr>
<tr>
<td width="38%" valign="top">
<p><font size="2">r</font></p>
</td>
<td width="62%" valign="top">
<p><font size="2">Read lock</font></p>
</td>
</tr>
<tr>
<td width="38%" valign="top">
<p><font size="2">w</font></p>
</td>
<td width="62%" valign="top">
<p><font size="2">Write lock</font></p>
</td>
</tr>
<tr>
<td width="38%" valign="top">
<p><font size="2">x</font></p>
</td>
<td width="62%" valign="top">
<p><font size="2">Exclusive lock</font></p>
</td>
</tr>
<tr>
<td width="38%" valign="top">
<p><font size="2">k</font></p>
</td>
<td width="62%" valign="top">
<p><font size="2">Keep lock</font></p>
</td>
</tr>
</table>
<p><font size="2">Read locks allow other programs to read but not
update the locked files. Write locks prevent all other programs
from accessing the locked files and can only be issued from within
a transaction. Exclusive locks also prevent all other programs from
accessing the locked files, but can be issued independent of
transactions. Keep locks can only be issued from within a
transaction and will keep read and write locked files read-locked
after a transaction ends. (<b>d_trend</b> normally frees all read-
and write-locked files.) To apply a keep lock, the record or set
types specified with a keep lock must be locked. Otherwise, status
S_NOTLOCKED is returned.</font></p>
<p>Within a transaction, a file with a read lock can be upgraded to
a write or exclusive lock without the possibility of outside
intervention by calling <b>d_lock</b>. If the upgrade lock request
is denied, the read lock will remain in effect. If any of the
requested locks cannot be granted, none of the locks will be
granted.</p>
<blockquote>Note: If a single <b>d_lock</b> call for each
transaction is always used to lock all files needed by the
transaction, the program is guaranteed to be free of deadlock,
assuming that a timeout value other than -1 is used.</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_UNAVAIL<br>
One or more of the requested files is not available (that is, you
were on the queue waiting for a file longer than your current time
out value).</font></p>
<p>S_BADTYPE<br>
An invalid lock type was specified. You may have passed a string
(for example, "r") instead of a character (for example, 'r').</p>
<p>S_NOTFREE<br>
You attempted to lock a previously locked record or set.</p>
<p>S_NOTRANS<br>
You requested a write lock outside of a transaction.</p>
<p>S_INVNUM<br>
An invalid record or set type was specified in the lock request
packet.</p>
<h4>Example</h4>
<pre>
<font color="#0000FF">int tx_ckin_sz = 3;
LOCK_REQUEST tx_ckin_pkt[] = {
        {AUTHOR_LIST, 'r'},
        {HAS_PUBLISHED, 'w'},
        {BORROWER, 'w'}
};
        ...
d_trbegin("tx_ckin", task);
if ( <i>d_lock</i>(tx_ckin_sz, tx_ckin_pkt, task, CURR_DB) == OKAY ) {
        ...  /* check in borrowed book */
        d_trend(task);
else
        d_trabort(task);        
/* try again later */</font>
</pre>
<h4>See Also</h4>
<p><b><font size="2">d_freeall, d_recfree, d_reclock, d_reclstat,
d_setfree, d_setlock, d_setlstat, d_trabort, d_trbegin,
d_trend</font></b></p>
<hr>
<h3><a name="lockcomm" id="lockcomm"></a>d_lockcomm</h3>
<p><font size="2">Selects a lock manager interface</font></p>
<h4>Prototype</h4>
<pre>
<font color=
"#0000FF">d_lockcomm(LMC_AVAIL_FCN *<i>avail</i>, DB_TASK <i>task</i>)</font>
</pre>
<h4>Parameters</h4>
<p><font size="2">avail<br>
The address of a function to check the availability of a transport.
The most portable way use this function is to pass the result of a
call to psp_lmcFind().</font></p>
<p>task<br>
The application's task variable.</p>
<h4>Description</h4>
<p><font size="2">This function sets the type of communications to
use for the lock manager.</font></p>
<p>A multi-user application must call <b>d_lockcomm</b> to
initialize the protocol interface. An attempt to use
<b><i>db.*</i></b> without a call to <b>d_lockcomm</b> produces
user error S_NOLOCKCOMM, indicating the lock manager communication
layer was not initialized.</p>
<p>The following values are currently allowed:</p>
<div style="margin-left: 4em">
<p>NULL<br>
Single-user applications (no lock manager)</p>
<p>&amp;psp_ip_avail<br>
UNIX Domain sockets</p>
<p>&amp;psp_tcp_avail<br>
UNIX Internet Domain sockets</p>
</div>
<p>Alternatively, the addresses of these functions can be found
using the <b>psp_lmcFind</b> function. Look at the following:</p>
<pre>
<font color="#0000FF">LMC_AVAIL_FCN *tcpavail = psp_lmcFind("TCP");
LMC_AVAIL_FCN *ipavail = psp_lmcFind("IP");</font>
</pre>
<p><font size="2">These lines will result in tcpavail pointing to
the <b>psp_tcp_avail</b> function and ipavail pointing to the
<b>psp_ip_avail</b> function.</font></p>
<h4>Currency Changes</h4>
<p><font size="2">None.</font></p>
<p><b><font face="HELVETICA">Locking Requirements</font></b></p>
<p><font size="2">None.</font></p>
<h4>Return Codes</h4>
<p><font size="2">S_DBOPEN<br>
The database is open. Function called after
<b>d_open</b>.</font></p>
<hr>
<h3><a name="lockmgr" id="lockmgr"></a>d_lockmgr</h3>
<p><font size="2">Selects the named lock manager to use</font></p>
<h4>Prototype</h4>
<pre>
<font color=
"#0000FF">d_lockmgr(char *<i>id</i>, DB_TASK *<i>task</i>)</font>
</pre>
<h4>Parameters</h4>
<p><font size="2">id<br>
A string containing the desired lock manager name.</font></p>
<p>task<br>
A pointer to the application's task variable.</p>
<h4>Description</h4>
<p><font size="2">This function selects the named lock manager to
be used during multi-user operation. The default lock manager name
is <b>lockmgr</b>. The lock manager name cannot be set after the
database is opened.</font></p>
<p>Some lock managers have specific requirements for lock manager
names. See the section in this document specific to your lock
manager for details.</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_DBOPEN<br>
The database is open. Function called after
<b>d_open</b>.</font></p>
<p>S_INVPTR<br>
Null pointers and empty strings are not allowed.</p>
<p>S_BADUSERID<br>
The user id contains invalid characters.</p>
<h4>See Also</h4>
<p><font size="2">None.</font></p>
<p><a href="MU_TOC.htm">Table of Contents</a></p>
</body>
</html>