136 lines
6.6 KiB
HTML
136 lines
6.6 KiB
HTML
<!--$Id: db_join.html 63573 2008-05-23 21:43:21Z trent.nelson $-->
|
|
<!--Copyright (c) 1997,2008 Oracle. All rights reserved.-->
|
|
<!--See the file LICENSE for redistribution information.-->
|
|
<html>
|
|
<head>
|
|
<title>Berkeley DB: DB->join</title>
|
|
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
|
|
<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++">
|
|
</head>
|
|
<body bgcolor=white>
|
|
<table width="100%"><tr valign=top>
|
|
<td>
|
|
<b>DB->join</b>
|
|
</td>
|
|
<td align=right>
|
|
<a href="../api_c/api_core.html"><img src="../images/api.gif" alt="API"></a>
|
|
<a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a></td>
|
|
</tr></table>
|
|
<hr size=1 noshade>
|
|
<tt>
|
|
<b><pre>
|
|
#include <db.h>
|
|
<p>
|
|
int
|
|
DB->join(DB *primary,
|
|
DBC **curslist, DBC **dbcp, u_int32_t flags);
|
|
</pre></b>
|
|
<hr size=1 noshade>
|
|
<b>Description: DB->join</b>
|
|
<p>The DB->join method creates a specialized join cursor for use in
|
|
performing equality or natural joins on secondary indices. For
|
|
information on how to organize your data to use this functionality, see
|
|
<a href="../ref/am/join.html">Equality join</a>.</p>
|
|
<p>The DB->join method method is called using the <a href="../api_c/db_class.html">DB</a> handle of
|
|
the primary database.</p>
|
|
<p>The join cursor supports only the <a href="../api_c/dbc_get.html">DBcursor->get</a> and <b>dbc_close</b>
|
|
cursor functions:</p>
|
|
<br>
|
|
<b><a href="../api_c/dbc_get.html">DBcursor->get</a></b><ul compact><li>Iterates over the values associated with the keys to which each item in
|
|
<b>curslist</b> was initialized. Any data value that appears in all
|
|
items specified by the <b>curslist</b> parameter is then used as a key
|
|
into the <b>primary</b>, and the key/data pair found in the
|
|
<b>primary</b> is returned.
|
|
The <b>flags</b> parameter must be set to 0 or
|
|
the following value:
|
|
<br>
|
|
<b><a name="DB_JOIN_ITEM">DB_JOIN_ITEM</a></b><ul compact><li>Do not use the data value found in all the cursors as a lookup key for
|
|
the <b>primary</b>, but simply return it in the key parameter instead.
|
|
The data parameter is left unchanged.</ul>
|
|
<br>
|
|
In addition, the following flag may be set by
|
|
bitwise inclusively <b>OR</b>'ing it into the <b>flags</b> parameter:
|
|
<br>
|
|
<b><a name="DB_READ_UNCOMMITTED">DB_READ_UNCOMMITTED</a></b><ul compact><li>Configure a transactional join operation to have degree 1 isolation,
|
|
reading modified but not yet committed data. Silently ignored if the
|
|
<a href="../api_c/db_open.html#DB_READ_UNCOMMITTED">DB_READ_UNCOMMITTED</a> flag was not specified when the underlying
|
|
database was opened.</ul>
|
|
<b><a name="DB_RMW">DB_RMW</a></b><ul compact><li>Acquire write locks instead of read locks when doing the read, if
|
|
locking is configured. Setting this flag can eliminate deadlock during
|
|
a read-modify-write cycle by acquiring the write lock during the read
|
|
part of the cycle so that another thread of control acquiring a read
|
|
lock for the same item, in its own read-modify-write cycle, will not
|
|
result in deadlock.
|
|
</ul>
|
|
<br></ul>
|
|
<b><a href="../api_c/dbc_close.html">DBcursor->close</a></b><ul compact><li>Close the returned cursor and release all resources. (Closing the cursors
|
|
in <b>curslist</b> is the responsibility of the caller.)</ul>
|
|
<br>
|
|
<p>The DB->join method
|
|
returns a non-zero error value on failure
|
|
and 0 on success.
|
|
</p>
|
|
<b>Parameters</b> <br>
|
|
<b>curslist</b><ul compact><li>The <b>curslist</b> parameter contains a NULL terminated array of cursors.
|
|
Each cursor must have been initialized to refer to the key on which the
|
|
underlying database should be joined. Typically, this initialization is done
|
|
by a <a href="../api_c/dbc_get.html">DBcursor->get</a> call with the <a href="../api_c/dbc_get.html#DB_SET">DB_SET</a> flag specified. Once the
|
|
cursors have been passed as part of a <b>curslist</b>, they should not
|
|
be accessed or modified until the newly created join cursor has been closed,
|
|
or else inconsistent results may be returned.
|
|
<p>Joined values are retrieved by doing a sequential iteration over the first
|
|
cursor in the <b>curslist</b> parameter, and a nested iteration over each
|
|
secondary cursor in the order they are specified in the <b>curslist</b>
|
|
parameter. This requires database traversals to search for the current
|
|
datum in all the cursors after the first. For this reason, the best join
|
|
performance normally results from sorting the cursors from the one that
|
|
refers to the least number of data items to the one that refers to the
|
|
most. By default, DB->join does this sort on behalf of its caller.</p>
|
|
<p>For the returned join cursor to be used in a transaction-protected manner,
|
|
the cursors listed in <b>curslist</b> must have been created within the
|
|
context of the same transaction.</p></ul>
|
|
<b>dbcp</b><ul compact><li>The newly created join cursor is returned in the memory location to
|
|
which <b>dbcp</b> refers.</ul>
|
|
<b>flags</b><ul compact><li>The <b>flags</b> parameter must be set to 0 or
|
|
the following value:
|
|
<br>
|
|
<b><a name="DB_JOIN_NOSORT">DB_JOIN_NOSORT</a></b><ul compact><li>Do not sort the cursors based on the number of data items to which they
|
|
refer. If the data are structured so that cursors with many data items
|
|
also share many common elements, higher performance will result from
|
|
listing those cursors before cursors with fewer data items; that is, a
|
|
sort order other than the default. The DB_JOIN_NOSORT flag
|
|
permits applications to perform join optimization prior to calling
|
|
DB->join.</ul>
|
|
<br></ul>
|
|
<br>
|
|
<br><b>Errors</b>
|
|
<p>The DB->join method
|
|
may fail and return one of the following non-zero errors:</p>
|
|
<br>
|
|
<b>DB_REP_HANDLE_DEAD</b><ul compact><li>The database handle has been invalidated because a replication election
|
|
unrolled a committed transaction.</ul>
|
|
<br>
|
|
<br>
|
|
<b>DB_REP_LOCKOUT</b><ul compact><li>The operation was blocked by client/master synchronization.</ul>
|
|
<br>
|
|
<br>
|
|
<b>DB_SECONDARY_BAD</b><ul compact><li>A secondary index references a nonexistent primary key.</ul>
|
|
<br>
|
|
<br>
|
|
<b>EINVAL</b><ul compact><li>If cursor methods other than <a href="../api_c/dbc_get.html">DBcursor->get</a> or <a href="../api_c/dbc_close.html">DBcursor->close</a> were
|
|
called; or if an
|
|
invalid flag value or parameter was specified.</ul>
|
|
<br>
|
|
<hr size=1 noshade>
|
|
<br><b>Class</b>
|
|
<a href="../api_c/db_class.html">DB</a>
|
|
<br><b>See Also</b>
|
|
<a href="../api_c/db_list.html">Databases and Related Methods</a>
|
|
</tt>
|
|
<table width="100%"><tr><td><br></td><td align=right>
|
|
<a href="../api_c/api_core.html"><img src="../images/api.gif" alt="API"></a><a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a>
|
|
</td></tr></table>
|
|
<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font>
|
|
</body>
|
|
</html>
|