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