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->join()</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="dbget_type.html" title="DB->get_type()" /> 12 <link rel="next" href="dbkey_range.html" title="DB->key_range()" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">DB->join()</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="dbget_type.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="dbkey_range.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="dbjoin"></a>DB->join()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db.h> 39 40int 41DB->join(DB *primary, 42 DBC **curslist, DBC **dbcp, u_int32_t flags); </pre> 43 <p> 44 The <code class="methodname">DB->join()</code> method creates a specialized join cursor for use in 45 performing equality or natural joins on secondary indices. For 46 information on how to organize your data to use this functionality, 47 see <a href="../../programmer_reference/am_cursor.html#am_join" class="olink">Equality join</a>. 48 </p> 49 <p> 50 The <code class="methodname">DB->join()</code> method is called using the 51 <a class="link" href="db.html" title="Chapter��2.�� The DB Handle">DB</a> handle of the primary 52 database. 53 </p> 54 <p> 55 The join cursor supports only the <a class="xref" href="dbcget.html" title="DBcursor->get()">DBcursor->get()</a> and 56 <a class="xref" href="dbcclose.html" title="DBcursor->close()">DBcursor->close()</a> cursor functions: 57 </p> 58 <div class="itemizedlist"> 59 <ul type="disc"> 60 <li> 61 <p> 62 <span class="bold"><strong> <a class="xref" href="dbcget.html" title="DBcursor->get()">DBcursor->get()</a> </strong></span> 63 </p> 64 <p> 65 Iterates over the values associated with the keys to which each item 66 in <span class="bold"><strong>curslist</strong></span> was initialized. Any 67 data value that appears in all items specified by the <span class="bold"><strong>curslist</strong></span> parameter is then used as a key into 68 the <span class="bold"><strong>primary</strong></span>, and the key/data pair 69 found in the <span class="bold"><strong>primary</strong></span> is returned. The 70 <span class="bold"><strong>flags</strong></span> parameter must be set to 0 or 71 the following value: 72 73 </p> 74 <div class="itemizedlist"> 75 <ul type="circle"> 76 <li> 77 <p> 78 <span class="bold"><strong><code class="literal">DB_JOIN_ITEM</code></strong></span> 79 </p> 80 <p> 81 Do not use the data value found in all the cursors as a lookup key for 82 the <span class="bold"><strong>primary</strong></span>, but simply return it in 83 the key parameter instead. The data parameter is left unchanged. 84 </p> 85 </li> 86 </ul> 87 </div> 88 <p> 89 In addition, the following flag may be set by bitwise inclusively 90 <span class="bold"><strong>OR</strong></span>'ing it into the <span class="bold"><strong>flags</strong></span> parameter: 91 </p> 92 <div class="itemizedlist"> 93 <ul type="circle"> 94 <li> 95 <p> 96 <span class="bold"><strong> <code class="literal">DB_READ_UNCOMMITTED</code></strong></span> 97 </p> 98 <p> 99 Configure a transactional join operation to have degree 1 isolation, 100 reading modified but not yet committed data. Silently ignored if the 101 <a class="link" href="dbopen.html#dbopen_DB_READ_UNCOMMITTED">DB_READ_UNCOMMITTED</a> 102 flag was not specified when the underlying database was opened. 103 </p> 104 </li> 105 <li> 106 <p> 107 <span class="bold"><strong><code class="literal">DB_RMW</code></strong></span> 108 </p> 109 <p> 110 Acquire write locks instead of read locks when doing the read, if 111 locking is configured. Setting this flag can eliminate deadlock 112 during a read-modify-write cycle by acquiring the write lock during 113 the read part of the cycle so that another thread of control acquiring 114 a read lock for the same item, in its own read-modify-write cycle, 115 will not result in deadlock. 116 </p> 117 </li> 118 </ul> 119 </div> 120 </li> 121 <li> 122 <p> 123 <span class="bold"><strong> <a class="xref" href="dbcclose.html" title="DBcursor->close()">DBcursor->close()</a> </strong></span> 124 </p> 125 <p> 126 Close the returned cursor and release all resources. (Closing the 127 cursors in <span class="bold"><strong>curslist</strong></span> is the 128 responsibility of the caller.) 129 </p> 130 </li> 131 </ul> 132 </div> 133 <p> 134 The <code class="methodname">DB->join()</code> <span> 135 <span> 136 method returns a non-zero error value on failure and 0 on success. 137 </span> 138 139 </span> 140 </p> 141 <div class="sect2" lang="en" xml:lang="en"> 142 <div class="titlepage"> 143 <div> 144 <div> 145 <h3 class="title"><a id="id1639198"></a>Parameters</h3> 146 </div> 147 </div> 148 </div> 149 <div class="sect3" lang="en" xml:lang="en"> 150 <div class="titlepage"> 151 <div> 152 <div> 153 <h4 class="title"><a id="id1638634"></a>curslist</h4> 154 </div> 155 </div> 156 </div> 157 <p> 158 The <span class="bold"><strong>curslist</strong></span> parameter contains a 159 NULL terminated array of cursors. Each cursor must have been 160 initialized to refer to the key on which the underlying database 161 should be joined. Typically, this initialization is done by a 162 <a class="xref" href="dbcget.html" title="DBcursor->get()">DBcursor->get()</a> call with the 163 <a class="link" href="dbcget.html#dbcget_DB_SET">DB_SET</a> flag 164 specified. Once the cursors have been passed as part of a <span class="bold"><strong>curslist</strong></span>, they should not be accessed or 165 modified until the newly created join cursor has been closed, or else 166 inconsistent results may be returned. 167 </p> 168 <p> 169 Joined values are retrieved by doing a sequential iteration over the 170 first cursor in the <span class="bold"><strong>curslist</strong></span> 171 parameter, and a nested iteration over each secondary cursor in the 172 order they are specified in the <span class="bold"><strong>curslist</strong></span> parameter. This requires database 173 traversals to search for the current datum in all the cursors after 174 the first. For this reason, the best join performance normally 175 results from sorting the cursors from the one that refers to the least 176 number of data items to the one that refers to the most. By default, 177 <code class="methodname">DB->join()</code> does this sort on behalf of its caller. 178 </p> 179 <p> 180 For the returned join cursor to be used in a transaction-protected 181 manner, the cursors listed in <span class="bold"><strong>curslist</strong></span> must have been created within the 182 context of the same transaction. 183 </p> 184 </div> 185 <div class="sect3" lang="en" xml:lang="en"> 186 <div class="titlepage"> 187 <div> 188 <div> 189 <h4 class="title"><a id="id1639129"></a>dbcp</h4> 190 </div> 191 </div> 192 </div> 193 <p> 194 The newly created join cursor is returned in the memory location to 195 which <span class="bold"><strong>dbcp</strong></span> refers. 196 </p> 197 </div> 198 <div class="sect3" lang="en" xml:lang="en"> 199 <div class="titlepage"> 200 <div> 201 <div> 202 <h4 class="title"><a id="id1639122"></a>flags</h4> 203 </div> 204 </div> 205 </div> 206 <p> 207 The <span class="bold"><strong>flags</strong></span> parameter must be set to 0 208 or the following value: 209 </p> 210 <div class="itemizedlist"> 211 <ul type="disc"> 212 <li> 213 <p><a id="join_DB_JOIN_NOSORT"></a> 214 <code class="literal">DB_JOIN_NOSORT</code> 215 </p> 216 <p> 217 Do not sort the cursors based on the number of data items to which 218 they refer. If the data are structured so that cursors with many data 219 items also share many common elements, higher performance will result 220 from listing those cursors before cursors with fewer data items; that 221 is, a sort order other than the default. The DB_JOIN_NOSORT flag 222 permits applications to perform join optimization prior to calling the 223 <code class="methodname">DB->join()</code> method. 224 </p> 225 </li> 226 </ul> 227 </div> 228 </div> 229 </div> 230 <div class="sect2" lang="en" xml:lang="en"> 231 <div class="titlepage"> 232 <div> 233 <div> 234 <h3 class="title"><a id="id1639148"></a>Errors</h3> 235 </div> 236 </div> 237 </div> 238 <p> 239 The <code class="methodname">DB->join()</code> <span> 240 <span> 241 method may fail and return one of the following non-zero errors: 242 </span> 243 244 </span> 245 </p> 246 <div class="sect3" lang="en" xml:lang="en"> 247 <div class="titlepage"> 248 <div> 249 <div> 250 <h4 class="title"><a id="id1639332"></a> DB_REP_HANDLE_DEAD</h4> 251 </div> 252 </div> 253 </div> 254 <p> 255 When a client synchronizes with the master, it is possible for committed 256 transactions to be rolled back. This invalidates all the database and cursor 257 handles opened in the replication environment. Once this occurs, an attempt to use 258 such a handle will 259 260 return <code class="literal">DB_REP_HANDLE_DEAD</code>. 261 The application will need to discard the handle and open a new one in order to 262 continue processing. 263 </p> 264 </div> 265 <div class="sect3" lang="en" xml:lang="en"> 266 <div class="titlepage"> 267 <div> 268 <div> 269 <h4 class="title"><a id="id1639136"></a>DB_REP_LOCKOUT</h4> 270 </div> 271 </div> 272 </div> 273 <p> 274 The operation was blocked by client/master synchronization. 275 </p> 276 </div> 277 <div class="sect3" lang="en" xml:lang="en"> 278 <div class="titlepage"> 279 <div> 280 <div> 281 <h4 class="title"><a id="id1638494"></a>DB_SECONDARY_BAD</h4> 282 </div> 283 </div> 284 </div> 285 <p> 286 A secondary index references a nonexistent primary key. 287 </p> 288 </div> 289 <div class="sect3" lang="en" xml:lang="en"> 290 <div class="titlepage"> 291 <div> 292 <div> 293 <h4 class="title"><a id="id1639208"></a>EINVAL</h4> 294 </div> 295 </div> 296 </div> 297 <p> 298 If cursor methods other than <a class="xref" href="dbcget.html" title="DBcursor->get()">DBcursor->get()</a> 299 or <a class="xref" href="dbcclose.html" title="DBcursor->close()">DBcursor->close()</a> were called; 300 or if an invalid flag value or parameter was specified. 301 </p> 302 </div> 303 </div> 304 <div class="sect2" lang="en" xml:lang="en"> 305 <div class="titlepage"> 306 <div> 307 <div> 308 <h3 class="title"><a id="id1639164"></a>Class</h3> 309 </div> 310 </div> 311 </div> 312 <p> 313 <a class="link" href="db.html" title="Chapter��2.�� The DB Handle">DB</a> 314 </p> 315 </div> 316 <div class="sect2" lang="en" xml:lang="en"> 317 <div class="titlepage"> 318 <div> 319 <div> 320 <h3 class="title"><a id="id1639019"></a>See Also</h3> 321 </div> 322 </div> 323 </div> 324 <p> 325 <a class="xref" href="db.html#dblist" title="Database and Related Methods">Database and Related Methods</a> 326 </p> 327 </div> 328 </div> 329 <div class="navfooter"> 330 <hr /> 331 <table width="100%" summary="Navigation footer"> 332 <tr> 333 <td width="40%" align="left"><a accesskey="p" href="dbget_type.html">Prev</a>��</td> 334 <td width="20%" align="center"> 335 <a accesskey="u" href="db.html">Up</a> 336 </td> 337 <td width="40%" align="right">��<a accesskey="n" href="dbkey_range.html">Next</a></td> 338 </tr> 339 <tr> 340 <td width="40%" align="left" valign="top">DB->get_type()��</td> 341 <td width="20%" align="center"> 342 <a accesskey="h" href="index.html">Home</a> 343 </td> 344 <td width="40%" align="right" valign="top">��DB->key_range()</td> 345 </tr> 346 </table> 347 </div> 348 </body> 349</html> 350