15 files changed, 200 insertions, 158 deletions
diff --git a/db/docs/ref/build_vxworks/introae.html b/db/docs/ref/build_vxworks/introae.html
index 4441aab5a..34b24671e 100644
--- a/db/docs/ref/build_vxworks/introae.html
+++ b/db/docs/ref/build_vxworks/introae.html
@@ -1,4 +1,4 @@
-<!--Id: introae.so,v 1.3 2001/10/12 19:21:26 bostic Exp -->
+<!--Id: introae.so,v 1.4 2001/11/05 21:05:19 sue Exp -->
 <!--Copyright 1997-2001 by Sleepycat Software, Inc.-->
 <!--All rights reserved.-->
 <html>
@@ -25,8 +25,8 @@ all component files are named <i>component.wpj</i>.
 <p><table border=1 align=center>
 <tr><th>File</th><th>Description</th></tr>
 <tr>    <td align=left>Berkeley DB/</td>    <td align=left>Berkeley DB component directory</td>    </tr>
-<tr>    <td align=left>demo/demo</td>    <td align=left>Demo program component directory</td>    </tr>
-<tr>    <td align=left>db_*/db_*</td>    <td align=left><a href="../../utility/index.html">Support utilities</a> component directories</td>    </tr>
+<tr>    <td align=left>demo/demo</td>    <td align=left><a href="../../ref/build_vxworks/notes.html">Demo program</a> component directory</td>    </tr>
+<tr>    <td align=left>db_*/db_*</td>    <td align=left><a href="../../ref/build_vxworks/notes.html">Support utilities</a> component directories</td>    </tr>
 </table>
 <h3>Building With Tornado 3.1</h3>
 <p>This document assumes you already have a workspace set up and you
diff --git a/db/docs/ref/rep/app.html b/db/docs/ref/rep/app.html
index cc4ca9bdf..abc26fdd0 100644
--- a/db/docs/ref/rep/app.html
+++ b/db/docs/ref/rep/app.html
@@ -1,4 +1,4 @@
-<!--Id: app.so,v 1.1 2001/10/13 19:56:23 bostic Exp -->
+<!--Id: app.so,v 1.3 2001/10/25 21:17:51 bostic Exp -->
 <!--Copyright 1997-2001 by Sleepycat Software, Inc.-->
 <!--All rights reserved.-->
 <html>
@@ -21,10 +21,10 @@ applications use the following additional four Berkeley DB methods:
 <a href="../../api_c/rep_elect.html">DB_ENV-&gt;rep_elect</a>, <a href="../../api_c/rep_message.html">DB_ENV-&gt;rep_process_message</a>, <a href="../../api_c/rep_start.html">DB_ENV-&gt;rep_start</a> and
 <a href="../../api_c/rep_transport.html">DB_ENV-&gt;set_rep_transport</a>:
 <p><dl compact>
+<p><dt><a href="../../api_c/rep_transport.html">DB_ENV-&gt;set_rep_transport</a><dd>The <a href="../../api_c/rep_transport.html">DB_ENV-&gt;set_rep_transport</a> function configures the replication system's
+communications infrastructure.
 <p><dt><a href="../../api_c/rep_start.html">DB_ENV-&gt;rep_start</a><dd>The <a href="../../api_c/rep_start.html">DB_ENV-&gt;rep_start</a> function configures (or reconfigures) an existing database
 environment to be a replication master or client.
-<p><dt><a href="../../api_c/rep_elect.html">DB_ENV-&gt;rep_elect</a><dd>The <a href="../../api_c/rep_elect.html">DB_ENV-&gt;rep_elect</a> function causes the replication group to elect a new
-master; it is called whenever contact with the master is lost.
 <p><dt><a href="../../api_c/rep_message.html">DB_ENV-&gt;rep_process_message</a><dd>The <a href="../../api_c/rep_message.html">DB_ENV-&gt;rep_process_message</a> function is used to process incoming messages from other
 environments in the replication group.  For clients, it is responsible
 for accepting log records and updating the local databases based on
@@ -32,8 +32,8 @@ messages from the master.  For both the master and the clients, it is
 responsible for handling administrative functions (for example, the
 protocol for dealing with lost messages), and permitting new clients to
 join an active replication group.
-<p><dt><a href="../../api_c/rep_transport.html">DB_ENV-&gt;set_rep_transport</a><dd>The <a href="../../api_c/rep_transport.html">DB_ENV-&gt;set_rep_transport</a> function configures the replication system's
-communications infrastructure.
+<p><dt><a href="../../api_c/rep_elect.html">DB_ENV-&gt;rep_elect</a><dd>The <a href="../../api_c/rep_elect.html">DB_ENV-&gt;rep_elect</a> function causes the replication group to elect a new
+master; it is called whenever contact with the master is lost.
 </dl>
 <p>To add replication to a Berkeley DB application, application initialization
 must be changed, and some new code, the application's communications
@@ -54,6 +54,10 @@ group, or, alternatively, configure all group members as clients and
 then call an election, letting the clients select the master from among
 themselves.  Either is correct, and the choice is entirely up to the
 application.
+<p>The result of calling <a href="../../api_c/rep_start.html">DB_ENV-&gt;rep_start</a> is usually the discovery of a
+master, or the declaration of the local environment as the master.  If
+a master has not been discovered after a reasonable amount of time,
+the application should call <a href="../../api_c/rep_elect.html">DB_ENV-&gt;rep_elect</a> to call for an election.
 <p>Databases are generally opened read-write on both clients and masters
 in order to simplify upgrading replication clients to be masters.  (If
 databases are opened read-only on clients, and the client is then
diff --git a/db/docs/ref/rep/comm.html b/db/docs/ref/rep/comm.html
index a58a11e0b..d7f550b7f 100644
--- a/db/docs/ref/rep/comm.html
+++ b/db/docs/ref/rep/comm.html
@@ -1,4 +1,4 @@
-<!--Id: comm.so,v 1.1 2001/10/13 19:56:23 bostic Exp -->
+<!--Id: comm.so,v 1.3 2001/10/25 20:05:34 bostic Exp -->
 <!--Copyright 1997-2001 by Sleepycat Software, Inc.-->
 <!--All rights reserved.-->
 <html>
@@ -14,14 +14,15 @@
 </td></tr></table>
 <p>
 <h1 align=center>Building the communications infrastructure</h1>
-<p>Replicated applications are typically written with one or more threads
-of control looping on one or more communication channels.  These threads
-accept messages from remote environments for the local database
-environment, and accept messages from the local environment for remote
-environments.  Messages from remote environments are passed to the local
-database environment using the <a href="../../api_c/rep_message.html">DB_ENV-&gt;rep_process_message</a> function.  Messages from the
-local environment are passed to the application for transmission using
-the callback interface specified to the <a href="../../api_c/rep_transport.html">DB_ENV-&gt;set_rep_transport</a> function.
+<p>The replication portion of an application is typically written with one
+or more threads of control looping on one or more communication
+channels, receiving and sending messages.  These threads accept messages
+from remote environments for the local database environment, and accept
+messages from the local environment for remote environments.  Messages
+from remote environments are passed to the local database environment
+using the <a href="../../api_c/rep_message.html">DB_ENV-&gt;rep_process_message</a> function.  Messages from the local environment
+are passed to the application for transmission using the callback
+interface specified to the <a href="../../api_c/rep_transport.html">DB_ENV-&gt;set_rep_transport</a> function.
 <p>Both clients and servers establish communication channels by calling
 the <a href="../../api_c/rep_transport.html">DB_ENV-&gt;set_rep_transport</a> function.  This method specifies the <b>send</b>
 interface, a callback interface used by Berkeley DB for sending messages to
@@ -42,6 +43,11 @@ arbitrary thread or process in the Berkeley DB environment.
 <p>There are a number of informational returns from the
 <a href="../../api_c/rep_message.html">DB_ENV-&gt;rep_process_message</a> function:
 <p><dl compact>
+<p><dt><a href="../../api_c/rep_message.html#DB_REP_DUPMASTER">DB_REP_DUPMASTER</a><dd>When <a href="../../api_c/rep_message.html">DB_ENV-&gt;rep_process_message</a> returns <a href="../../api_c/rep_message.html#DB_REP_DUPMASTER">DB_REP_DUPMASTER</a>, it means that
+another database environment in the replication group also believes
+itself to be the master.  The application should reconfigure itself as
+a client using the <a href="../../api_c/rep_start.html">DB_ENV-&gt;rep_start</a> function, and then call for an election by
+calling the <a href="../../api_c/rep_elect.html">DB_ENV-&gt;rep_elect</a> function.
 <p><dt><a href="../../api_c/rep_message.html#DB_REP_HOLDELECTION">DB_REP_HOLDELECTION</a><dd>When <a href="../../api_c/rep_message.html">DB_ENV-&gt;rep_process_message</a> returns <a href="../../api_c/rep_message.html#DB_REP_HOLDELECTION">DB_REP_HOLDELECTION</a>, it means
 that another database environment in the replication group has called
 for an election.  The application should call the <a href="../../api_c/rep_elect.html">DB_ENV-&gt;rep_elect</a> function.
@@ -51,18 +57,17 @@ environment's ID for that master.  If the ID of the master has changed,
 the application may need to reconfigure itself (for example, to redirect
 update queries to the new master rather then the old one).  If the new
 master is the local environment, then the application must call the
-<a href="../../api_c/rep_start.html">DB_ENV-&gt;rep_start</a> function, and to reconfigure the supporting Berkeley DB library as
-a replication master.
+<a href="../../api_c/rep_start.html">DB_ENV-&gt;rep_start</a> function, and reconfigure the supporting Berkeley DB library as a
+replication master.
 <p><dt><a href="../../api_c/rep_message.html#DB_REP_NEWSITE">DB_REP_NEWSITE</a><dd>When <a href="../../api_c/rep_message.html">DB_ENV-&gt;rep_process_message</a> returns <a href="../../api_c/rep_message.html#DB_REP_NEWSITE">DB_REP_NEWSITE</a>, it means that
 a message from a previously unknown member of the replication group has
 been received.  The application should reconfigure itself as necessary
 so it is able to send messages to this site.
 <p><dt><a href="../../api_c/rep_message.html#DB_REP_OUTDATED">DB_REP_OUTDATED</a><dd>When <a href="../../api_c/rep_message.html">DB_ENV-&gt;rep_process_message</a> returns <a href="../../api_c/rep_message.html#DB_REP_OUTDATED">DB_REP_OUTDATED</a>, it means that
-the environment has been out-of-contact with the master for too long a
-time, and the master no longer has sufficient logs in order to bring the
-local client up-to-date.  The application should shut down, and the
-client reinitialized (see <a href="../../ref/rep/init.html">Initializing
-a new site</a> for more information.)
+the environment has been partitioned from the master for too long a
+time, and the master no longer has the necessary log files to update
+the local client.  The application should shut down, and the client
+should be reinitialized (see <a href="../../ref/rep/init.html">Initializing a new site</a> for more information).
 </dl>
 <table width="100%"><tr><td><br></td><td align=right><a href="../../ref/rep/app.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rep/newsite.html"><img src="../../images/next.gif" alt="Next"></a>
 </td></tr></table>
diff --git a/db/docs/ref/rep/elect.html b/db/docs/ref/rep/elect.html
index 8aa9bd6a6..c0b2ed9ac 100644
--- a/db/docs/ref/rep/elect.html
+++ b/db/docs/ref/rep/elect.html
@@ -1,4 +1,4 @@
-<!--Id: elect.so,v 1.1 2001/10/13 19:56:23 bostic Exp -->
+<!--Id: elect.so,v 1.5 2001/10/25 21:20:01 bostic Exp -->
 <!--Copyright 1997-2001 by Sleepycat Software, Inc.-->
 <!--All rights reserved.-->
 <html>
@@ -18,22 +18,29 @@
 application.  It is not dangerous to hold an election, as the Berkeley DB
 election process ensures there is never more than a single master
 environment.  Clients should initiate an election whenever they lose
-contact with the master environment, whenever see a return of
+contact with the master environment, whenever they see a return of
 <a href="../../api_c/rep_message.html#DB_REP_HOLDELECTION">DB_REP_HOLDELECTION</a> from the <a href="../../api_c/rep_message.html">DB_ENV-&gt;rep_process_message</a> function, or when, for
-whatever reason, they do not know who the master is.
+whatever reason, they do not know who the master is.  It is not
+necessary for applications to immediately hold elections when they
+start, as any existing master will be quickly discovered after calling
+<a href="../../api_c/rep_start.html">DB_ENV-&gt;rep_start</a>.  If no master has been found after a short wait
+period, then the application should call for an election.
 <p>For a client to become the master, the client must win an election.  To
-win an election, the replication group must currently have no master
-and the client must have the highest priority of the database
-environments participating in the election.  It is dangerous to
-configure more than one master environment using the <a href="../../api_c/rep_start.html">DB_ENV-&gt;rep_start</a> function,
-and applications should be careful not to do so.  Applications should
-only configure themselves as the master environment if they are the only
-possible master, or if they have won an election.  An application can
-only know it has won an election if the <a href="../../api_c/rep_elect.html">DB_ENV-&gt;rep_elect</a> function returns
-success and the local database environment's ID as the new master
-environment ID, or if the <a href="../../api_c/rep_message.html">DB_ENV-&gt;rep_process_message</a> function returns
-<a href="../../api_c/rep_message.html#DB_REP_NEWMASTER">DB_REP_NEWMASTER</a> and the local database environment's ID as the
-new master environment ID.
+win an election, the replication group must currently have no master,
+the client must have the highest priority of the database environments
+participating in the election, and at least (N / 2 + 1) of the members
+of the replication group must participate in the election.  In the case
+of multiple database environments with equal priorities, the environment
+with the most recent log records will win.
+<p>It is dangerous to configure more than one master environment using the
+<a href="../../api_c/rep_start.html">DB_ENV-&gt;rep_start</a> function, and applications should be careful not to do so.
+Applications should only configure themselves as the master environment
+if they are the only possible master, or if they have won an election.
+An application can only know it has won an election if the
+<a href="../../api_c/rep_elect.html">DB_ENV-&gt;rep_elect</a> function returns success and the local database environment's
+ID as the new master environment ID, or if the <a href="../../api_c/rep_message.html">DB_ENV-&gt;rep_process_message</a> function
+returns <a href="../../api_c/rep_message.html#DB_REP_NEWMASTER">DB_REP_NEWMASTER</a> and the local database environment's
+ID as the new master environment ID.
 <p>To add a database environment to the replication group with the intent
 of it becoming the master, first add it as a client.  Since it may be
 out-of-date with respect to the current master, allow it to update
@@ -44,15 +51,17 @@ sufficient time to update itself with respect to the current master.
 <p>If a client is unable to find a master or win an election, it means that
 the network has been partitioned and there are not enough environments
 participating in the election for one of the participants to win.  In
-this case, the application should periodically hold an election until
-a master is found or an election is won.  In desperate circumstances,
-an application could simply declare itself the master by calling
-<a href="../../api_c/rep_start.html">DB_ENV-&gt;rep_start</a>, or by reducing the number of participants required
-to win an election until the election is won.  Neither of these
-solutions is recommended: in the case of a network partition, either of
-these choices can result in there being two masters in one replication
-group, and the databases in the environment might irretrievably diverge
-as they are modified in different ways by the masters.
+this case, the application should repeatedly call <a href="../../api_c/rep_start.html">DB_ENV-&gt;rep_start</a> and
+<a href="../../api_c/rep_elect.html">DB_ENV-&gt;rep_elect</a>, alternating between attempting to discover an
+existing master, and holding an election to declare a new one.  In
+desperate circumstances, an application could simply declare itself the
+master by calling <a href="../../api_c/rep_start.html">DB_ENV-&gt;rep_start</a>, or by reducing the number of
+participants required to win an election until the election is won.
+Neither of these solutions is recommended: in the case of a network
+partition, either of these choices can result in there being two masters
+in one replication group, and the databases in the environment might
+irretrievably diverge as they are modified in different ways by the
+masters.
 <p>Finally, it is possible for the wrong database environment to win an
 election if a number of systems crash at the same time.  Because an
 election winner is declared as soon as enough environments participate
diff --git a/db/docs/ref/rep/faq.html b/db/docs/ref/rep/faq.html
index 3670df8e9..83ed42e96 100644
--- a/db/docs/ref/rep/faq.html
+++ b/db/docs/ref/rep/faq.html
@@ -1,4 +1,4 @@
-<!--Id: faq.so,v 1.1 2001/10/13 19:56:23 bostic Exp -->
+<!--Id: faq.so,v 1.5 2001/11/17 16:59:33 bostic Exp -->
 <!--Copyright 1997-2001 by Sleepycat Software, Inc.-->
 <!--All rights reserved.-->
 <html>
@@ -10,13 +10,13 @@
 <body bgcolor=white>
 <table width="100%"><tr valign=top>
 <td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Replication</dl></h3></td>
-<td align=right><a href="../../ref/rep/trans.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/xa/intro.html"><img src="../../images/next.gif" alt="Next"></a>
+<td align=right><a href="../../ref/rep/partition.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rep/ex.html"><img src="../../images/next.gif" alt="Next"></a>
 </td></tr></table>
 <p>
 <h1 align=center>Replication FAQ</h1>
 <p><ol>
-<p><li><b>Does Berkeley DB provide support for sending database update messages
-from the client application to the master?</b>
+<p><li><b>Does Berkeley DB provide support for forwarding write queries from
+clients to masters?</b>
 <p>No, it does not.  The Berkeley DB RPC server code could be modified to support
 this functionality, but in general this protocol is left entirely to
 the application.  Note, there is no reason not to use the communications
@@ -27,24 +27,6 @@ those channels be used exclusively for replication messages.
 multiple sites?</b>
 <p>No, this is not possible.  All replicated databases must be equally
 shared by all environments in the replication group.
-<p><li><b>What happens if an environment with out-of-date information
-wins the election?</b>
-<p>This is unlikely, but it is possible, and the outcome can be the loss
-of information.  For example, consider a system with a master
-environment and two clients A and B, where client A may upgrade to
-master status and client B cannot.  Then, assume client A is partitioned
-from the other two database environments, and it becomes out-of-date
-with respect to the master.  Then, assume the master crashes and does
-not come back on-line.  Subsequently, the network partition is restored,
-and clients A and B hold an election.  As client B cannot win the
-election, client A will win by default, and in order to get back into
-sync with client B, it will unroll possibly committed transactions on
-client B until they can once again move forward together.
-<p>This scenario stresses the importance of good network infrastructure in
-your replicated environments.  When replicating database environments
-over sufficiently lossy networking, the best solution is usually to pick
-a single master, and only hold elections when human intervention has
-determined the selected master is unable to recover.
 <p><li><b>How can I distinguish Berkeley DB messages from application messages?</b>
 <p>There is no way to distinguish Berkeley DB messages from application-specific
 messages, nor does Berkeley DB offer any way to wrap application messages
@@ -57,20 +39,24 @@ send connection information to the other database environments in the
 group (see <a href="../../ref/rep/newsite.html">Connecting to a new site</a>
 for more information).
 <p><li><b>How should I build my <b>send</b> function?</b>
-<p>This depends on the specifics of the application.  One common way is
-to write the <b>rec</b> and <b>control</b> arguments' sizes and data
-to a socket connected to each remote site.
+<p>This depends on the specifics of the application.  One common way is to
+write the <b>rec</b> and <b>control</b> arguments' sizes and data to
+a socket connected to each remote site.  On a fast, local area net, the
+simplest method is likely to be construct broadcast messages.  Each
+Berkeley DB message would be encapsulated inside an application specific
+message, with header information specifying the intended recipient(s)
+for the message.  This will likely require a global numbering scheme,
+however, as the Berkeley DB library has to be able to send specific log
+records to clients apart from the general broadcast of new log records
+intended for all members of a replication group.
 <p><li><b>Can I use replication to replicate just the database
 environment's log files?</b>
-<p>Not explicitly.  However, a client replica will contain a full set of
-logs as generated by the master, within the semantic limits of the
-transport mechanism.  In the event that a master crashes, the client
-environment may be used directly (after running recovery) or for
-catastrophic recovery on the master site.
-<p><font color=red>There's a DB_REP_LOGSONLY flag -- so this is wrong, I
-think.</font>
+<p>Yes.  If the <a href="../../api_c/rep_start.html#DB_REP_LOGSONLY">DB_REP_LOGSONLY</a> flag is specified to
+<a href="../../api_c/rep_start.html">DB_ENV-&gt;rep_start</a>, the client site acts as a repository for logfiles
+(see <a href="../../ref/rep/logonly.html">Log file only clients</a> for more
+information).
 </ol>
-<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/rep/trans.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/xa/intro.html"><img src="../../images/next.gif" alt="Next"></a>
+<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/rep/partition.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rep/ex.html"><img src="../../images/next.gif" alt="Next"></a>
 </td></tr></table>
 <p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>
 </body>
diff --git a/db/docs/ref/rep/id.html b/db/docs/ref/rep/id.html
index d470db350..572fcc1d6 100644
--- a/db/docs/ref/rep/id.html
+++ b/db/docs/ref/rep/id.html
@@ -1,4 +1,4 @@
-<!--Id: id.so,v 1.2 2001/10/13 19:56:23 bostic Exp -->
+<!--Id: id.so,v 1.5 2001/11/05 17:24:27 bostic Exp -->
 <!--Copyright 1997-2001 by Sleepycat Software, Inc.-->
 <!--All rights reserved.-->
 <html>
@@ -17,19 +17,26 @@
 <p>Each database environment included in a replication group must have a
 unique identifier for itself and for the other members of the
 replication group.   The identifiers do not need to be global, that is,
-each instance of a running application can assign local identifiers to
-members of the replication group as they find out about them.  For
-example, given three sites: A, B and C, site A might assign the
-identifiers 1 and 2 to sites B and C respectively, while site B might
-assign the identifiers 301 and 302 to sites A and C respectively.  Note,
-it is not wrong to have global identifiers, of course, it is just not
-necessary.
+each database environment can assign local identifiers to members of
+the replication group as it encounters them.  For example, given three
+sites: A, B and C, site A might assign the identifiers 1 and 2 to sites
+B and C respectively, while site B might assign the identifiers 301 and
+302 to sites A and C respectively.  Note, it is not wrong to have global
+identifiers, of course, it is just not necessary.
 <p>It is the responsibility of the application to label each incoming
 replication message passed to <a href="../../api_c/rep_message.html">DB_ENV-&gt;rep_process_message</a> function with the appropriate
 identifier.  Subsequently, Berkeley DB will label outgoing messages to the
 <b>send</b> interface with those same identifiers.
 <p>Negative identifiers are reserved for use by Berkeley DB, and should never be
-assigned to environments by the application.
+assigned to environments by the application.  Two of these reserved
+identifiers are intended for application use, as follows:
+<p><dl compact>
+<p><dt><a href="../../api_c/rep_transport.html#DB_EID_BROADCAST">DB_EID_BROADCAST</a><dd>The <a href="../../api_c/rep_transport.html#DB_EID_BROADCAST">DB_EID_BROADCAST</a> identifier indicates a message should be
+broadcast to all members of a replication group.
+<p><dt><a href="../../api_c/rep_transport.html#DB_EID_INVALID">DB_EID_INVALID</a><dd>The <a href="../../api_c/rep_transport.html#DB_EID_INVALID">DB_EID_INVALID</a> identifier is an invalid environment ID, and
+may be used to initialize environment ID variables that are subsequently
+checked for validity.
+</dl>
 <table width="100%"><tr><td><br></td><td align=right><a href="../../ref/rep/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rep/pri.html"><img src="../../images/next.gif" alt="Next"></a>
 </td></tr></table>
 <p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>
diff --git a/db/docs/ref/rep/init.html b/db/docs/ref/rep/init.html
index 0ab90224d..46a784c12 100644
--- a/db/docs/ref/rep/init.html
+++ b/db/docs/ref/rep/init.html
@@ -1,4 +1,4 @@
-<!--Id: init.so,v 1.1 2001/10/13 19:56:24 bostic Exp -->
+<!--Id: init.so,v 1.2 2001/11/05 17:24:27 bostic Exp -->
 <!--Copyright 1997-2001 by Sleepycat Software, Inc.-->
 <!--All rights reserved.-->
 <html>
@@ -17,17 +17,19 @@
 <p>Perform the following steps to add a new site to the replication
 group:
 <p><ol>
-<p><li>Perform a hot backup of the master's environment, as described in
-<a href="../../ref/transapp/archival.html">Database and log file archival</a>.
-<p><li>Copy the hot backup to the client.
-<p><li>Run ordinary (non-catastrophic) recovery on the client's new
-environment, using either the <a href="../../utility/db_recover.html">db_recover</a> utility or the
-<a href="../../api_c/env_open.html#DB_RECOVER">DB_RECOVER</a> flag to <a href="../../api_c/env_open.html">DB_ENV-&gt;open</a>.
+<p><li>Do an archival backup of the master's environment, as described in
+<a href="../../ref/transapp/archival.html">Database and log file
+archival</a>.  The backup can either be a conventional backup or a hot
+backup.
+<p><li>Copy the archival backup into a clean environment directory on the
+client.
+<p><li>Run catastrophic recovery on the client's new environment, as described
+in <a href="../../ref/transapp/recovery.html">Recovery procedures</a>.
 <p><li>Reconfigure and reopen the environment as a client member of the
 replication group.
 </ol>
-<p>If copying the hot backup to the client takes a long time relative to
-the frequency with which log files are reclaimed using the
+<p>If copying the backup to the client takes a long time relative to the
+frequency with which log files are reclaimed using the
 <a href="../../utility/db_archive.html">db_archive</a> utility or the <a href="../../api_c/log_archive.html">DB_ENV-&gt;log_archive</a> function, it may be
 necessary to suppress log reclamation until the newly restarted client
 has "caught up" and applied all log records generated during its
diff --git a/db/docs/ref/rep/intro.html b/db/docs/ref/rep/intro.html
index e0d670f98..439937cd1 100644
--- a/db/docs/ref/rep/intro.html
+++ b/db/docs/ref/rep/intro.html
@@ -1,4 +1,4 @@
-<!--Id: intro.so,v 1.2 2001/10/13 20:21:47 bostic Exp -->
+<!--Id: intro.so,v 1.3 2001/10/24 19:06:38 bostic Exp -->
 <!--Copyright 1997-2001 by Sleepycat Software, Inc.-->
 <!--All rights reserved.-->
 <html>
@@ -16,19 +16,17 @@
 <p>
 <h1 align=center>Introduction</h1>
 <p>Berkeley DB includes support for building highly available applications based
-on single-master (read-only) replication.  Berkeley DB replication groups
-consist of some number of independently configured database
-environments.  The database environments might be on separate computers,
-on separate boards in a computer with replicated hardware, or on
-separate disks in a single computer.  The environments may be accessed
-by any number of applications, from one to many.  As always with Berkeley DB
+on replication.  Berkeley DB replication groups consist of some number of
+independently configured database environments.  There is a single
+<i>master</i> database environment and one or more <i>client</i>
+database environments.  Master environments support both database reads
+and writes; client environments support only database reads.  If the
+master environment fails, applications may upgrade a client to be the
+new master.  The database environments might be on separate computers,
+on separate hardware partitions in a non-uniform memory access (NUMA)
+system, or on separate disks in a single server.  As always with Berkeley DB
 environments, any number of concurrent processes or threads may access
-the database environment.
-<p>Berkeley DB replication groups contain a single <i>master</i> database
-environment and one or more <i>client</i> database environments.
-Master environments support both database reads and writes; client
-environments support only database reads.  If the master environment
-fails, applications may upgrade a client to be the new master.
+a database environment.
 <p>Applications may be written to provide various degrees of consistency
 between the master and clients.  The system can be run synchronously
 such that replicas are guaranteed to be up-to-date with all committed
diff --git a/db/docs/ref/rep/logonly.html b/db/docs/ref/rep/logonly.html
index cb1fac5b4..70860f10d 100644
--- a/db/docs/ref/rep/logonly.html
+++ b/db/docs/ref/rep/logonly.html
@@ -1,4 +1,4 @@
-<!--Id: logonly.so,v 1.1 2001/10/13 19:56:24 bostic Exp -->
+<!--Id: logonly.so,v 1.4 2001/11/06 22:20:11 bostic Exp -->
 <!--Copyright 1997-2001 by Sleepycat Software, Inc.-->
 <!--All rights reserved.-->
 <html>
@@ -14,7 +14,32 @@
 </td></tr></table>
 <p>
 <h1 align=center>Log file only clients</h1>
-<p><font color=red>Needs to be written.</font>
+<p>Applications wanting to use replication to support recovery after
+catastrophic failure of the master may want to configure a site as a
+logs-file-only replica.  Such clients cannot respond to read (or write)
+queries but still receive a complete copy the log files, so that in the
+event of master failure, catastrophic recovery can be run.
+<p>Log file only clients are configured like other client sites, except
+they should specify the <a href="../../api_c/rep_start.html#DB_REP_LOGSONLY">DB_REP_LOGSONLY</a> flag to the
+<a href="../../api_c/rep_start.html">DB_ENV-&gt;rep_start</a> function and should specify a priority of 0 to the
+<a href="../../api_c/rep_elect.html">DB_ENV-&gt;rep_elect</a> function.
+<p>To recover using a log-file-only replica, recovery must be run on the
+log files accumulated by the replica.  If the log files are entirely
+self-contained, that is, they start with log file number 1, then a log
+replica can simply run catastrophic recovery.  Obviously, if there are
+a large number of log files in this case, recovery may take a long time.
+If the log files are not self-contained, an archival copy of the
+databases must first be restored onto the replica before running
+catastrophic recovery.
+<p>More specifically, the log files accumulating on the log-file-only
+replica can take the place of the log files described in
+<i>catastrophic recovery</i> section of the
+<a href="../../ref/transapp/recovery.html">Recovery procedures</a> Berkeley DB
+Reference Guide.
+<p>In all other ways, a log-file-only site behaves as other replication
+clients do.  It should have a thread or process receiving messages and
+passing them to <a href="../../api_c/rep_message.html">DB_ENV-&gt;rep_process_message</a> and must respond to all returns
+described for that interface.
 <table width="100%"><tr><td><br></td><td align=right><a href="../../ref/rep/elect.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rep/trans.html"><img src="../../images/next.gif" alt="Next"></a>
 </td></tr></table>
 <p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>
diff --git a/db/docs/ref/rep/newsite.html b/db/docs/ref/rep/newsite.html
index 3856bbe7e..ace77acf7 100644
--- a/db/docs/ref/rep/newsite.html
+++ b/db/docs/ref/rep/newsite.html
@@ -1,4 +1,4 @@
-<!--Id: newsite.so,v 1.1 2001/10/13 19:56:24 bostic Exp -->
+<!--Id: newsite.so,v 1.2 2001/10/25 14:58:49 bostic Exp -->
 <!--Copyright 1997-2001 by Sleepycat Software, Inc.-->
 <!--All rights reserved.-->
 <html>
@@ -20,8 +20,8 @@ should assign the new site a local environment ID number, and all future
 messages from the site passed to <a href="../../api_c/rep_message.html">DB_ENV-&gt;rep_process_message</a> should include that
 environment ID number.  It is possible, of course, for the application
 to be aware of a new site before the return of <a href="../../api_c/rep_message.html">DB_ENV-&gt;rep_process_message</a> (for
-example, applications using a connection-oriented protocols are likely
-to detect new sites immediately, while applications using broadcast
+example, applications using connection-oriented protocols are likely to
+detect new sites immediately, while applications using broadcast
 protocols may not).
 <p>Regardless, in applications supporting the dynamic addition of database
 environments to replication groups, environments joining an existing
diff --git a/db/docs/ref/rep/pri.html b/db/docs/ref/rep/pri.html
index 6ceaf09be..cd92c9b13 100644
--- a/db/docs/ref/rep/pri.html
+++ b/db/docs/ref/rep/pri.html
@@ -1,4 +1,4 @@
-<!--Id: pri.so,v 1.1 2001/10/13 19:56:24 bostic Exp -->
+<!--Id: pri.so,v 1.3 2001/11/05 17:24:27 bostic Exp -->
 <!--Copyright 1997-2001 by Sleepycat Software, Inc.-->
 <!--All rights reserved.-->
 <html>
@@ -19,12 +19,14 @@ priority, which specifies a relative ordering among the different
 environments in a replication group.  This ordering determines which
 environment will be selected as a new master in case the existing master
 fails.
-<p>Priorities may be any integer.  Larger valued priorities indicate a more
-desirable master.  For example, if a replication group consists of three
-database environments, two of which are connected by an OC3 and the
-third of which is connected by a T1, the third database environment
-should be assigned a priority value which is lower than either of the
-other two.
+<p>Priorities must be a non-negative integer, but do not need to be unique
+throughout the replication group.  A priority of 0 means the system can
+never become a master, regardless.  Otherwise, larger valued priorities
+indicate a more desirable master.  For example, if a replication group
+consists of three database environments, two of which are connected by
+an OC3 and the third of which is connected by a T1, the third database
+environment should be assigned a priority value which is lower than
+either of the other two.
 <table width="100%"><tr><td><br></td><td align=right><a href="../../ref/rep/id.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rep/app.html"><img src="../../images/next.gif" alt="Next"></a>
 </td></tr></table>
 <p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>
diff --git a/db/docs/ref/rep/trans.html b/db/docs/ref/rep/trans.html
index db8bd7b13..4dac09dee 100644
--- a/db/docs/ref/rep/trans.html
+++ b/db/docs/ref/rep/trans.html
@@ -1,4 +1,4 @@
-<!--Id: trans.so,v 1.1 2001/10/13 19:56:24 bostic Exp -->
+<!--Id: trans.so,v 1.5 2001/11/05 17:24:27 bostic Exp -->
 <!--Copyright 1997-2001 by Sleepycat Software, Inc.-->
 <!--All rights reserved.-->
 <html>
@@ -10,7 +10,7 @@
 <body bgcolor=white>
 <table width="100%"><tr valign=top>
 <td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Replication</dl></h3></td>
-<td align=right><a href="../../ref/rep/logonly.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rep/faq.html"><img src="../../images/next.gif" alt="Next"></a>
+<td align=right><a href="../../ref/rep/logonly.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rep/partition.html"><img src="../../images/next.gif" alt="Next"></a>
 </td></tr></table>
 <p>
 <h1 align=center>Transactional guarantees</h1>
@@ -23,15 +23,14 @@ information is reviewed during recovery, and the databases are updated
 so that all changes made as part of committed transactions appear, and
 all changes made as part of uncommitted transactions do not appear.  In
 this case, no information will have been lost.
-<p>If the database environment has been configured to not synchronously
-flush the log to stable storage when transactions are committed (using
-the <a href="../../api_c/env_open.html#DB_TXN_NOSYNC">DB_TXN_NOSYNC</a> flag to increase performance at the cost of
-sacrificing transactional durability), Berkeley DB recovery will only be able
-to restore the system to the state of the last commit found on stable
-storage.  In this case, information may have been lost (for example,
-changes made on the part of a committed transaction may not appear in
-a database).
-<p>Finally, if there is database or log file loss or corruption (for
+<p>If a database environment does not require that the log be flushed to
+stable storage on transaction commit (using the <a href="../../api_c/env_set_flags.html#DB_TXN_NOSYNC">DB_TXN_NOSYNC</a>
+flag to increase performance at the cost of sacrificing transactional
+durability), Berkeley DB recovery will only be able to restore the system to
+the state of the last commit found on stable storage.  In this case,
+information may have been lost (for example, the changes made by some
+committed transactions may not appear in the databases after recovery).
+<p>Further, if there is database or log file loss or corruption (for
 example, if a disk drive fails), then catastrophic recovery is
 necessary, and Berkeley DB recovery will only be able to restore the system
 to the state of the last archived log file.  In this case, information
@@ -40,11 +39,12 @@ may also have been lost.
 new component to "stable storage": the client's replicated information.
 If a database environment is replicated, there is no lost information
 in the case of database or log file loss, because the replicated system
-contains a complete set of databases and log records up to the point of
-failure.  A database environment that loses a disk drive can have the
-drive replaced, and it can rejoin the replication group as a client.
+can be configured to contain a complete set of databases and log records
+up to the point of failure.  A database environment that loses a disk
+drive can have the drive replaced, and it can rejoin the replication
+group as a client.
 <p>Because of this new component of stable storage, specifying
-<a href="../../api_c/env_open.html#DB_TXN_NOSYNC">DB_TXN_NOSYNC</a> in a replicated environment no longer sacrifices
+<a href="../../api_c/env_set_flags.html#DB_TXN_NOSYNC">DB_TXN_NOSYNC</a> in a replicated environment no longer sacrifices
 durability, as long as one or more clients have acknowledged receipt of
 the messages sent by the master.  Since network connections are often
 faster than local disk writes, replication becomes a way for
@@ -57,13 +57,14 @@ of the <b>send</b> interface returning failure is to flush the local
 database environment's log as necessary to ensure that any information
 critical to database integrity is not lost.  Because this flush is an
 expensive operation in terms of database performance, applications will
-want to avoid returning an error from the <b>send</b> interface.
+want to avoid returning an error from the <b>send</b> interface, unless
+it is absolutely necessary.
 <p>First, there is no reason for the <b>send</b> interface to ever return
 failure unless the <a href="../../api_c/rep_transport.html#DB_REP_PERMANENT">DB_REP_PERMANENT</a> flag is specified.  Messages
 without that flag do not make visible changes to databases, and
 therefore the application's <b>send</b> interface can return success
-to Berkeley DB immediately after it has broadcast the message (or even simply
-copied the message to local memory).
+to Berkeley DB immediately after it has sent the message (or even simply
+copied the message to its local memory).
 <p>Further, unless the master's database environment has been configured
 to not synchronously flush the log on transaction commit, there is no
 reason for the <b>send</b> interface to ever return failure, as any
@@ -76,25 +77,26 @@ should be recovered before holding an election, as only the master
 database environment is guaranteed to have the most up-to-date logs.
 <p>To sum up, the only reason for the <b>send</b> interface to return
 failure is when the master database environment has been configured to
-not synchronously flush the log on transaction commit and the
-<b>send</b> interface was unable to determine that some number of
-clients received the message.  How many clients should have received
-the message before the <b>send</b> interface can return success is an
-application choice, and, in fact, may not depend as much on a specific
-number of clients reporting success as one or more geographically
-distributed clients.
+not synchronously flush the log on transaction commit, the
+<a href="../../api_c/rep_transport.html#DB_REP_PERMANENT">DB_REP_PERMANENT</a> flag is specified, and the <b>send</b>
+interface was unable to determine that some number of clients have
+received the current message (and all messages preceding the current
+message).  How many clients should receive the message before the
+<b>send</b> interface can return success is an application choice, and,
+in fact, may not depend as much on a specific number of clients
+reporting success as one or more geographically distributed clients.
 <p>Of course, it is important to ensure that the replicated master and
 client environments are truly independent of each other.  For example,
 it does not help matters that a client has acknowledged receipt of a
 message if both master and clients are on the same power supply, as the
 failure of the power supply will still potentially lose information.
 <p>Finally, the Berkeley DB replication implementation has one other additional
-feature to increase application reliability.  Replication in Berkeley DB was
+feature to increase application reliability.  Replication in Berkeley DB is
 implemented to perform database updates using a different code path than
 the standard ones.  This means operations which manage to crash the
 replication master due to a software bug will not necessarily also crash
 replication clients.
-<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/rep/logonly.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rep/faq.html"><img src="../../images/next.gif" alt="Next"></a>
+<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/rep/logonly.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rep/partition.html"><img src="../../images/next.gif" alt="Next"></a>
 </td></tr></table>
 <p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>
 </body>
diff --git a/db/docs/ref/upgrade.4.0/disk.html b/db/docs/ref/upgrade.4.0/disk.html
index 1bb72138e..230840167 100644
--- a/db/docs/ref/upgrade.4.0/disk.html
+++ b/db/docs/ref/upgrade.4.0/disk.html
@@ -1,4 +1,4 @@
-<!--Id: disk.so,v 1.9 2001/09/18 16:08:16 bostic Exp -->
+<!--Id: disk.so,v 1.10 2001/11/09 22:11:29 bostic Exp -->
 <!--Copyright 1997-2001 by Sleepycat Software, Inc.-->
 <!--All rights reserved.-->
 <html>
@@ -10,7 +10,7 @@
 <body bgcolor=white>
 <table width="100%"><tr valign=top>
 <td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td>
-<td align=right><a href="../../ref/upgrade.4.0/java.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/test/run.html"><img src="../../images/next.gif" alt="Next"></a>
+<td align=right><a href="../../ref/upgrade.4.0/asr.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/test/run.html"><img src="../../images/next.gif" alt="Next"></a>
 </td></tr></table>
 <p>
 <h1 align=center>Release 4.0: upgrade requirements</h1>
@@ -18,7 +18,7 @@
 formats changed in the Berkeley DB 4.0 release.
 <p>For further information on upgrading Berkeley DB installations, see
 <a href="../../ref/upgrade/process.html">Upgrading Berkeley DB installations</a>.
-<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.4.0/java.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/test/run.html"><img src="../../images/next.gif" alt="Next"></a>
+<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.4.0/asr.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/test/run.html"><img src="../../images/next.gif" alt="Next"></a>
 </td></tr></table>
 <p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>
 </body>
diff --git a/db/docs/ref/upgrade.4.0/java.html b/db/docs/ref/upgrade.4.0/java.html
index cb51dd8bc..788620b18 100644
--- a/db/docs/ref/upgrade.4.0/java.html
+++ b/db/docs/ref/upgrade.4.0/java.html
@@ -1,4 +1,4 @@
-<!--Id: java.so,v 1.4 2001/09/25 21:05:24 bostic Exp -->
+<!--Id: java.so,v 1.6 2001/11/14 02:27:12 bostic Exp -->
 <!--Copyright 1997-2001 by Sleepycat Software, Inc.-->
 <!--All rights reserved.-->
 <html>
@@ -10,7 +10,7 @@
 <body bgcolor=white>
 <table width="100%"><tr valign=top>
 <td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td>
-<td align=right><a href="../../ref/upgrade.4.0/lock_id_free.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.0/disk.html"><img src="../../images/next.gif" alt="Next"></a>
+<td align=right><a href="../../ref/upgrade.4.0/lock_id_free.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.0/cxx.html"><img src="../../images/next.gif" alt="Next"></a>
 </td></tr></table>
 <p>
 <h1 align=center>Release 4.0: Java CLASSPATH environment variable</h1>
@@ -25,7 +25,7 @@ example, on UNIX:
 <p>For more information on Java configuration, please see
 <a href="../../ref/java/conf.html">Java configuration</a> and
 <a href="../../ref/build_win/intro.html">Building for Win32</a>.
-<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.4.0/lock_id_free.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.0/disk.html"><img src="../../images/next.gif" alt="Next"></a>
+<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.4.0/lock_id_free.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.0/cxx.html"><img src="../../images/next.gif" alt="Next"></a>
 </td></tr></table>
 <p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>
 </body>
diff --git a/db/docs/ref/upgrade.4.0/toc.html b/db/docs/ref/upgrade.4.0/toc.html
index 3c579f944..ad2033946 100644
--- a/db/docs/ref/upgrade.4.0/toc.html
+++ b/db/docs/ref/upgrade.4.0/toc.html
@@ -1,4 +1,4 @@
-<!--Id: toc.so,v 1.13 2001/09/25 21:05:25 bostic Exp -->
+<!--Id: toc.so,v 1.15 2001/11/14 02:27:12 bostic Exp -->
 <!--Copyright 1997-2001 by Sleepycat Software, Inc.-->
 <!--All rights reserved.-->
 <html>
@@ -26,6 +26,8 @@
 <li><a href="set_lk_max.html">Release 4.0: DB_ENV-&gt;set_lk_max</a>
 <li><a href="lock_id_free.html">Release 4.0: DB_ENV-&gt;lock_id_free</a>
 <li><a href="java.html">Release 4.0: Java CLASSPATH environment variable</a>
+<li><a href="cxx.html">Release 4.0: C++ ostream objects</a>
+<li><a href="asr.html">Release 4.0: application-specific recovery</a>
 <li><a href="disk.html">Release 4.0: upgrade requirements</a>
 </ol>
 <table width="100%"><tr><td><br></td><td align=right><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a>