DB_ENV->repmgr_msg_dispatch()

#include <db.h>

int
DB_ENV->repmgr_msg_dispatch(DB_ENV *env, 
        void (*msg_dispatch_fcn) (DB_ENV *env, DB_CHANNEL *channel, 
                                  DBT *request, u_int32_t nrequest,
                                  u_int32_t cb_flags), 
        u_int32_t flags);  

Sets the message dispatch function. This function is responsible for receiving messages sent from remote sites using either the DB_CHANNEL->send_msg() or DB_CHANNEL->send_request() methods. If the message received by this function was sent using the DB_CHANNEL->send_msg() method then no response is required. If the message was sent using the DB_CHANNEL->send_request() method, then this function must send a response using the DB_CHANNEL->send_msg() method.

For best results, the DB_ENV->repmgr_msg_dispatch() method should be called before the Replication Manager has been started.

The DB_ENV->repmgr_msg_dispatch() method returns a non-zero error value on failure and 0 on success.

Parameters

msg_dispatch_fcn

This parameter is the application-specific function used to handle messages sent over Replication Manager message channels. It takes four parameters:

  • channel

    Provides the DB_CHANNEL to be used to send a response back to the originator of the message. If the message was sent by the remote site using DB_CHANNEL->send_request() then this function should send a response back to the originator using the channel provided on this parameter. The message should be sent by calling DB_CHANNEL->send_msg() exactly once.

    This channel is valid only during the current invocation of the dispatch function; it is destroyed when the dispatch function returns. The application may not save a copy of the pointer and use it later elsewhere. Methods that do not make sense in the context of a message dispatch function (such as DB_CHANNEL->send_request() and DB_CHANNEL->close() ) will be rejected with EINVAL.

  • request

    Array of DBTs containing the message received from the remote site.

  • nrequest

    Specifies the number of elements in the request array.

  • cb_flags

    This flag is DB_REPMGR_NEED_RESPONSE if the message requires a response. Otherwise, it is 0.

This function does not return a value. If the function encounters an error, you can reflect the error back to the originator of the message by formatting an error message of your own design into the response.

flags

This parameter is currently unused, and must be set to 0.

Errors

The DB_ENV->repmgr_msg_dispatch() method may fail and return one of the following non-zero errors:

EINVAL

If this method is called from a Base API application, or if an invalid flag value or parameter was specified.

Class

DB_ENV

See Also

Replication and Related Methods