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