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_set_config()</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="repclockskew.html" title="DbEnv::rep_set_clockskew()" /> 12 <link rel="next" href="repset_limit.html" title="DbEnv::rep_set_limit()" /> 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_set_config()</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="repclockskew.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="repset_limit.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="repconfig"></a>DbEnv::rep_set_config()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db_cxx.h> 39 40int 41DbEnv::rep_set_config(u_int32_t which, int onoff); </pre> 42 <p> 43 The <code class="methodname">DbEnv::rep_set_config()</code> method configures the Berkeley DB 44 replication subsystem. 45 </p> 46 <p> 47 The database environment's replication subsystem may also be 48 configured using the environment's <a href="../../programmer_reference/env_db_config.html#env_db_config.DB_CONFIG" class="olink">DB_CONFIG</a> file. The 49 syntax of the entry in that file is a single line with the string 50 "rep_set_config", one or more whitespace characters, and the method 51 <span class="bold"><strong>which</strong></span> parameter as a string; for 52 example, "rep_set_config DB_REP_CONF_NOWAIT". Because the <a href="../../programmer_reference/env_db_config.html#env_db_config.DB_CONFIG" class="olink">DB_CONFIG</a> file is 53 read when the database environment is opened, it will silently 54 overrule configuration done before that time. 55 </p> 56 <p> 57 The <code class="methodname">DbEnv::rep_set_config()</code> method configures a database 58 environment, not only operations performed using the specified 59 <a class="link" href="env.html" title="Chapter 5. The DbEnv Handle">DbEnv</a> handle. 60 </p> 61 <p> 62 The <code class="methodname">DbEnv::rep_set_config()</code> method may not be 63 called to set in-memory replication after the environment is 64 opened using the 65 <a class="xref" href="envopen.html" title="DbEnv::open()">DbEnv::open()</a> method. 66 This method may also not be called to set master leases after the 67 <a class="xref" href="repstart.html" title="DbEnv::rep_start()">DbEnv::rep_start()</a> or 68 <a class="xref" href="repmgrstart.html" title="DbEnv::repmgr_start()">DbEnv::repmgr_start()</a> methods 69 are called. For all other <span class="bold"><strong>which</strong></span> 70 parameters, this method may be called at any time during the life 71 of the application. 72 </p> 73 <p> 74 The <code class="methodname">DbEnv::rep_set_config()</code> <span> 75 76 <span> 77 method either returns a non-zero error value or throws an 78 exception that encapsulates a non-zero error value on 79 failure, and returns 0 on success. 80 </span> 81 </span> 82 </p> 83 <div class="sect2" lang="en" xml:lang="en"> 84 <div class="titlepage"> 85 <div> 86 <div> 87 <h3 class="title"><a id="id1702959"></a>Parameters</h3> 88 </div> 89 </div> 90 </div> 91 <div class="sect3" lang="en" xml:lang="en"> 92 <div class="titlepage"> 93 <div> 94 <div> 95 <h4 class="title"><a id="id1702812"></a>onoff</h4> 96 </div> 97 </div> 98 </div> 99 <p> 100 If the <span class="bold"><strong>onoff</strong></span> parameter is zero, the 101 configuration flag is turned off. 102Otherwise, it is turned on. All configuration flags are turned off by default. 103 </p> 104 </div> 105 <div class="sect3" lang="en" xml:lang="en"> 106 <div class="titlepage"> 107 <div> 108 <div> 109 <h4 class="title"><a id="id1703132"></a>which</h4> 110 </div> 111 </div> 112 </div> 113 <p> 114 The <span class="bold"><strong>which</strong></span> parameter must be set to 115 one of the following values: 116 </p> 117 <div class="itemizedlist"> 118 <ul type="disc"> 119 <li> 120 <p><a id="config_DB_REP_CONF_BULK"></a> 121 <code class="literal">DB_REP_CONF_BULK</code> 122 </p> 123 <p> 124 The replication master sends groups of records to the clients in a 125 single network transfer. 126 </p> 127 </li> 128 <li> 129 <p><a id="config_DB_REP_CONF_DELAYCLIENT"></a> 130 <code class="literal">DB_REP_CONF_DELAYCLIENT</code> 131 </p> 132 <p> 133 The client should delay synchronizing to a newly declared master. Clients configured in this way will remain 134 unsynchronized until the application calls the 135 <a class="xref" href="repsync.html" title="DbEnv::rep_sync()">DbEnv::rep_sync()</a> method. 136 </p> 137 </li> 138 <li> 139 <p><a id="config_DB_REP_CONF_INMEM"></a> 140 <code class="literal">DB_REP_CONF_INMEM</code> 141 </p> 142 <p> 143 Store internal replication information in memory only. 144 </p> 145 <p> 146 By default, replication creates files in the environment home directory 147 to preserve some internal information. If this configuration flag is turned 148 on, replication only stores this internal information in-memory and cannot 149 keep persistent state across a site crash or reboot. This results in the 150 following limitations: 151 </p> 152 <div class="itemizedlist"> 153 <ul type="circle"> 154 <li> 155 <p> 156 A master site should not reappoint itself master 157 immediately after crashing or rebooting because the application would incur a 158 slightly higher risk of client crashes. The former master site should rejoin 159 the replication group as a client. The application should either hold an 160 election or appoint a different site to be the next master. 161 </p> 162 </li> 163 <li> 164 <p> 165 An application has a slightly higher risk that elections will fail or be 166 unable to complete. Calling additional elections should eventually yield a 167 winner. 168 </p> 169 </li> 170 <li> 171 <p> 172 An application has a slight risk that the wrong site may win an election, 173 resulting in the loss of some data. This is consistent with the general loss 174 of data durability when running in-memory. 175 </p> 176 </li> 177 </ul> 178 </div> 179 <p> 180 This configuration flag can only be turned on before the environment 181 is opened with the <a class="xref" href="envopen.html" title="DbEnv::open()">DbEnv::open()</a> 182 method. Its value cannot be changed while the environment is open. 183 </p> 184 </li> 185 <li> 186 <p> 187 <code class="literal">DB_REP_CONF_LEASE</code> 188 </p> 189 <p> 190 Master leases will be used for this site. 191 </p> 192 <p> 193 Configuring this option may result in 194 <code class="literal">DB_REP_LEASE_EXPIRED</code> error returns 195 from the <a class="xref" href="dbget.html" title="Db::get()">Db::get()</a> and 196 <a class="xref" href="dbcget.html" title="Dbc::get()">Dbc::get()</a> methods 197 when attempting to read entries from a database after the site's 198 master lease has expired. 199 </p> 200 <p> 201 This configuration flag may not be set after the 202 <a class="xref" href="repmgrstart.html" title="DbEnv::repmgr_start()">DbEnv::repmgr_start()</a> method or the 203 <a class="xref" href="repstart.html" title="DbEnv::rep_start()">DbEnv::rep_start()</a> 204 method is called. 205 </p> 206 </li> 207 <li> 208 <p><a id="config_DB_REP_CONF_NOAUTOINIT"></a> 209 <code class="literal">DB_REP_CONF_NOAUTOINIT</code> 210 </p> 211 <p> 212 The replication master will not automatically re-initialize outdated 213 clients. 214 </p> 215 </li> 216 <li> 217 <p><a id="config_DB_REP_CONF_NOWAIT"></a> 218 <code class="literal">DB_REP_CONF_NOWAIT</code> 219 </p> 220 <p> 221 Berkeley DB method calls that would normally block while clients are 222 in recovery will return errors immediately. 223 </p> 224 </li> 225 <li> 226 <p><a id="config_DB_REPMGR_CONF_2SITE_STRICT"></a> 227 <code class="literal">DB_REPMGR_CONF_2SITE_STRICT</code> 228 </p> 229 <p> 230 Replication Manager observes the strict "majority" rule in managing 231 elections, even in a group with only 2 sites. This means the client 232 in a 2-site group will be unable to take over as master if the 233 original master fails or becomes disconnected. (See the <a href="../../programmer_reference/rep_elect.html" class="olink">Elections</a> section in the <em class="citetitle">Berkeley DB Programmer's Reference Guide</em> for more information.) Both sites in the 234 replication group should have the same value for this configuration flag. 235 </p> 236 </li> 237 </ul> 238 </div> 239 </div> 240 </div> 241 <div class="sect2" lang="en" xml:lang="en"> 242 <div class="titlepage"> 243 <div> 244 <div> 245 <h3 class="title"><a id="id1703201"></a>Errors</h3> 246 </div> 247 </div> 248 </div> 249 <p> 250 The <code class="methodname">DbEnv::rep_set_config()</code> <span> 251 252 <span> 253 method may fail and throw a <a class="link" href="dbexception.html" title="Chapter 6. The DbException Class">DbException</a> 254 exception, encapsulating one of the following non-zero errors, or return one 255 of the following non-zero errors: 256 </span> 257 </span> 258 </p> 259 <div class="sect3" lang="en" xml:lang="en"> 260 <div class="titlepage"> 261 <div> 262 <div> 263 <h4 class="title"><a id="id1703489"></a>EINVAL</h4> 264 </div> 265 </div> 266 </div> 267 <p> 268 If setting in-memory replication after the database environment is already 269 opened; if setting master leases after replication is started; if setting 270 the 2-site strict majority rule for a Base API application; 271 or if an invalid flag value or parameter was specified. 272 </p> 273 </div> 274 </div> 275 <div class="sect2" lang="en" xml:lang="en"> 276 <div class="titlepage"> 277 <div> 278 <div> 279 <h3 class="title"><a id="id1703437"></a>Class</h3> 280 </div> 281 </div> 282 </div> 283 <p> 284 <a class="link" href="env.html" title="Chapter 5. The DbEnv Handle">DbEnv</a> 285 </p> 286 </div> 287 <div class="sect2" lang="en" xml:lang="en"> 288 <div class="titlepage"> 289 <div> 290 <div> 291 <h3 class="title"><a id="id1703033"></a>See Also</h3> 292 </div> 293 </div> 294 </div> 295 <p> 296 <a class="xref" href="rep.html#replist" title="Replication and Related Methods">Replication and Related Methods</a> 297 </p> 298 </div> 299 </div> 300 <div class="navfooter"> 301 <hr /> 302 <table width="100%" summary="Navigation footer"> 303 <tr> 304 <td width="40%" align="left"><a accesskey="p" href="repclockskew.html">Prev</a> </td> 305 <td width="20%" align="center"> 306 <a accesskey="u" href="rep.html">Up</a> 307 </td> 308 <td width="40%" align="right"> <a accesskey="n" href="repset_limit.html">Next</a></td> 309 </tr> 310 <tr> 311 <td width="40%" align="left" valign="top">DbEnv::rep_set_clockskew() </td> 312 <td width="20%" align="center"> 313 <a accesskey="h" href="index.html">Home</a> 314 </td> 315 <td width="40%" align="right" valign="top"> DbEnv::rep_set_limit()</td> 316 </tr> 317 </table> 318 </div> 319 </body> 320</html> 321