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->rep_process_message()</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="repget_timeout.html" title="DB_ENV->rep_get_timeout()" /> 12 <link rel="next" href="repclockskew.html" title="DB_ENV->rep_set_clockskew()" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">DB_ENV->rep_process_message()</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="repget_timeout.html">Prev</a>��</td> 22 <th width="60%" align="center">Chapter��10.�� 23 Replication Methods 24 </th> 25 <td width="20%" align="right">��<a accesskey="n" href="repclockskew.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="repmessage"></a>DB_ENV->rep_process_message()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db.h> 39 40int 41DB_ENV->rep_process_message(DB_ENV *env, 42 DBT *control, DBT *rec, int envid, DB_LSN *ret_lsnp) </pre> 43 <p> 44 The <code class="methodname">DB_ENV->rep_process_message()</code> method processes an incoming 45 replication message sent by a member of the replication group to the 46 local database environment. 47 </p> 48 <p> 49 The <code class="methodname">DB_ENV->rep_process_message()</code> method is not called by most 50 replication applications. It should only be called by Base API applications 51 implementing their own network transport layer, explicitly holding 52 replication group elections and handling replication messages outside 53 of the Replication Manager framework. 54 </p> 55 <p> 56 For implementation reasons, all incoming replication messages must be 57 processed using the same <a class="link" href="env.html" title="Chapter��5.�� The DB_ENV Handle">DB_ENV</a> handle. It is not 58 required that a single thread of control process all messages, only 59 that all threads of control processing messages use the same handle. 60 </p> 61 <p> 62 Before calling this method, the enclosing database environment must 63 already have been opened by calling the 64 <a class="xref" href="envopen.html" title="DB_ENV->open()">DB_ENV->open()</a> method and must 65 already have been configured to send replication messages by 66 calling the <a class="xref" href="reptransport.html" title="DB_ENV->rep_set_transport()">DB_ENV->rep_set_transport()</a> 67 method. 68 </p> 69 <p> 70 The <code class="methodname">DB_ENV->rep_process_message()</code> method has additional return 71 values: 72 </p> 73 <div class="itemizedlist"> 74 <ul type="disc"> 75 <li> 76 <p><a id="repmsg_DB_REP_DUPMASTER"></a> 77 <span class="bold"><strong>DB_REP_DUPMASTER</strong></span> 78 </p> 79 <p> 80 The <code class="methodname">DB_ENV->rep_process_message()</code> method will return 81 <code class="literal">DB_REP_DUPMASTER</code> if the replication group has more than one 82 master. The application should reconfigure itself as a client by calling the 83 <a class="xref" href="repstart.html" title="DB_ENV->rep_start()">DB_ENV->rep_start()</a> method, and then call for an 84 election by calling <a class="xref" href="repelect.html" title="DB_ENV->rep_elect()">DB_ENV->rep_elect()</a>. 85 </p> 86 </li> 87 <li> 88 <p><a id="repmsg_DB_REP_HOLDELECTION"></a> 89 <span class="bold"><strong>DB_REP_HOLDELECTION</strong></span> 90 </p> 91 <p> 92 The <code class="methodname">DB_ENV->rep_process_message()</code> method will return 93 <code class="literal">DB_REP_HOLDELECTION</code> if an election is needed. The application 94 should call for an election by calling 95 <a class="xref" href="repelect.html" title="DB_ENV->rep_elect()">DB_ENV->rep_elect()</a>. 96 </p> 97 </li> 98 <li> 99 <p><a id="repmsg_DB_REP_IGNORE"></a> 100 <span class="bold"><strong>DB_REP_IGNORE</strong></span> 101 </p> 102 <p> 103 The <code class="methodname">DB_ENV->rep_process_message()</code> method will return 104 <code class="literal">DB_REP_IGNORE</code> if this message cannot be processed. This is an 105 indication that this message is irrelevant to the current replication state (for 106 example, an old message from a previous generation arrives and is processed late). 107 </p> 108 </li> 109 <li> 110 <p><a id="repmsg_DB_REP_ISPERM"></a> 111 <span class="bold"><strong>DB_REP_ISPERM</strong></span> 112 </p> 113 <p> 114 The <code class="methodname">DB_ENV->rep_process_message()</code> method will return 115 <code class="literal">DB_REP_ISPERM</code> if processing this message results in the 116 processing of records that are permanent. The maximum LSN of the permanent records 117 stored is returned. 118 </p> 119 </li> 120 <li> 121 <p><a id="repmsg_DB_REP_JOIN_FAILURE"></a> 122 <span class="bold"><strong>DB_REP_JOIN_FAILURE</strong></span> 123 </p> 124 <p> 125 The <code class="methodname">DB_ENV->rep_process_message()</code> method will return 126 <code class="literal">DB_REP_JOIN_FAILURE</code> if a new master has been chosen but the 127 client is unable to synchronize with the new master (possibly because the client 128 has been configured with the 129 <a class="link" href="repconfig.html#config_DB_REP_CONF_NOAUTOINIT">DB_REP_CONF_NOAUTOINIT</a> 130 flag to turn off automatic internal initialization). 131 </p> 132 </li> 133 <li> 134 <p><a id="repmsg_DB_REP_NEWSITE"></a> 135 <span class="bold"><strong>DB_REP_NEWSITE</strong></span> 136 </p> 137 <p> 138 The <code class="methodname">DB_ENV->rep_process_message()</code> method will return 139 <code class="literal">DB_REP_NEWSITE</code> if the system received contact information from a 140 new environment. The <span class="bold"><strong>rec</strong></span> parameter contains the 141 opaque data specified in the <span class="bold"><strong>cdata</strong></span> parameter to 142 the <a class="xref" href="repstart.html" title="DB_ENV->rep_start()">DB_ENV->rep_start()</a>. The application should 143 take whatever action is needed to establish a communication channel with this new 144 environment. 145 </p> 146 </li> 147 <li> 148 <p><a id="repmsg_DB_REP_NOTPERM"></a> 149 <span class="bold"><strong>DB_REP_NOTPERM</strong></span> 150 </p> 151 <p> 152 The <code class="methodname">DB_ENV->rep_process_message()</code> method will return 153 <code class="literal">DB_REP_NOTPERM</code> if a message carrying a 154 <a class="link" href="reptransport.html#transport_DB_REP_PERMANENT">DB_REP_PERMANENT</a> 155 flag was processed successfully, but was not written to disk. The LSN of this 156 record is returned. The application should take whatever action is deemed 157 necessary to retain its recoverability characteristics. 158 </p> 159 </li> 160 </ul> 161 </div> 162 <p> 163 Unless otherwise specified, the <code class="methodname">DB_ENV->rep_process_message()</code> 164 <span> 165 <span> 166 method returns a non-zero error value on failure and 0 on success. 167 </span> 168 169 </span> 170 </p> 171 <div class="sect2" lang="en" xml:lang="en"> 172 <div class="titlepage"> 173 <div> 174 <div> 175 <h3 class="title"><a id="id1697935"></a>Parameters</h3> 176 </div> 177 </div> 178 </div> 179 <div class="sect3" lang="en" xml:lang="en"> 180 <div class="titlepage"> 181 <div> 182 <div> 183 <h4 class="title"><a id="id1696933"></a>control</h4> 184 </div> 185 </div> 186 </div> 187 <p> 188 The <span class="bold"><strong>control</strong></span> parameter should 189 reference a copy of the <span class="bold"><strong>control</strong></span> 190 parameter specified by Berkeley DB on the sending environment. 191See the <a class="xref" href="reptransport.html" title="DB_ENV->rep_set_transport()">DB_ENV->rep_set_transport()</a> method for more information. 192 </p> 193 </div> 194 <div class="sect3" lang="en" xml:lang="en"> 195 <div class="titlepage"> 196 <div> 197 <div> 198 <h4 class="title"><a id="id1697970"></a>envid</h4> 199 </div> 200 </div> 201 </div> 202 <p> 203 The <span class="bold"><strong>envid</strong></span> parameter should contain 204 the local identifier that corresponds to the environment that sent the 205 message to be processed (see <a href="../../programmer_reference/rep_id.html" class="olink">Replication environment IDs</a> for more 206 information). 207 </p> 208 </div> 209 <div class="sect3" lang="en" xml:lang="en"> 210 <div class="titlepage"> 211 <div> 212 <div> 213 <h4 class="title"><a id="id1697724"></a>rec</h4> 214 </div> 215 </div> 216 </div> 217 <p> 218 The <span class="bold"><strong>rec</strong></span> parameter should reference a 219 copy of the <span class="bold"><strong>rec</strong></span> parameter specified 220 by Berkeley DB on the sending environment. 221See the <a class="xref" href="reptransport.html" title="DB_ENV->rep_set_transport()">DB_ENV->rep_set_transport()</a> method for more information. 222 </p> 223 </div> 224 <div class="sect3" lang="en" xml:lang="en"> 225 <div class="titlepage"> 226 <div> 227 <div> 228 <h4 class="title"><a id="id1697858"></a>ret_lsnp</h4> 229 </div> 230 </div> 231 </div> 232 <p> 233 If <code class="methodname">DB_ENV->rep_process_message()</code> method returns 234 <code class="literal">DB_REP_NOTPERM</code> then the 235 <span class="bold"><strong>ret_lsnp</strong></span> parameter will contain the log sequence 236 number of this permanent log message that could not be written to disk. If 237 <code class="methodname">DB_ENV->rep_process_message()</code> method returns 238 <code class="literal">DB_REP_ISPERM</code> then the 239 <span class="bold"><strong>ret_lsnp</strong></span> parameter will contain largest log 240 sequence number of the permanent records that are now written to disk as a 241 result of processing this message. In all other cases the value of 242 <span class="bold"><strong>ret_lsnp</strong></span> is undefined. 243 244 </p> 245 </div> 246 </div> 247 <div class="sect2" lang="en" xml:lang="en"> 248 <div class="titlepage"> 249 <div> 250 <div> 251 <h3 class="title"><a id="id1697846"></a>Errors</h3> 252 </div> 253 </div> 254 </div> 255 <p> 256 The <code class="methodname">DB_ENV->rep_process_message()</code> 257 <span> 258 <span> 259 method may fail and return one of the following non-zero errors: 260 </span> 261 262 </span> 263 </p> 264 <div class="sect3" lang="en" xml:lang="en"> 265 <div class="titlepage"> 266 <div> 267 <div> 268 <h4 class="title"><a id="id1698053"></a>EINVAL</h4> 269 </div> 270 </div> 271 </div> 272 <p> 273 If the database environment was not already configured to 274 communicate with a replication group by a call to 275 <a class="xref" href="reptransport.html" title="DB_ENV->rep_set_transport()">DB_ENV->rep_set_transport()</a>; 276 if the database environment was not already opened; 277 if this method is called from a Replication Manager 278 application; or if an invalid flag value or parameter 279 was specified. 280 </p> 281 </div> 282 </div> 283 <div class="sect2" lang="en" xml:lang="en"> 284 <div class="titlepage"> 285 <div> 286 <div> 287 <h3 class="title"><a id="id1698178"></a>Class</h3> 288 </div> 289 </div> 290 </div> 291 <p> 292 <a class="link" href="env.html" title="Chapter��5.�� The DB_ENV Handle">DB_ENV</a> 293 </p> 294 </div> 295 <div class="sect2" lang="en" xml:lang="en"> 296 <div class="titlepage"> 297 <div> 298 <div> 299 <h3 class="title"><a id="id1697623"></a>See Also</h3> 300 </div> 301 </div> 302 </div> 303 <p> 304 <a class="xref" href="rep.html#replist" title="Replication and Related Methods">Replication and Related Methods</a> 305 </p> 306 </div> 307 </div> 308 <div class="navfooter"> 309 <hr /> 310 <table width="100%" summary="Navigation footer"> 311 <tr> 312 <td width="40%" align="left"><a accesskey="p" href="repget_timeout.html">Prev</a>��</td> 313 <td width="20%" align="center"> 314 <a accesskey="u" href="rep.html">Up</a> 315 </td> 316 <td width="40%" align="right">��<a accesskey="n" href="repclockskew.html">Next</a></td> 317 </tr> 318 <tr> 319 <td width="40%" align="left" valign="top">DB_ENV->rep_get_timeout()��</td> 320 <td width="20%" align="center"> 321 <a accesskey="h" href="index.html">Home</a> 322 </td> 323 <td width="40%" align="right" valign="top">��DB_ENV->rep_set_clockskew()</td> 324 </tr> 325 </table> 326 </div> 327 </body> 328</html> 329