<!--$Id: comm.so,v 1.19 2007/03/20 20:20:27 alanb Exp $--> <!--Copyright (c) 1997,2008 Oracle. All rights reserved.--> <!--See the file LICENSE for redistribution information.--> <html> <head> <title>Berkeley DB Reference Guide: Building the communications infrastructure</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><b><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Replication</dl></b></td> <td align=right><a href="../rep/base_meth.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../rep/newsite.html"><img src="../../images/next.gif" alt="Next"></a> </td></tr></table> <p align=center><b>Building the communications infrastructure</b></p> <p>Replication Manager provides a built-in communications infrastructure.</p> <p>For applications that use the Base replication API, which must provide their own communications infrastructure, it 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->rep_process_message</a> method. Messages from the local environment are passed to the application for transmission using the callback function specified to the <a href="../../api_c/rep_transport.html">DB_ENV->rep_set_transport</a> method.</p> <p>Processes establish communication channels by calling the <a href="../../api_c/rep_transport.html">DB_ENV->rep_set_transport</a> method, regardless of whether they are running in client or server environments. This method specifies the <b>send</b> function, a callback function used by Berkeley DB for sending messages to other database environments in the replication group. The <b>send</b> function takes an environment ID and two opaque data objects. It is the responsibility of the <b>send</b> function to transmit the information in the two data objects to the database environment corresponding to the ID, with the receiving application then calling the <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> method to process the message.</p> <p>The details of the transport mechanism are left entirely to the application; the only requirement is that the data buffer and size of each of the control and rec <a href="../../api_c/dbt_class.html">DBT</a>s passed to the <b>send</b> function on the sending site be faithfully copied and delivered to the receiving site by means of a call to <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> with corresponding arguments. Messages that are broadcast (whether by broadcast media or when directed by setting the <a href="../../api_c/rep_transport.html">DB_ENV->rep_set_transport</a> method's envid parameter DB_EID_BROADCAST), should not be processed by the message sender. In all cases, the application's transport media or software must ensure that <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> is never called with a message intended for a different database environment or a broadcast message sent from the same environment on which <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> will be called. The <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> method is free-threaded; it is safe to deliver any number of messages simultaneously, and from any arbitrary thread or process in the Berkeley DB environment.</p> <p>There are a number of informational returns from the <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> method:</p> <br> <b><a href="../../api_c/rep_message.html#DB_REP_DUPMASTER">DB_REP_DUPMASTER</a></b><ul compact><li>When <a href="../../api_c/rep_message.html">DB_ENV->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 complete all active transactions, close all open database handles, reconfigure itself as a client using the <a href="../../api_c/rep_start.html">DB_ENV->rep_start</a> method, and then call for an election by calling the <a href="../../api_c/rep_elect.html">DB_ENV->rep_elect</a> method.</ul> <b><a href="../../api_c/rep_message.html#DB_REP_HOLDELECTION">DB_REP_HOLDELECTION</a></b><ul compact><li>When <a href="../../api_c/rep_message.html">DB_ENV->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->rep_elect</a> method.</ul> <b><a href="../../api_c/rep_message.html#DB_REP_IGNORE">DB_REP_IGNORE</a></b><ul compact><li>When <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> returns <a href="../../api_c/rep_message.html#DB_REP_IGNORE">DB_REP_IGNORE</a>, it means that this message cannot be processed. This is normally an indication that this message is irrelevant to the current replication state, such as a message from an old generation that arrived late.</ul> <b><a href="../../api_c/rep_message.html#DB_REP_ISPERM">DB_REP_ISPERM</a></b><ul compact><li>When <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> returns <a href="../../api_c/rep_message.html#DB_REP_ISPERM">DB_REP_ISPERM</a>, it means a permanent record, perhaps a message previously returned as <a href="../../api_c/rep_message.html#DB_REP_NOTPERM">DB_REP_NOTPERM</a> was successfully written to disk. This record may have filled a gap in the log record that allowed additional records to be written. The <b>ret_lsnp</b> contains the maximum LSN of the permanent records written.</ul> <b><a href="../../api_c/rep_message.html#DB_REP_NEWSITE">DB_REP_NEWSITE</a></b><ul compact><li>When <a href="../../api_c/rep_message.html">DB_ENV->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.</ul> <b><a href="../../api_c/rep_message.html#DB_REP_NOTPERM">DB_REP_NOTPERM</a></b><ul compact><li>When <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> returns <a href="../../api_c/rep_message.html#DB_REP_NOTPERM">DB_REP_NOTPERM</a>, it means a message marked as <a href="../../api_c/rep_transport.html#DB_REP_PERMANENT">DB_REP_PERMANENT</a> was processed successfully but was not written to disk. This is normally an indication that one or more messages, which should have arrived before this message, have not yet arrived. This operation will be written to disk when the missing messages arrive. The <b>ret_lsnp</b> argument will contain the LSN of this record. The application should take whatever action is deemed necessary to retain its recoverability characteristics.</ul> <br> <table width="100%"><tr><td><br></td><td align=right><a href="../rep/base_meth.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../rep/newsite.html"><img src="../../images/next.gif" alt="Next"></a> </td></tr></table> <p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> </body> </html>