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_foreign()</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="dbassociate.html" title="Db::associate()" /> 12 <link rel="next" href="dbclose.html" title="Db::close()" /> 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_foreign()</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="dbassociate.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="dbclose.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_foreign"></a>Db::associate_foreign()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db_cxx.h> 39 40int 41DB::associate_foreign(Db *secondary,, 42 int (*callback)(Db *secondary, 43 const Dbt *key, Dbt *data, const Dbt *foreignkey, int *changed), 44 u_int32_t flags); </pre> 45 <p> 46 The <code class="methodname">Db::associate_foreign()</code> function is used to declare one database a 47 foreign constraint for a secondary database. The 48 <a class="link" href="db.html" title="Chapter 2. The Db Handle">Db</a> handle that you call the 49 <code class="methodname">associate_foreign()</code> method from is the foreign 50 database. 51 </p> 52 <p> 53 After a foreign database has been "associated" with a secondary 54 database, all keys inserted into the secondary must exist in the 55 foreign database. Attempting to add a record with a foreign key 56 that does not exist in the foreign database will cause the put 57 method to fail and return <code class="literal">DB_FOREIGN_CONFLICT</code>. 58 </p> 59 <p> 60 Deletions in the foreign database affect the secondary in a manner 61 defined by the flags parameter. See 62 <a href="../../programmer_reference/am_foreign.html" class="olink">Foreign Indices</a> 63 in the <em class="citetitle">Berkeley DB Programmer's Reference Guide</em> for more information. 64 </p> 65 <p> 66 The <code class="methodname">Db::associate_foreign()</code> <span> 67 68 <span> 69 method either returns a non-zero error value or throws an 70 exception that encapsulates a non-zero error value on 71 failure, and returns 0 on success. 72 </span> 73 </span> 74 </p> 75 <div class="sect2" lang="en" xml:lang="en"> 76 <div class="titlepage"> 77 <div> 78 <div> 79 <h3 class="title"><a id="id1630620"></a>Parameters</h3> 80 </div> 81 </div> 82 </div> 83 <div class="sect3" lang="en" xml:lang="en"> 84 <div class="titlepage"> 85 <div> 86 <div> 87 <h4 class="title"><a id="id1630645"></a>callback</h4> 88 </div> 89 </div> 90 </div> 91 <p> 92 The <span class="bold"><strong>callback</strong></span> parameter is a callback 93 function that nullifies the foreign key portion of a data <a class="link" href="dbt.html" title="Chapter 4. The Dbt Handle">Dbt</a>. 94 </p> 95 <p> 96 The callback parameter must be NULL if either DB_FOREIGN_ABORT or DB_FOREIGN_CASCADE is set. 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 to be updated. 129 </p> 130 </li> 131 <li> 132 <p> 133 <code class="literal">foreignkey</code> 134 </p> 135 <p> 136 The <span class="bold"><strong>foreignkey</strong></span> parameter is a 137 <a class="link" href="dbt.html" title="Chapter 4. The Dbt Handle">Dbt</a> referencing the foreign 138 key which is being deleted. 139 </p> 140 </li> 141 <li> 142 <p> 143 <code class="literal">changed</code> 144 </p> 145 <p> 146 The <span class="bold"><strong>changed</strong></span> parameter is a 147 pointer to a boolean value, indicated whether <span class="bold"><strong>data</strong></span> 148 has changed. 149 </p> 150 </li> 151 </ul> 152 </div> 153 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> 154 <h3 class="title">Note</h3> 155 <p> 156 Berkeley DB is not re-entrant. Callback functions should not 157 attempt to make library calls (for example, to release locks or 158 close open handles). Re-entering Berkeley DB is not guaranteed 159 to work correctly, and the results are undefined. 160 </p> 161 </div> 162 </div> 163 <div class="sect3" lang="en" xml:lang="en"> 164 <div class="titlepage"> 165 <div> 166 <div> 167 <h4 class="title"><a id="id1631289"></a>flags</h4> 168 </div> 169 </div> 170 </div> 171 <p> 172 The <span class="bold"><strong>flags</strong></span> parameter must be set to 173 one of the following values: 174 </p> 175 <div class="itemizedlist"> 176 <ul type="disc"> 177 <li> 178 <p><a id="associate_foreign_DB_FOREIGN_ABORT"></a> 179 <code class="literal">DB_FOREIGN_ABORT</code> 180 </p> 181 <p> 182 Abort the deletion of a key in the foreign database and return DB_FOREIGN_CONFLICT 183 if that key exists in the secondary database. The deletion should be protected by 184 a transaction to ensure database integrity after the aborted delete. 185 </p> 186 </li> 187 <li> 188 <p><a id="associate_foreign_DB_FOREIGN_CASCADE"></a> 189 <code class="literal">DB_FOREIGN_CASCADE</code> 190 </p> 191 <p> 192 The deletion of a key in the foreign database will also delete that key from the 193 secondary database (and the corresponding entry in the secondary's primary database.) 194 </p> 195 </li> 196 <li> 197 <p><a id="associate_foreign_DB_FOREIGN_NULLIFY"></a> 198 <code class="literal">DB_FOREIGN_NULLIFY</code> 199 </p> 200 <p> 201 The deletion of a key in the foreign database will call the nullification function 202 passed to associate_foreign and update the secondary database with the changed data. 203 </p> 204 </li> 205 </ul> 206 </div> 207 </div> 208 <div class="sect3" lang="en" xml:lang="en"> 209 <div class="titlepage"> 210 <div> 211 <div> 212 <h4 class="title"><a id="id1630029"></a>secondary</h4> 213 </div> 214 </div> 215 </div> 216 <p> 217 The <span class="bold"><strong>secondary</strong></span> parameter should be an 218 open database handle of a database that contains a secondary index who's 219 keys also exist in the <span class="bold"><strong>foreign</strong></span> database. 220 </p> 221 </div> 222 </div> 223 <div class="sect2" lang="en" xml:lang="en"> 224 <div class="titlepage"> 225 <div> 226 <div> 227 <h3 class="title"><a id="id1630328"></a>Errors</h3> 228 </div> 229 </div> 230 </div> 231 <p> 232 The <code class="methodname">Db::associate_foreign()</code> <span> 233 234 <span> 235 method may fail and throw a <a class="link" href="dbexception.html" title="Chapter 6. The DbException Class">DbException</a> 236 exception, encapsulating one of the following non-zero errors, or return one 237 of the following non-zero errors: 238 </span> 239 </span> 240 </p> 241 <div class="sect3" lang="en" xml:lang="en"> 242 <div class="titlepage"> 243 <div> 244 <div> 245 <h4 class="title"><a id="id1630481"></a><span>DbRepHandleDeadException or</span> DB_REP_HANDLE_DEAD</h4> 246 </div> 247 </div> 248 </div> 249 <p> 250 When a client synchronizes with the master, it is possible for committed 251 transactions to be rolled back. This invalidates all the database and cursor 252 handles opened in the replication environment. Once this occurs, an attempt to use 253 such a handle will 254 <span> 255 throw a <a class="xref" href="dbrephandledead.html" title="DbRepHandleDeadException">DbRepHandleDeadException</a> (if 256 your application is configured to throw exceptions), or 257 </span> 258 return <code class="literal">DB_REP_HANDLE_DEAD</code>. 259 The application will need to discard the handle and open a new one in order to 260 continue processing. 261 </p> 262 </div> 263 <div class="sect3" lang="en" xml:lang="en"> 264 <div class="titlepage"> 265 <div> 266 <div> 267 <h4 class="title"><a id="id1629504"></a><span>DbDeadlockException or </span>DB_REP_LOCKOUT</h4> 268 </div> 269 </div> 270 </div> 271 <p> 272 The operation was blocked by client/master synchronization. 273 </p> 274 <p> 275 <a class="xref" href="dbdeadlock.html" title="DbDeadlockException">DbDeadlockException</a> is thrown if 276 your Berkeley DB API is configured to throw exceptions. 277 Otherwise, <code class="literal">DB_REP_LOCKOUT</code> is returned. 278 </p> 279 </div> 280 <div class="sect3" lang="en" xml:lang="en"> 281 <div class="titlepage"> 282 <div> 283 <div> 284 <h4 class="title"><a id="id1630158"></a>EINVAL</h4> 285 </div> 286 </div> 287 </div> 288 <p> 289 If the foreign database handle is a secondary index; the foreign 290 database handle has been configured to allow duplicates; the foreign 291 database handle is a renumbering recno database; callback is 292 configured and DB_FOREIGN_NULLIFY is not; DB_FOREIGN_NULLIFY is 293 configured and callback is not. 294 </p> 295 </div> 296 </div> 297 <div class="sect2" lang="en" xml:lang="en"> 298 <div class="titlepage"> 299 <div> 300 <div> 301 <h3 class="title"><a id="id1631196"></a>Class</h3> 302 </div> 303 </div> 304 </div> 305 <p> 306 <a class="link" href="db.html" title="Chapter 2. The Db Handle">Db</a> 307 </p> 308 </div> 309 <div class="sect2" lang="en" xml:lang="en"> 310 <div class="titlepage"> 311 <div> 312 <div> 313 <h3 class="title"><a id="id1630791"></a>See Also</h3> 314 </div> 315 </div> 316 </div> 317 <p> 318 <a class="xref" href="db.html#dblist" title="Database and Related Methods">Database and Related Methods</a> 319 </p> 320 </div> 321 </div> 322 <div class="navfooter"> 323 <hr /> 324 <table width="100%" summary="Navigation footer"> 325 <tr> 326 <td width="40%" align="left"><a accesskey="p" href="dbassociate.html">Prev</a> </td> 327 <td width="20%" align="center"> 328 <a accesskey="u" href="db.html">Up</a> 329 </td> 330 <td width="40%" align="right"> <a accesskey="n" href="dbclose.html">Next</a></td> 331 </tr> 332 <tr> 333 <td width="40%" align="left" valign="top">Db::associate() </td> 334 <td width="20%" align="center"> 335 <a accesskey="h" href="index.html">Home</a> 336 </td> 337 <td width="40%" align="right" valign="top"> Db::close()</td> 338 </tr> 339 </table> 340 </div> 341 </body> 342</html> 343