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>Building the communications infrastructure</title> 7 <link rel="stylesheet" href="gettingStarted.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 Programmer's Reference Guide" /> 10 <link rel="up" href="rep.html" title="Chapter��12.�� Berkeley DB Replication" /> 11 <link rel="prev" href="rep_base_meth.html" title="Base API Methods" /> 12 <link rel="next" href="rep_newsite.html" title="Connecting to a new site" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Building the communications infrastructure</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="rep_base_meth.html">Prev</a>��</td> 22 <th width="60%" align="center">Chapter��12.�� 23 Berkeley DB Replication 24 </th> 25 <td width="20%" align="right">��<a accesskey="n" href="rep_newsite.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="rep_comm"></a>Building the communications infrastructure</h2> 35 </div> 36 </div> 37 </div> 38 <p>Replication Manager provides a built-in communications 39infrastructure.</p> 40 <p>Base API applications must provide 41their own communications infrastructure, which is typically written with one 42or more threads of control looping on one or more communication 43channels, receiving and sending messages. These threads accept messages 44from remote environments for the local database environment, and accept 45messages from the local environment for remote environments. Messages 46from remote environments are passed to the local database environment 47using the <a href="../api_reference/C/repmessage.html" class="olink">DB_ENV->rep_process_message()</a> method. Messages from the local environment are 48passed to the application for transmission using the callback function 49specified to the <a href="../api_reference/C/reptransport.html" class="olink">DB_ENV->rep_set_transport()</a> method.</p> 50 <p>Processes establish communication channels by calling the 51<a href="../api_reference/C/reptransport.html" class="olink">DB_ENV->rep_set_transport()</a> method, regardless of whether they are running in 52client or server environments. This method specifies the <span class="bold"><strong>send</strong></span> 53function, a callback function used by Berkeley DB for sending messages to 54other database environments in the replication group. The <span class="bold"><strong>send</strong></span> 55function takes an environment ID and two opaque data objects. It is the 56responsibility of the <span class="bold"><strong>send</strong></span> function to transmit the information 57in the two data objects to the database environment corresponding to the 58ID, with the receiving application then calling the <a href="../api_reference/C/repmessage.html" class="olink">DB_ENV->rep_process_message()</a> method 59to process the message.</p> 60 <p>The details of the transport mechanism are left entirely to the 61application; the only requirement is that the data buffer and size of 62each of the control and rec <a href="../api_reference/C/dbt.html" class="olink">DBT</a>s passed to the <span class="bold"><strong>send</strong></span> 63function on the sending site be faithfully copied and delivered to the 64receiving site by means of a call to <a href="../api_reference/C/repmessage.html" class="olink">DB_ENV->rep_process_message()</a> with 65corresponding arguments. Messages that are broadcast (whether by 66broadcast media or when directed by setting the 67<a href="../api_reference/C/reptransport.html" class="olink">DB_ENV->rep_set_transport()</a> method's envid parameter DB_EID_BROADCAST), should 68not be processed by the message sender. In all cases, the application's 69transport media or software must ensure that <a href="../api_reference/C/repmessage.html" class="olink">DB_ENV->rep_process_message()</a> is 70never called with a message intended for a different database 71environment or a broadcast message sent from the same environment on 72which <a href="../api_reference/C/repmessage.html" class="olink">DB_ENV->rep_process_message()</a> will be called. 73The <a href="../api_reference/C/repmessage.html" class="olink">DB_ENV->rep_process_message()</a> method is 74free-threaded; it is safe to deliver any number of messages 75simultaneously, and from any arbitrary thread or process in the Berkeley DB 76environment.</p> 77 <p>There are a number of informational returns from the 78<a href="../api_reference/C/repmessage.html" class="olink">DB_ENV->rep_process_message()</a> method:</p> 79 <div class="variablelist"> 80 <dl> 81 <dt> 82 <span class="term"> 83 <a href="../api_reference/C/repmessage.html#repmsg_DB_REP_DUPMASTER" class="olink">DB_REP_DUPMASTER</a> 84 </span> 85 </dt> 86 <dd> 87 <p> 88 When <a href="../api_reference/C/repmessage.html" class="olink">DB_ENV->rep_process_message()</a> returns <a href="../api_reference/C/repmessage.html#repmsg_DB_REP_DUPMASTER" class="olink">DB_REP_DUPMASTER</a>, it means that 89 another database environment in the replication group also 90 believes itself to be the master. The application should 91 complete all active transactions, close all open database 92 handles, reconfigure itself as a client using the 93 <a href="../api_reference/C/repstart.html" class="olink">DB_ENV->rep_start()</a> method, and then call for an election by calling 94 the <a href="../api_reference/C/repelect.html" class="olink">DB_ENV->rep_elect()</a> method. 95 </p> 96 </dd> 97 <dt> 98 <span class="term"> 99 <a href="../api_reference/C/repmessage.html#repmsg_DB_REP_HOLDELECTION" class="olink">DB_REP_HOLDELECTION</a> 100 </span> 101 </dt> 102 <dd> 103 <p> 104 When <a href="../api_reference/C/repmessage.html" class="olink">DB_ENV->rep_process_message()</a> returns <a href="../api_reference/C/repmessage.html#repmsg_DB_REP_HOLDELECTION" class="olink">DB_REP_HOLDELECTION</a>, it means that 105 another database environment in the replication group has 106 called for an election. The application should call the 107 <a href="../api_reference/C/repelect.html" class="olink">DB_ENV->rep_elect()</a> method. 108 </p> 109 </dd> 110 <dt> 111 <span class="term"> 112 <a href="../api_reference/C/repmessage.html#repmsg_DB_REP_IGNORE" class="olink">DB_REP_IGNORE</a> 113 </span> 114 </dt> 115 <dd> 116 <p> 117 When <a href="../api_reference/C/repmessage.html" class="olink">DB_ENV->rep_process_message()</a> returns <a href="../api_reference/C/repmessage.html#repmsg_DB_REP_IGNORE" class="olink">DB_REP_IGNORE</a>, it means that this 118 message cannot be processed. This is normally an indication 119 that this message is irrelevant to the current replication 120 state, such as a message from an old generation that arrived 121 late. 122 </p> 123 </dd> 124 <dt> 125 <span class="term"> 126 <a href="../api_reference/C/repmessage.html#repmsg_DB_REP_ISPERM" class="olink">DB_REP_ISPERM</a> 127 </span> 128 </dt> 129 <dd> 130 <p> 131 When <a href="../api_reference/C/repmessage.html" class="olink">DB_ENV->rep_process_message()</a> returns <a href="../api_reference/C/repmessage.html#repmsg_DB_REP_ISPERM" class="olink">DB_REP_ISPERM</a>, it means a permanent 132 record, perhaps a message previously returned as 133 <a href="../api_reference/C/repmessage.html#repmsg_DB_REP_NOTPERM" class="olink">DB_REP_NOTPERM</a>, was successfully written to disk. This 134 record may have filled a gap in the log record that allowed 135 additional records to be written. The <span class="bold"><strong>ret_lsnp</strong></span> contains the maximum LSN of 136 the permanent records written. 137 </p> 138 </dd> 139 <dt> 140 <span class="term"> 141 <a href="../api_reference/C/repmessage.html#repmsg_DB_REP_NEWSITE" class="olink">DB_REP_NEWSITE</a> 142 </span> 143 </dt> 144 <dd> 145 <p> 146 When <a href="../api_reference/C/repmessage.html" class="olink">DB_ENV->rep_process_message()</a> returns <a href="../api_reference/C/repmessage.html#repmsg_DB_REP_NEWSITE" class="olink">DB_REP_NEWSITE</a>, it means that a 147 message from a previously unknown member of the replication 148 group has been received. The application should reconfigure 149 itself as necessary so it is able to send messages to this 150 site. 151 </p> 152 </dd> 153 <dt> 154 <span class="term"> 155 <a href="../api_reference/C/repmessage.html#repmsg_DB_REP_NOTPERM" class="olink">DB_REP_NOTPERM</a> 156 </span> 157 </dt> 158 <dd> 159 <p> 160 When <a href="../api_reference/C/repmessage.html" class="olink">DB_ENV->rep_process_message()</a> returns <a href="../api_reference/C/repmessage.html#repmsg_DB_REP_NOTPERM" class="olink">DB_REP_NOTPERM</a>, it means a message 161 marked as <a href="../api_reference/C/reptransport.html#transport_DB_REP_PERMANENT" class="olink">DB_REP_PERMANENT</a> was processed successfully but was not 162 written to disk. This is normally an indication that one or 163 more messages, which should have arrived before this message, 164 have not yet arrived. This operation will be written to disk 165 when the missing messages arrive. The <span class="bold"><strong>ret_lsnp</strong></span> argument will contain the 166 LSN of this record. The application should take whatever 167 action is deemed necessary to retain its recoverability 168 characteristics. 169 </p> 170 </dd> 171 </dl> 172 </div> 173 </div> 174 <div class="navfooter"> 175 <hr /> 176 <table width="100%" summary="Navigation footer"> 177 <tr> 178 <td width="40%" align="left"><a accesskey="p" href="rep_base_meth.html">Prev</a>��</td> 179 <td width="20%" align="center"> 180 <a accesskey="u" href="rep.html">Up</a> 181 </td> 182 <td width="40%" align="right">��<a accesskey="n" href="rep_newsite.html">Next</a></td> 183 </tr> 184 <tr> 185 <td width="40%" align="left" valign="top">Base API Methods��</td> 186 <td width="20%" align="center"> 187 <a accesskey="h" href="index.html">Home</a> 188 </td> 189 <td width="40%" align="right" valign="top">��Connecting to a new site</td> 190 </tr> 191 </table> 192 </div> 193 </body> 194</html> 195