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