1<!--$Id: db_associate.so,v 10.47 2007/10/24 16:06:06 bostic Exp $--> 2<!--Copyright (c) 1997,2008 Oracle. All rights reserved.--> 3<!--See the file LICENSE for redistribution information.--> 4<html> 5<head> 6<title>Berkeley DB: Db::associate</title> 7<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> 8<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++"> 9</head> 10<body bgcolor=white> 11<table width="100%"><tr valign=top> 12<td> 13<b>Db::associate</b> 14</td> 15<td align=right> 16<a href="/api_cxx/api_core.html"><img src="/images/api.gif" alt="API"></a> 17<a href="/ref/toc.html"><img src="/images/ref.gif" alt="Ref"></a></td> 18</tr></table> 19<hr size=1 noshade> 20<tt> 21<b><pre> 22#include <db_cxx.h> 23<p> 24int 25Db::associate(DbTxn *txnid, Db *secondary, 26 int (*callback)(Db *secondary, 27 const Dbt *key, const Dbt *data, Dbt *result), u_int32_t flags); 28</pre></b> 29<hr size=1 noshade> 30<b>Description: Db::associate</b> 31<p>The Db::associate function is used to declare one database a 32secondary index for a primary database. After a secondary database has 33been "associated" with a primary database, all updates to the primary 34will be automatically reflected in the secondary and all reads from the 35secondary will return corresponding data from the primary. Note that 36as primary keys must be unique for secondary indices to work, the 37primary database must be configured without support for duplicate data 38items. See <a href="/ref/am/second.html">Secondary indices</a> for 39more information.</p> 40<p>The Db::associate method 41either returns a non-zero error value 42or throws an exception that encapsulates a non-zero error value on 43failure, and returns 0 on success. 44</p> 45<b>Parameters</b> <br> 46 <b>callback</b><ul compact><li>The <b>callback</b> parameter is a callback function that creates the 47set of secondary keys corresponding to a given primary key and data 48pair. 49<p>The callback parameter may be NULL if both the primary and secondary 50database handles were opened with the <a href="/api_cxx/db_open.html#DB_RDONLY">DB_RDONLY</a> flag.</p> 51<p>The callback takes four arguments:</p> 52<br> 53<b><b>secondary</b></b><ul compact><li>The <b>secondary</b> parameter is the database handle for the secondary.</ul> 54<b><b>key</b></b><ul compact><li>The <b>key</b> parameter is a <a href="/api_cxx/dbt_class.html">Dbt</a> referencing the primary key.</ul> 55<b><b>data</b></b><ul compact><li>The <b>data</b> parameter is a <a href="/api_cxx/dbt_class.html">Dbt</a> referencing the primary data 56item.</ul> 57<b><b>result</b></b><ul compact><li>The <b>result</b> parameter is a zeroed <a href="/api_cxx/dbt_class.html">Dbt</a> in which the callback 58function should fill in <b>data</b> and <b>size</b> fields that describe 59the secondary key or keys.</ul> 60<br> 61<p>The callback optionally returns some special values:</p> 62<br> 63<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> 64data field (rather than simply pointing into the primary key or datum), 65DB_DBT_APPMALLOC should be set in the <b>flags</b> field of the 66<b>result</b> <a href="/api_cxx/dbt_class.html">Dbt</a>, which indicates that Berkeley DB should free the 67memory when it is done with it.</ul> 68<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 69in the <b>flags</b> field of the <b>result</b> <a href="/api_cxx/dbt_class.html">Dbt</a>, which 70indicates Berkeley DB should treat the <b>size</b> field as the number of 71secondary keys (zero or more), and the <b>data</b> field as a pointer 72to an array of that number of <a href="/api_cxx/dbt_class.html">Dbt</a>s describing the set of 73secondary keys. 74<p><b>When multiple secondary keys are returned, keys may not be repeated</b>. 75In other words, there must be no repeated record numbers in the array 76for Recno and Queue databases, and keys must not compare equally using 77the secondary database's comparison function for Btree and Hash 78databases. If keys are repeated, operations may fail and the secondary 79may become inconsistent with the primary.</p> 80<p>The DB_DBT_APPMALLOC flag may be set for any <a href="/api_cxx/dbt_class.html">Dbt</a> in the 81array of returned <a href="/api_cxx/dbt_class.html">Dbt</a>'s to indicate that Berkeley DB should free the 82memory referenced by that particular <a href="/api_cxx/dbt_class.html">Dbt</a>'s data field when it 83is done with it.</p> 84<p>The DB_DBT_APPMALLOC flag may be combined with 85DB_DBT_MULTIPLE in the <b>result</b> <a href="/api_cxx/dbt_class.html">Dbt</a>'s <b>flag</b> 86field to indicate that Berkeley DB should free the array once it is done with 87all of the returned keys.</p></ul> 88<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 89should be left out of the secondary index, the callback function may 90optionally return DB_DONOTINDEX. Otherwise, the callback 91function should return 0 in case of success or an error outside of the 92Berkeley DB name space in case of failure; the error code will be returned 93from the Berkeley DB call that initiated the callback. 94<p>If the callback function returns DB_DONOTINDEX for any key/data 95pairs in the primary database, the secondary index will not contain any 96reference to those key/data pairs, and such operations as cursor 97iterations and range queries will reflect only the corresponding subset 98of the database. If this is not desirable, the application should 99ensure that the callback function is well-defined for all possible 100values and never returns DB_DONOTINDEX.</p> 101<p>Returning DB_DONOTINDEX is equivalent to setting 102DB_DBT_MULTIPLE on the <b>result</b> <a href="/api_cxx/dbt_class.html">Dbt</a> and setting 103the <b>size</b> field to zero.</p></ul> 104<br> 105<p>Berkeley DB is not re-entrant. Callback functions should not attempt to make 106library calls (for example, to release locks or close open handles). 107Re-entering Berkeley DB is not guaranteed to work correctly, and the results 108are undefined.</p></ul> 109 <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 110or more of the following values: 111<br> 112<b><a name="DB_CREATE">DB_CREATE</a></b><ul compact><li>If the secondary database is empty, walk through the primary and create 113an index to it in the empty secondary. This operation is potentially 114very expensive. 115<p>If the secondary database has been opened in an environment configured 116with transactions, each put necessary for its creation will be done in 117the context of a transaction created for the purpose.</p> 118<p>Care should be taken not to use a newly-populated secondary database in 119another thread of control until the Db::associate call has 120returned successfully in the first thread.</p> 121<p>If transactions are not being used, care should be taken not to modify 122a primary database being used to populate a secondary database, in 123another thread of control, until the Db::associate call has 124returned successfully in the first thread. If transactions are being 125used, Berkeley DB will perform appropriate locking and the application need 126not do any special operation ordering.</p></ul> 127<b><a name="DB_IMMUTABLE_KEY">DB_IMMUTABLE_KEY</a></b><ul compact><li>Specifies the secondary key is immutable. 128<p>This flag can be used to optimize updates when the secondary key in a 129primary record will never be changed after the primary record is 130inserted. For immutable secondary keys, a best effort is made to avoid 131calling the secondary callback function when primary records are 132updated. This optimization may reduce the overhead of update operations 133significantly if the callback function is expensive.</p> 134<p>Be sure to specify this flag only if the secondary key in the primary 135record is never changed. If this rule is violated, the secondary index 136will become corrupted, that is, it will become out of sync with the 137primary.</p></ul> 138<br></ul> 139 <b>primary</b><ul compact><li>The associate method called should be a method of a database handle for 140the primary database that is to be indexed.</ul> 141 <b>secondary</b><ul compact><li>The <b>secondary</b> parameter should be an open database handle of 142either a newly created and empty database that is to be used to store 143a secondary index, or of a database that was previously associated with 144the same primary and contains a secondary index. Note that it is not 145safe to associate as a secondary database a handle that is in use by 146another thread of control or has open cursors. If the handle was opened 147with the <a href="/api_cxx/env_open.html#DB_THREAD">DB_THREAD</a> flag it is safe to use it in multiple threads 148of control after the Db::associate method has returned. Note also 149that either secondary keys must be unique or the secondary database must 150be configured with support for duplicate data items.</ul> 151 <b>txnid</b><ul compact><li>If the operation is part of an application-specified transaction, the 152<b>txnid</b> parameter is a transaction handle returned from 153<a href="/api_cxx/txn_begin.html">DbEnv::txn_begin</a>; if the operation is part of a Berkeley DB Concurrent Data Store group, the 154<b>txnid</b> parameter is a handle returned from 155<a href="/api_cxx/env_cdsgroup_begin.html">DbEnv::cdsgroup_begin</a>; otherwise NULL. 156If no transaction handle is 157specified, but the 158operation occurs in a transactional 159database, 160the operation will be implicitly transaction protected. 161</ul> 162<br> 163<br><b>Errors</b> 164<p>The Db::associate method 165may fail and throw 166<a href="/api_cxx/except_class.html">DbException</a>, 167encapsulating one of the following non-zero errors, or return one of 168the following non-zero errors:</p> 169<br> 170<b>DB_REP_HANDLE_DEAD</b><ul compact><li>The database handle has been invalidated because a replication election 171unrolled a committed transaction.</ul> 172<br> 173<br> 174<b>DB_REP_LOCKOUT</b><ul compact><li>The operation was blocked by client/master synchronization.</ul> 175<br> 176<br> 177<b>EINVAL</b><ul compact><li>If the secondary database handle has already been associated with this or 178another database handle; the secondary database handle is not open; the 179primary database has been configured to allow duplicates; or if an 180invalid flag value or parameter was specified.</ul> 181<br> 182<hr size=1 noshade> 183<br><b>Class</b> 184<a href="/api_cxx/db_class.html">Db</a> 185<br><b>See Also</b> 186<a href="/api_cxx/db_list.html">Databases and Related Methods</a> 187</tt> 188<table width="100%"><tr><td><br></td><td align=right> 189<a href="/api_cxx/api_core.html"><img src="/images/api.gif" alt="API"></a><a href="/ref/toc.html"><img src="/images/ref.gif" alt="Ref"></a> 190</td></tr></table> 191<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 192</body> 193</html> 194