docs/api_reference/C/reptransport.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_ENV-&gt;rep_set_transport()</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="rep.html" title="Chapter 10.  Replication Methods" />
  11     <link rel="prev" href="repset_timeout.html" title="DB_ENV-&gt;rep_set_timeout()" />
  12     <link rel="next" href="repstart.html" title="DB_ENV-&gt;rep_start()" />
  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_ENV-&gt;rep_set_transport()</th>
  22         </tr>
  23         <tr>
  24           <td width="20%" align="left"><a accesskey="p" href="repset_timeout.html">Prev</a> </td>
  25           <th width="60%" align="center">Chapter 10.
  26                 Replication Methods
  27         </th>
  28           <td width="20%" align="right"> <a accesskey="n" href="repstart.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="reptransport"></a>DB_ENV-&gt;rep_set_transport()</h2>
  38           </div>
  39         </div>
  40       </div>
  41       <pre class="programlisting">#include &lt;db.h&gt;
  42
  43 int
  44 DB_ENV-&gt;rep_set_transport(DB_ENV *env, int envid,
  45     int (*send)(DB_ENV *dbenv,
  46     const DBT *control, const DBT *rec, const DB_LSN *lsnp,
  47     int envid, u_int32_t flags));  </pre>
  48       <p>
  49          The <code class="methodname">DB_ENV-&gt;rep_set_transport()</code> method initializes the communication
  50          infrastructure for a database environment participating in a replicated application.
  51     </p>
  52       <p>
  53          The <code class="methodname">DB_ENV-&gt;rep_set_transport()</code> method is not called by most
  54          replication applications.  It should only be called by Base API applications
  55          implementing their own network transport layer, explicitly holding
  56          replication group elections and handling replication messages outside
  57          of the Replication Manager framework.
  58     </p>
  59       <p>
  60          The <code class="methodname">DB_ENV-&gt;rep_set_transport()</code> method configures operations
  61          performed using the specified <a class="link" href="env.html" title="Chapter 5.  The DB_ENV Handle">DB_ENV</a>  handle,
  62          not all operations performed on the underlying database environment.
  63     </p>
  64       <p>
  65          The <code class="methodname">DB_ENV-&gt;rep_set_transport()</code> method may be called at any time
  66          during the life of the application.
  67     </p>
  68       <p>
  69          The <code class="methodname">DB_ENV-&gt;rep_set_transport()</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="note" style="margin-left: 0.5in; margin-right: 0.5in;">
  77         <h3 class="title">Note</h3>
  78         <p>
  79                     Berkeley DB is not re-entrant. The callback function
  80 for this method should not attempt to make
  81                     library calls (for example, to release locks or close open handles). Re-entering
  82                     Berkeley DB is not guaranteed to work correctly, and the results are undefined.
  83             </p>
  84       </div>
  85       <div class="sect2" lang="en" xml:lang="en">
  86         <div class="titlepage">
  87           <div>
  88             <div>
  89               <h3 class="title"><a id="idp62161184"></a>Parameters</h3>
  90             </div>
  91           </div>
  92         </div>
  93         <div class="sect3" lang="en" xml:lang="en">
  94           <div class="titlepage">
  95             <div>
  96               <div>
  97                 <h4 class="title"><a id="idp62161464"></a>envid</h4>
  98               </div>
  99             </div>
 100           </div>
 101           <p>
 102                           The <span class="bold"><strong>envid</strong></span> parameter is the local
 103                           environment's ID.  It must be a non-negative integer and uniquely identify
 104                           this Berkeley DB database environment (see
 105                           <a href="../../programmer_reference/rep_id.html" class="olink">Replication environment IDs</a>
 106                           for more information).
 107                      </p>
 108         </div>
 109         <div class="sect3" lang="en" xml:lang="en">
 110           <div class="titlepage">
 111             <div>
 112               <div>
 113                 <h4 class="title"><a id="idp62173296"></a>send</h4>
 114               </div>
 115             </div>
 116           </div>
 117           <p>
 118                           The <span class="bold"><strong>send</strong></span> callback function is used to
 119                           transmit data using the replication application's communication
 120                           infrastructure.  The parameters to <span class="bold"><strong>send</strong></span> are as follows:
 121                      </p>
 122           <div class="itemizedlist">
 123             <ul type="disc">
 124               <li>
 125                 <p>
 126                 <code class="literal">dbenv</code>
 127             </p>
 128                 <p>
 129                  The <span class="bold"><strong>dbenv</strong></span> parameter is the enclosing
 130                  database environment handle.
 131             </p>
 132               </li>
 133               <li>
 134                 <p>
 135                 <code class="literal">control</code>
 136             </p>
 137                 <p>
 138                  The <span class="bold"><strong>control</strong></span> parameter is the first of
 139                  the two data elements to be transmitted by the <span class="bold"><strong>send</strong></span> function.
 140             </p>
 141               </li>
 142               <li>
 143                 <p>
 144                 <code class="literal">rec</code>
 145             </p>
 146                 <p>
 147                  The <span class="bold"><strong>rec</strong></span> parameter is the second of
 148                  the two data elements to be transmitted by the <span class="bold"><strong>send</strong></span> function.
 149             </p>
 150               </li>
 151               <li>
 152                 <p>
 153                 <code class="literal">lsnp</code>
 154             </p>
 155                 <p>
 156                  If the type of message to be sent has an LSN associated with it, then
 157                  the <span class="bold"><strong>lsnp</strong></span> parameter contains the LSN
 158                  of the record being sent. This LSN can be used to determine that
 159                  certain records have been processed successfully by clients.
 160             </p>
 161               </li>
 162               <li>
 163                 <p>
 164                 <code class="literal">envid</code>
 165             </p>
 166                 <p>
 167                  The <span class="bold"><strong>envid</strong></span> parameter is a positive
 168                  integer identifier that specifies the replication environment to which
 169                  the message should be sent (see <a href="../../programmer_reference/rep_id.html" class="olink">Replication environment IDs</a> for more
 170                  information).
 171             </p>
 172                 <p><a id="transport_DB_EID_BROADCAST"></a>
 173                 The special identifier <code class="literal">DB_EID_BROADCAST</code> indicates that a message
 174                 should be broadcast to every environment in the replication group.  The application
 175                 may use a true broadcast protocol or may send the message in sequence to each
 176                 machine with which it is in communication.  In both cases, the sending site should
 177                 not be asked to process the message.
 178             </p>
 179                 <p>
 180                 The special identifier
 181                 <a href="../../programmer_reference/rep_id.html#rep_id.DB_EID_INVALID" class="olink">DB_EID_INVALID</a>
 182                 indicates an invalid environment ID.  This may be used to initialize
 183                 values that are subsequently checked for validity.
 184             </p>
 185               </li>
 186               <li>
 187                 <p>
 188                 <code class="literal">flags</code>
 189             </p>
 190                 <p>
 191                  The <span class="bold"><strong>flags</strong></span> parameter must be set to 0
 192                  or by bitwise inclusively <span class="bold"><strong>OR</strong></span>'ing
 193                  together one or more of the following values:
 194             </p>
 195                 <div class="itemizedlist">
 196                   <ul type="circle">
 197                     <li>
 198                       <p><a id="transport_DB_REP_ANYWHERE"></a>
 199                      <code class="literal">DB_REP_ANYWHERE</code>
 200             </p>
 201                       <p>
 202                  The message is a client request that can be satisfied by another
 203                  client as well as by the master.
 204             </p>
 205                     </li>
 206                     <li>
 207                       <p><a id="transport_DB_REP_NOBUFFER"></a>
 208                   <code class="literal">DB_REP_NOBUFFER</code>
 209             </p>
 210                       <p>
 211                  The record being sent should be transmitted immediately and not
 212                  buffered or delayed.
 213             </p>
 214                     </li>
 215                     <li>
 216                       <p><a id="transport_DB_REP_PERMANENT"></a>
 217                   <code class="literal">DB_REP_PERMANENT</code>
 218             </p>
 219                       <p>
 220                  The record being sent is critical for maintaining database integrity
 221                  (for example, the message includes a transaction commit).  The
 222                  application should take appropriate action to enforce the reliability
 223                  guarantees it has chosen, such as waiting for acknowledgement from one
 224                  or more clients.
 225             </p>
 226                     </li>
 227                     <li>
 228                       <p><a id="transport_DB_REP_REREQUEST"></a>
 229                   <code class="literal">DB_REP_REREQUEST</code>
 230             </p>
 231                       <p>
 232                  The message is a client request that has already been made and to
 233                  which no response was received.
 234             </p>
 235                     </li>
 236                   </ul>
 237                 </div>
 238               </li>
 239             </ul>
 240           </div>
 241           <p>
 242
 243                     It may sometimes be useful to pass application-specific data to the send
 244                     function; see <a href="../../programmer_reference/env_faq.html" class="olink">Environment FAQ</a>
 245                     for a discussion on how to do this.
 246
 247             </p>
 248           <p>
 249                     The <span class="bold"><strong>send</strong></span> function must return 0 on success and non-zero on failure.
 250                     If the send function fails, the message being sent is necessary to maintain database integrity, and
 251                     the local log is not configured for synchronous flushing, the local log will be flushed; otherwise,
 252                     any error from the <span class="bold"><strong>send</strong></span> function will be ignored.
 253             </p>
 254         </div>
 255       </div>
 256       <div class="sect2" lang="en" xml:lang="en">
 257         <div class="titlepage">
 258           <div>
 259             <div>
 260               <h3 class="title"><a id="idp62198640"></a>Errors</h3>
 261             </div>
 262           </div>
 263         </div>
 264         <p>
 265                          The <code class="methodname">DB_ENV-&gt;rep_set_transport()</code> <span>
 266             <span>
 267                  method may fail and return one of the following non-zero errors:
 268             </span>
 269
 270         </span>
 271                     </p>
 272         <div class="sect3" lang="en" xml:lang="en">
 273           <div class="titlepage">
 274             <div>
 275               <div>
 276                 <h4 class="title"><a id="idp62217728"></a>EINVAL</h4>
 277               </div>
 278             </div>
 279           </div>
 280           <p>
 281                 The method is called from a Replication Manager application; or an invalid flag value or
 282                 parameter was specified.
 283             </p>
 284         </div>
 285       </div>
 286       <div class="sect2" lang="en" xml:lang="en">
 287         <div class="titlepage">
 288           <div>
 289             <div>
 290               <h3 class="title"><a id="idp62128728"></a>Class</h3>
 291             </div>
 292           </div>
 293         </div>
 294         <p>
 295                 <a class="link" href="env.html" title="Chapter 5.  The DB_ENV Handle">DB_ENV</a>
 296             </p>
 297       </div>
 298       <div class="sect2" lang="en" xml:lang="en">
 299         <div class="titlepage">
 300           <div>
 301             <div>
 302               <h3 class="title"><a id="idp62196440"></a>See Also</h3>
 303             </div>
 304           </div>
 305         </div>
 306         <p>
 307                      <a class="xref" href="rep.html#replist" title="Replication and Related Methods">Replication and Related Methods</a>
 308                 </p>
 309       </div>
 310     </div>
 311     <div class="navfooter">
 312       <hr />
 313       <table width="100%" summary="Navigation footer">
 314         <tr>
 315           <td width="40%" align="left"><a accesskey="p" href="repset_timeout.html">Prev</a> </td>
 316           <td width="20%" align="center">
 317             <a accesskey="u" href="rep.html">Up</a>
 318           </td>
 319           <td width="40%" align="right"> <a accesskey="n" href="repstart.html">Next</a></td>
 320         </tr>
 321         <tr>
 322           <td width="40%" align="left" valign="top">DB_ENV-&gt;rep_set_timeout() </td>
 323           <td width="20%" align="center">
 324             <a accesskey="h" href="index.html">Home</a>
 325           </td>
 326           <td width="40%" align="right" valign="top"> DB_ENV-&gt;rep_start()</td>
 327         </tr>
 328       </table>
 329     </div>
 330   </body>
 331 </html>