1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml"> 4 <head> 5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 6 <title>DB->associate()</title> 7 <link rel="stylesheet" href="apiReference.css" type="text/css" /> 8 <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /> 9 <link rel="start" href="index.html" title="Berkeley DB C API Reference" /> 10 <link rel="up" href="db.html" title="Chapter��2.�� The DB Handle" /> 11 <link rel="prev" href="db.html" title="Chapter��2.�� The DB Handle" /> 12 <link rel="next" href="dbassociate_foreign.html" title="DB->associate_foreign()" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">DB->associate()</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="db.html">Prev</a>��</td> 22 <th width="60%" align="center">Chapter��2.�� 23 The DB Handle 24 </th> 25 <td width="20%" align="right">��<a accesskey="n" href="dbassociate_foreign.html">Next</a></td> 26 </tr> 27 </table> 28 <hr /> 29 </div> 30 <div class="sect1" lang="en" xml:lang="en"> 31 <div class="titlepage"> 32 <div> 33 <div> 34 <h2 class="title" style="clear: both"><a id="dbassociate"></a>DB->associate()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db.h> 39 40int 41DB->associate(DB *primary, DB_TXN *txnid, DB *secondary, 42 int (*callback)(DB *secondary, 43 const DBT *key, const DBT *data, DBT *result), u_int32_t flags); </pre> 44 <p> 45 The <code class="methodname">DB->associate()</code> function is used to declare one database a 46 secondary index for a primary database. The 47 <a class="link" href="db.html" title="Chapter��2.�� The DB Handle">DB</a> handle that you call the 48 <code class="methodname">associate()</code> method from is the primary 49 database. 50 </p> 51 <p> 52 After a secondary database has been "associated" with a primary 53 database, all updates to the primary will be automatically 54 reflected in the secondary and all reads from the secondary will 55 return corresponding data from the primary. Note that as primary 56 keys must be unique for secondary indices to work, the primary 57 database must be configured without support for duplicate data 58 items. See 59 <a href="../../programmer_reference/am_second.html" class="olink">Secondary Indices</a> 60 in the <em class="citetitle">Berkeley DB Programmer's Reference Guide</em> for more information. 61 </p> 62 <p> 63 The <code class="methodname">DB->associate()</code> <span> 64 <span> 65 method returns a non-zero error value on failure and 0 on success. 66 </span> 67 68 </span> 69 </p> 70 <div class="sect2" lang="en" xml:lang="en"> 71 <div class="titlepage"> 72 <div> 73 <div> 74 <h3 class="title"><a id="id1630489"></a>Parameters</h3> 75 </div> 76 </div> 77 </div> 78 <div class="sect3" lang="en" xml:lang="en"> 79 <div class="titlepage"> 80 <div> 81 <div> 82 <h4 class="title"><a id="id1630915"></a>callback</h4> 83 </div> 84 </div> 85 </div> 86 <p> 87 The <span class="bold"><strong>callback</strong></span> parameter is a callback 88 function that creates the set of secondary keys corresponding to a 89 given primary key and data pair. 90 </p> 91 <p> 92 The callback parameter may be NULL if both the primary and secondary 93 database handles were opened with the 94 <a class="link" href="dbopen.html#dbopen_DB_RDONLY">DB_RDONLY</a> flag. 95 </p> 96 <p> 97 The callback takes four arguments: 98 </p> 99 <div class="itemizedlist"> 100 <ul type="disc"> 101 <li> 102 <p> 103 <code class="literal">secondary</code> 104 </p> 105 <p> 106 The <span class="bold"><strong>secondary</strong></span> parameter is the 107 database handle for the secondary. 108 </p> 109 </li> 110 <li> 111 <p> 112 <code class="literal">key</code> 113 </p> 114 <p> 115 The <span class="bold"><strong>key</strong></span> parameter is a 116 <a class="link" href="dbt.html" title="Chapter��4.�� The DBT Handle">DBT</a> referencing the primary key. 117 </p> 118 </li> 119 <li> 120 <p> 121 <code class="literal">data</code> 122 </p> 123 <p> 124 The <span class="bold"><strong>data</strong></span> parameter is a 125 <a class="link" href="dbt.html" title="Chapter��4.�� The DBT Handle">DBT</a> referencing the primary data 126 item. 127 </p> 128 </li> 129 <li> 130 <p> 131 <code class="literal">result</code> 132 </p> 133 <p> 134 The <span class="bold"><strong>result</strong></span> parameter is a zeroed 135 <a class="link" href="dbt.html" title="Chapter��4.�� The DBT Handle">DBT</a> in which the callback 136 function should fill in <span class="bold"><strong>data</strong></span> and 137 <span class="bold"><strong>size</strong></span> fields that describe the 138 secondary key or keys. 139 </p> 140 </li> 141 </ul> 142 </div> 143 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> 144 <h3 class="title">Note</h3> 145 <p> 146 Berkeley DB is not re-entrant. Callback functions should not 147 attempt to make library calls (for example, to release locks or 148 close open handles). Re-entering Berkeley DB is not guaranteed 149 to work correctly, and the results are undefined. 150 </p> 151 </div> 152 <p> 153 The result <a class="link" href="dbt.html" title="Chapter��4.�� The DBT Handle">DBT</a> can 154 have the following flags set in its 155 <span class="bold"><strong>flags</strong></span> field: 156 </p> 157 <div class="itemizedlist"> 158 <ul type="disc"> 159 <li> 160 <p><a id="associate_DB_DBT_APPMALLOC"></a> 161 <code class="literal">DB_DBT_APPMALLOC</code> 162 </p> 163 <p> 164 If the callback function needs to allocate memory for the <span class="bold"><strong>result</strong></span> data field (rather than simply pointing 165 into the primary key or datum), DB_DBT_APPMALLOC should be set in the 166 <span class="bold"><strong>flags</strong></span> field of the 167 <span class="bold"><strong>result</strong></span> 168 <a class="link" href="dbt.html" title="Chapter��4.�� The DBT Handle">DBT</a>, which indicates that 169 Berkeley DB should free the memory when it is done with it. 170 </p> 171 </li> 172 <li> 173 <p><a id="associate_DB_DBT_MULTIPLE"></a> 174 <code class="literal">DB_DBT_MULTIPLE</code> 175 </p> 176 <p> 177 To return multiple secondary keys, DB_DBT_MULTIPLE should be set in 178 the <span class="bold"><strong>flags</strong></span> field of the <span class="bold"><strong>result</strong></span> <a class="link" href="dbt.html" title="Chapter��4.�� The DBT Handle">DBT</a>, 179 which indicates Berkeley DB should treat the 180 <span class="bold"><strong>size</strong></span> field as the 181 number of secondary keys (zero or more), and the <span class="bold"><strong>data</strong></span> field as a pointer to an array of that 182 number of <a class="link" href="dbt.html" title="Chapter��4.�� The DBT Handle">DBT</a>s describing 183 the set of secondary keys. 184 </p> 185 <p> 186 <span class="bold"><strong>When multiple secondary keys are returned, keys 187 may not be repeated</strong></span>. In other words, there must be no 188 repeated record numbers in the array for Recno and Queue databases, 189 and keys must not compare equally using the secondary database's 190 comparison function for Btree and Hash databases. If keys are 191 repeated, operations may fail and the secondary may become 192 inconsistent with the primary. 193 </p> 194 <p> 195 The DB_DBT_APPMALLOC flag may be set for any 196 <a class="link" href="dbt.html" title="Chapter��4.�� The DBT Handle">DBT</a> in the array of returned 197 <a class="link" href="dbt.html" title="Chapter��4.�� The DBT Handle">DBT</a>'s to indicate that 198 Berkeley DB should free the memory referenced by that particular 199 <a class="link" href="dbt.html" title="Chapter��4.�� The DBT Handle">DBT</a>'s data field when it 200 is done with it. 201 </p> 202 <p> 203 The DB_DBT_APPMALLOC flag may be combined with DB_DBT_MULTIPLE in the 204 <span class="bold"><strong>result</strong></span> 205 <a class="link" href="dbt.html" title="Chapter��4.�� The DBT Handle">DBT</a>'s <span class="bold"><strong>flag</strong></span> field to indicate that Berkeley DB should 206 free the array once it is done with all of the returned keys. 207 </p> 208 </li> 209 </ul> 210 </div> 211 <p> 212 In addition, the callback can optionally return the following special value: 213 </p> 214 <div class="itemizedlist"> 215 <ul type="disc"> 216 <li> 217 <p><a id="associate_DB_DONOTINDEX"></a> 218 <code class="literal">DB_DONOTINDEX</code> 219 </p> 220 <p> 221 If any key/data pair in the primary yields a null secondary key and 222 should be left out of the secondary index, the callback function may 223 optionally return DB_DONOTINDEX. Otherwise, the callback function 224 should return 0 in case of success or an error outside of the Berkeley 225 DB name space in case of failure; the error code will be returned from 226 the Berkeley DB call that initiated the callback. 227 </p> 228 <p> 229 If the callback function returns DB_DONOTINDEX for any key/data pairs 230 in the primary database, the secondary index will not contain any 231 reference to those key/data pairs, and such operations as cursor 232 iterations and range queries will reflect only the corresponding 233 subset of the database. If this is not desirable, the application 234 should ensure that the callback function is well-defined for all 235 possible values and never returns DB_DONOTINDEX. 236 </p> 237 <p> 238 Returning DB_DONOTINDEX is equivalent to setting DB_DBT_MULTIPLE on 239 the <span class="bold"><strong>result</strong></span> 240 <a class="link" href="dbt.html" title="Chapter��4.�� The DBT Handle">DBT</a> and setting the <span class="bold"><strong>size</strong></span> field to zero. 241 </p> 242 </li> 243 </ul> 244 </div> 245 </div> 246 <div class="sect3" lang="en" xml:lang="en"> 247 <div class="titlepage"> 248 <div> 249 <div> 250 <h4 class="title"><a id="id1631678"></a>flags</h4> 251 </div> 252 </div> 253 </div> 254 <p> 255 The <span class="bold"><strong>flags</strong></span> parameter must be set to 0 256 or by bitwise inclusively <span class="bold"><strong>OR</strong></span>'ing 257 together one or more of the following values: 258 </p> 259 <div class="itemizedlist"> 260 <ul type="disc"> 261 <li> 262 <p><a id="associate_DB_CREATE"></a> 263 <code class="literal">DB_CREATE</code> 264 </p> 265 <p> 266 If the secondary database is empty, walk through the primary and 267 create an index to it in the empty secondary. This operation is 268 potentially very expensive. 269 </p> 270 <p> 271 If the secondary database has been opened in an environment 272 configured with transactions, the entire secondary index 273 creation is performed in the context of a single transaction. 274 </p> 275 <p> 276 Care should be taken not to use a newly-populated secondary database 277 in another thread of control until the <code class="methodname">DB->associate()</code> call has 278 returned successfully in the first thread. 279 </p> 280 <p> 281 If transactions are not being used, care should be taken not to modify 282 a primary database being used to populate a secondary database, in 283 another thread of control, until the <code class="methodname">DB->associate()</code> call has 284 returned successfully in the first thread. If transactions are being 285 used, Berkeley DB will perform appropriate locking and the application 286 need not do any special operation ordering. 287 </p> 288 </li> 289 <li> 290 <p><a id="associate_DB_IMMUTABLE_KEY"></a> 291 <code class="literal">DB_IMMUTABLE_KEY</code> 292 </p> 293 <p> 294 Specifies the secondary key is immutable. 295 </p> 296 <p> 297 This flag can be used to optimize updates when the secondary key in a 298 primary record will never be changed after the primary record is 299 inserted. For immutable secondary keys, a best effort is made to 300 avoid calling the secondary callback function when primary records are 301 updated. This optimization may reduce the overhead of update 302 operations significantly if the callback function is expensive. 303 </p> 304 <p> 305 Be sure to specify this flag only if the secondary key in the primary 306 record is never changed. If this rule is violated, the secondary 307 index will become corrupted, that is, it will become out of sync with 308 the primary. 309 </p> 310 </li> 311 </ul> 312 </div> 313 </div> 314 <div class="sect3" lang="en" xml:lang="en"> 315 <div class="titlepage"> 316 <div> 317 <div> 318 <h4 class="title"><a id="id1631257"></a>primary</h4> 319 </div> 320 </div> 321 </div> 322 <p> 323 The <span class="bold"><strong>primary</strong></span> parameter should be a 324 database handle for the primary database that is to be indexed. 325 </p> 326 </div> 327 <div class="sect3" lang="en" xml:lang="en"> 328 <div class="titlepage"> 329 <div> 330 <div> 331 <h4 class="title"><a id="id1631270"></a>secondary</h4> 332 </div> 333 </div> 334 </div> 335 <p> 336 The <span class="bold"><strong>secondary</strong></span> parameter should be an 337 open database handle of either a newly created and empty database that 338 is to be used to store a secondary index, or of a database that was 339 previously associated with the same primary and contains a secondary 340 index. Note that it is not safe to associate as a secondary database 341 a handle that is in use by another thread of control or has open 342 cursors. If the handle was opened with the 343 <a class="link" href="envopen.html#envopen_DB_THREAD">DB_THREAD</a> flag it is 344 safe to use it in multiple threads of control after the 345 <code class="methodname">DB->associate()</code> method has returned. Note also that either secondary 346 keys must be unique or the secondary database must be configured with 347 support for duplicate data items. 348 </p> 349 </div> 350 <div class="sect3" lang="en" xml:lang="en"> 351 <div class="titlepage"> 352 <div> 353 <div> 354 <h4 class="title"><a id="id1631062"></a>txnid</h4> 355 </div> 356 </div> 357 </div> 358 <p> 359 If the operation is part of an application-specified transaction, the 360 <span class="bold"><strong>txnid</strong></span> parameter is a transaction 361 handle returned from <a class="xref" href="txnbegin.html" title="DB_ENV->txn_begin()">DB_ENV->txn_begin()</a>; 362 if the operation is part of a Berkeley DB Concurrent Data Store group, the 363 <span class="bold"><strong>txnid</strong></span> parameter is a handle returned 364 from <a class="xref" href="envcdsgroup_begin.html" title="DB_ENV->cdsgroup_begin()">DB_ENV->cdsgroup_begin()</a>; 365 otherwise NULL. If no transaction handle is specified, but the 366 operation occurs in a transactional database, the operation will be 367 implicitly transaction protected. 368 </p> 369 </div> 370 </div> 371 <div class="sect2" lang="en" xml:lang="en"> 372 <div class="titlepage"> 373 <div> 374 <div> 375 <h3 class="title"><a id="id1631057"></a>Errors</h3> 376 </div> 377 </div> 378 </div> 379 <p> 380 The <code class="methodname">DB->associate()</code> <span> 381 <span> 382 method may fail and return one of the following non-zero errors: 383 </span> 384 385 </span> 386 </p> 387 <div class="sect3" lang="en" xml:lang="en"> 388 <div class="titlepage"> 389 <div> 390 <div> 391 <h4 class="title"><a id="id1631763"></a> DB_REP_HANDLE_DEAD</h4> 392 </div> 393 </div> 394 </div> 395 <p> 396 When a client synchronizes with the master, it is possible for committed 397 transactions to be rolled back. This invalidates all the database and cursor 398 handles opened in the replication environment. Once this occurs, an attempt to use 399 such a handle will 400 401 return <code class="literal">DB_REP_HANDLE_DEAD</code>. 402 The application will need to discard the handle and open a new one in order to 403 continue processing. 404 </p> 405 </div> 406 <div class="sect3" lang="en" xml:lang="en"> 407 <div class="titlepage"> 408 <div> 409 <div> 410 <h4 class="title"><a id="id1631242"></a>DB_REP_LOCKOUT</h4> 411 </div> 412 </div> 413 </div> 414 <p> 415 The operation was blocked by client/master synchronization. 416 </p> 417 </div> 418 <div class="sect3" lang="en" xml:lang="en"> 419 <div class="titlepage"> 420 <div> 421 <div> 422 <h4 class="title"><a id="id1631320"></a>EINVAL</h4> 423 </div> 424 </div> 425 </div> 426 <p> 427 If the secondary database handle has already been associated with this 428 or another database handle; the secondary database handle is not open; 429 the primary database has been configured to allow duplicates; or if an 430 invalid flag value or parameter was specified. 431 </p> 432 </div> 433 </div> 434 <div class="sect2" lang="en" xml:lang="en"> 435 <div class="titlepage"> 436 <div> 437 <div> 438 <h3 class="title"><a id="id1630627"></a>Class</h3> 439 </div> 440 </div> 441 </div> 442 <p> 443 <a class="link" href="db.html" title="Chapter��2.�� The DB Handle">DB</a> 444 </p> 445 </div> 446 <div class="sect2" lang="en" xml:lang="en"> 447 <div class="titlepage"> 448 <div> 449 <div> 450 <h3 class="title"><a id="id1630946"></a>See Also</h3> 451 </div> 452 </div> 453 </div> 454 <p> 455 <a class="xref" href="db.html#dblist" title="Database and Related Methods">Database and Related Methods</a> 456 </p> 457 </div> 458 </div> 459 <div class="navfooter"> 460 <hr /> 461 <table width="100%" summary="Navigation footer"> 462 <tr> 463 <td width="40%" align="left"><a accesskey="p" href="db.html">Prev</a>��</td> 464 <td width="20%" align="center"> 465 <a accesskey="u" href="db.html">Up</a> 466 </td> 467 <td width="40%" align="right">��<a accesskey="n" href="dbassociate_foreign.html">Next</a></td> 468 </tr> 469 <tr> 470 <td width="40%" align="left" valign="top">Chapter��2.�� 471 The DB Handle 472 ��</td> 473 <td width="20%" align="center"> 474 <a accesskey="h" href="index.html">Home</a> 475 </td> 476 <td width="40%" align="right" valign="top">��DB->associate_foreign()</td> 477 </tr> 478 </table> 479 </div> 480 </body> 481</html> 482