<!--$Id: rep_elect.so,v 1.21 2004/09/07 15:37:41 bostic Exp $-->
<!--Copyright 1997-2004 by Sleepycat Software, Inc.-->
<!--All rights reserved.-->
<!--See the file LICENSE for redistribution information.-->
<html>
<head>
<title>Berkeley DB: DbEnv::rep_elect</title>
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++">
</head>
<body bgcolor=white>
<table width="100%"><tr valign=top>
<td>
<h3>DbEnv::rep_elect</h3>
</td>
<td align=right>
<a href="../../db43-devel-4.3.21/api_cxx/api_core.html"><img src="../../db43-4.3.21/images/api.gif" alt="API"></a>
<a href="../../db43-devel-4.3.21/ref/toc.html"><img src="../../db43-4.3.21/images/ref.gif" alt="Ref"></a></td>
</tr></table>
<hr size=1 noshade>
<tt>
<h3><pre>
#include <db_cxx.h>
<p>
int
DbEnv::rep_elect(int nsites, int nvotes,
int priority, u_int32_t timeout, int *envid, u_int32_t flags);
</pre></h3>
<hr size=1 noshade>
<h3>Description: DbEnv::rep_elect</h3>
<p>The DbEnv::rep_elect method holds an election for the master of a replication
group.</p>
<p>If the election is successful, the new master's ID may be the ID of the
previous master, or the ID of the current environment. The application
is responsible for adjusting its usage of the other environments in the
replication group, including directing all database updates to the newly
selected master, in accordance with the results of this election.</p>
<p>The thread of control that calls the DbEnv::rep_elect method must not be the
thread of control that processes incoming messages; processing the
incoming messages is necessary to successfully complete an election.</p>
<h3>Parameters</h3>
<dl compact>
<dt><b>envid</b><dd>The <b>envid</b> parameter references memory into which
the newly elected master's ID is copied.
<dt><b>nsites</b><dd>The <b>nsites</b> parameter indicates the number of environments that
the application believes are in the replication group. This number is
used by Berkeley DB to avoid having two masters active simultaneously, even
in the case of a network partition. During an election, a new master
cannot be elected unless more than half of <b>nsites</b> agree on the
new master. Thus, in the face of a network partition, the side of the
partition with more than half the environments will elect a new master
and continue, while the environments communicating with fewer than half
the other environments will fail to find a new master.
<dt><b>nvotes</b><dd>The <b>nvotes</b> parameter indicates the number of votes required by
the application to successfully elect a new master. It must be a
positive integer, no greater than <b>nsites</b>, or 0 if the election
should use a simple majority of the <b>nsites</b> value as the
requirement. A warning is given if half or fewer votes are required to
win an election as that can potentially lead to multiple masters in the
face of a network partition.
<dt><b>priority</b><dd>The <b>priority</b> parameter is the priority of this environment. It
must be a positive integer, or 0 if this environment is not permitted
to become a master (see <a href="../../db43-devel-4.3.21/ref/rep/pri.html">Replication
environment priorities</a> for more information).
<dt><b>timeout</b><dd>The <b>timeout</b> parameter specifies a timeout period for an election.
If the election has not completed after <b>timeout</b> microseconds, the
election will fail.
<dt><b>flags</b><dd>The <b>flags</b> parameter is currently unused, and must be set to 0.
</dl>
<a name="2"><!--meow--></a>
<h3>Errors</h3>
<p>The DbEnv::rep_elect method
may fail and throw
<a href="../../db43-devel-4.3.21/api_cxx/except_class.html">DbException</a>,
encapsulating one of the following non-zero errors, or return one of
the following non-zero errors:</p>
<dl compact>
<dt>DB_REP_UNAVAIL<dd>The replication group was unable to elect a master, or was unable to
complete the election in the specified <b>timeout</b> period.
</dl>
<hr size=1 noshade>
<h3>Class</h3>
<a href="../../db43-devel-4.3.21/api_cxx/env_class.html">DbEnv</a>
<h3>See Also</h3>
<a href="../../db43-devel-4.3.21/api_cxx/rep_list.html">Replication and Related Methods</a>
</tt>
<table width="100%"><tr><td><br></td><td align=right>
<a href="../../db43-devel-4.3.21/api_cxx/api_core.html"><img src="../../db43-4.3.21/images/api.gif" alt="API"></a><a href="../../db43-devel-4.3.21/ref/toc.html"><img src="../../db43-4.3.21/images/ref.gif" alt="Ref"></a>
</td></tr></table>
<p><font size=1><a href="../../db43-devel-4.3.21/sleepycat/legal.html">Copyright (c) 1996-2004</a> <a href="http://www.sleepycat.com">Sleepycat Software, Inc.</a> - All rights reserved.</font>
</body>
</html>
