190 lines
10 KiB
HTML
190 lines
10 KiB
HTML
<!--$Id: db_associate.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->associate</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->associate</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->associate(DB *primary, DB_TXN *txnid, DB *secondary,
|
|
int (*callback)(DB *secondary,
|
|
const DBT *key, const DBT *data, DBT *result), u_int32_t flags);
|
|
</pre></b>
|
|
<hr size=1 noshade>
|
|
<b>Description: DB->associate</b>
|
|
<p>The DB->associate function is used to declare one database a
|
|
secondary index for a primary database. After a secondary database has
|
|
been "associated" with a primary database, all updates to the primary
|
|
will be automatically reflected in the secondary and all reads from the
|
|
secondary will return corresponding data from the primary. Note that
|
|
as primary keys must be unique for secondary indices to work, the
|
|
primary database must be configured without support for duplicate data
|
|
items. See <a href="../ref/am/second.html">Secondary indices</a> for
|
|
more information.</p>
|
|
<p>The DB->associate method
|
|
returns a non-zero error value on failure
|
|
and 0 on success.
|
|
</p>
|
|
<b>Parameters</b> <br>
|
|
<b>callback</b><ul compact><li>The <b>callback</b> parameter is a callback function that creates the
|
|
set of secondary keys corresponding to a given primary key and data
|
|
pair.
|
|
<p>The callback parameter may be NULL if both the primary and secondary
|
|
database handles were opened with the <a href="../api_c/db_open.html#DB_RDONLY">DB_RDONLY</a> flag.</p>
|
|
<p>The callback takes four arguments:</p>
|
|
<br>
|
|
<b><b>secondary</b></b><ul compact><li>The <b>secondary</b> parameter is the database handle for the secondary.</ul>
|
|
<b><b>key</b></b><ul compact><li>The <b>key</b> parameter is a <a href="../api_c/dbt_class.html">DBT</a> referencing the primary key.</ul>
|
|
<b><b>data</b></b><ul compact><li>The <b>data</b> parameter is a <a href="../api_c/dbt_class.html">DBT</a> referencing the primary data
|
|
item.</ul>
|
|
<b><b>result</b></b><ul compact><li>The <b>result</b> parameter is a zeroed <a href="../api_c/dbt_class.html">DBT</a> in which the callback
|
|
function should fill in <b>data</b> and <b>size</b> fields that describe
|
|
the secondary key or keys.</ul>
|
|
<br>
|
|
<p>The callback optionally returns some special values:</p>
|
|
<br>
|
|
<b><a name="DB_DBT_APPMALLOC">DB_DBT_APPMALLOC</a></b><ul compact><li>If the callback function needs to allocate memory for the <b>result</b>
|
|
data field (rather than simply pointing into the primary key or datum),
|
|
DB_DBT_APPMALLOC should be set in the <b>flags</b> field of the
|
|
<b>result</b> <a href="../api_c/dbt_class.html">DBT</a>, which indicates that Berkeley DB should free the
|
|
memory when it is done with it.</ul>
|
|
<b><a name="DB_DBT_MULTIPLE">DB_DBT_MULTIPLE</a></b><ul compact><li>To return multiple secondary keys, DB_DBT_MULTIPLE should be set
|
|
in the <b>flags</b> field of the <b>result</b> <a href="../api_c/dbt_class.html">DBT</a>, which
|
|
indicates Berkeley DB should treat the <b>size</b> field as the number of
|
|
secondary keys (zero or more), and the <b>data</b> field as a pointer
|
|
to an array of that number of <a href="../api_c/dbt_class.html">DBT</a>s describing the set of
|
|
secondary keys.
|
|
<p><b>When multiple secondary keys are returned, keys may not be repeated</b>.
|
|
In other words, there must be no repeated record numbers in the array
|
|
for Recno and Queue databases, and keys must not compare equally using
|
|
the secondary database's comparison function for Btree and Hash
|
|
databases. If keys are repeated, operations may fail and the secondary
|
|
may become inconsistent with the primary.</p>
|
|
<p>The DB_DBT_APPMALLOC flag may be set for any <a href="../api_c/dbt_class.html">DBT</a> in the
|
|
array of returned <a href="../api_c/dbt_class.html">DBT</a>'s to indicate that Berkeley DB should free the
|
|
memory referenced by that particular <a href="../api_c/dbt_class.html">DBT</a>'s data field when it
|
|
is done with it.</p>
|
|
<p>The DB_DBT_APPMALLOC flag may be combined with
|
|
DB_DBT_MULTIPLE in the <b>result</b> <a href="../api_c/dbt_class.html">DBT</a>'s <b>flag</b>
|
|
field to indicate that Berkeley DB should free the array once it is done with
|
|
all of the returned keys.</p></ul>
|
|
<b><a name="DB_DONOTINDEX">DB_DONOTINDEX</a></b><ul compact><li>If any key/data pair in the primary yields a null secondary key and
|
|
should be left out of the secondary index, the callback function may
|
|
optionally return DB_DONOTINDEX. Otherwise, the callback
|
|
function should return 0 in case of success or an error outside of the
|
|
Berkeley DB name space in case of failure; the error code will be returned
|
|
from the Berkeley DB call that initiated the callback.
|
|
<p>If the callback function returns DB_DONOTINDEX for any key/data
|
|
pairs in the primary database, the secondary index will not contain any
|
|
reference to those key/data pairs, and such operations as cursor
|
|
iterations and range queries will reflect only the corresponding subset
|
|
of the database. If this is not desirable, the application should
|
|
ensure that the callback function is well-defined for all possible
|
|
values and never returns DB_DONOTINDEX.</p>
|
|
<p>Returning DB_DONOTINDEX is equivalent to setting
|
|
DB_DBT_MULTIPLE on the <b>result</b> <a href="../api_c/dbt_class.html">DBT</a> and setting
|
|
the <b>size</b> field to zero.</p></ul>
|
|
<br>
|
|
<p>Berkeley DB is not re-entrant. Callback functions should not attempt to make
|
|
library calls (for example, to release locks or close open handles).
|
|
Re-entering Berkeley DB is not guaranteed to work correctly, and the results
|
|
are undefined.</p></ul>
|
|
<b>flags</b><ul compact><li>The <b>flags</b> parameter must be set to 0 or by bitwise inclusively <b>OR</b>'ing together one
|
|
or more of the following values:
|
|
<br>
|
|
<b><a name="DB_CREATE">DB_CREATE</a></b><ul compact><li>If the secondary database is empty, walk through the primary and create
|
|
an index to it in the empty secondary. This operation is potentially
|
|
very expensive.
|
|
<p>If the secondary database has been opened in an environment configured
|
|
with transactions, each put necessary for its creation will be done in
|
|
the context of a transaction created for the purpose.</p>
|
|
<p>Care should be taken not to use a newly-populated secondary database in
|
|
another thread of control until the DB->associate call has
|
|
returned successfully in the first thread.</p>
|
|
<p>If transactions are not being used, care should be taken not to modify
|
|
a primary database being used to populate a secondary database, in
|
|
another thread of control, until the DB->associate call has
|
|
returned successfully in the first thread. If transactions are being
|
|
used, Berkeley DB will perform appropriate locking and the application need
|
|
not do any special operation ordering.</p></ul>
|
|
<b><a name="DB_IMMUTABLE_KEY">DB_IMMUTABLE_KEY</a></b><ul compact><li>Specifies the secondary key is immutable.
|
|
<p>This flag can be used to optimize updates when the secondary key in a
|
|
primary record will never be changed after the primary record is
|
|
inserted. For immutable secondary keys, a best effort is made to avoid
|
|
calling the secondary callback function when primary records are
|
|
updated. This optimization may reduce the overhead of update operations
|
|
significantly if the callback function is expensive.</p>
|
|
<p>Be sure to specify this flag only if the secondary key in the primary
|
|
record is never changed. If this rule is violated, the secondary index
|
|
will become corrupted, that is, it will become out of sync with the
|
|
primary.</p></ul>
|
|
<br></ul>
|
|
<b>primary</b><ul compact><li>The <b>primary</b> parameter should be a database handle for the primary
|
|
database that is to be indexed.</ul>
|
|
<b>secondary</b><ul compact><li>The <b>secondary</b> parameter should be an open database handle of
|
|
either a newly created and empty database that is to be used to store
|
|
a secondary index, or of a database that was previously associated with
|
|
the same primary and contains a secondary index. Note that it is not
|
|
safe to associate as a secondary database a handle that is in use by
|
|
another thread of control or has open cursors. If the handle was opened
|
|
with the <a href="../api_c/env_open.html#DB_THREAD">DB_THREAD</a> flag it is safe to use it in multiple threads
|
|
of control after the DB->associate method has returned. Note also
|
|
that either secondary keys must be unique or the secondary database must
|
|
be configured with support for duplicate data items.</ul>
|
|
<b>txnid</b><ul compact><li>If the operation is part of an application-specified transaction, the
|
|
<b>txnid</b> parameter is a transaction handle returned from
|
|
<a href="../api_c/txn_begin.html">DB_ENV->txn_begin</a>; if the operation is part of a Berkeley DB Concurrent Data Store group, the
|
|
<b>txnid</b> parameter is a handle returned from
|
|
<a href="../api_c/env_cdsgroup_begin.html">DB_ENV->cdsgroup_begin</a>; otherwise NULL.
|
|
If no transaction handle is
|
|
specified, but the
|
|
operation occurs in a transactional
|
|
database,
|
|
the operation will be implicitly transaction protected.
|
|
</ul>
|
|
<br>
|
|
<br><b>Errors</b>
|
|
<p>The DB->associate 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>EINVAL</b><ul compact><li>If the secondary database handle has already been associated with this or
|
|
another database handle; the secondary database handle is not open; the
|
|
primary database has been configured to allow duplicates; 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>
|