docs/api_reference/C/dbassociate_foreign.html

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