DbChannel::send_request()

#include <db_cxx.h>

int 
DbChannel::send_request(Dbt *request, u_int32_t nrequest, 
                        Dbt *response, db_timeout_t timeout,
                        u_int32_t flags);

The DbChannel::send_request() method sends a message on the message channel. The message is sent synchronously; the method blocks waiting for a response before returning. If a response is not received within the timeout value configured for this request, this method returns with an error condition.

If you do not want to block while waiting for a response from a remote site, use the DbChannel::send_msg() method.

The message sent by this method is received and handled at remote sites using a message dispatch callback, which is configured using the DbEnv::repmgr_msg_dispatch() method.

The DbChannel::send_request() method either returns a non-zero error value or throws an exception that encapsulates a non-zero error value on failure, and returns 0 on success.

Parameters

request

Refers to an array of Dbt handles. For more information, see The Dbt Handle .

Any flags provided to the Dbt handles used in this array are ignored.

nrequest

Indicates how many elements are contained in the msg array.

response

Points to a single Dbt handle, which is used to receive the response from the remote site. By default, the response is expected to be a single-part message. If there is a possibility that the response could be a multi-part message, specify DB_MULTIPLE to this method's flags parameter.

The response Dbt should specify one of the following flags: DB_DBT_MALLOC, DB_DBT_REALLOC, or DB_DBT_USERMEM.

For more information on configuring and using Dbts, see The Dbt Handle .

Note that the response Dbt can be empty. In this way an application can send an acknowledgement even if there is no other information that needs to be sent.

timeout

Configures the amount of time that may elapse while this method waits for a response from the remote site. If this timeout period elapses without a response, this method returns with an error condition.

The timeout value must be specified as an unsigned 32-bit number of microseconds, limiting the maximum timeout to roughly 71 minutes.

A timeout value of 0 indicates that the channel's default timeout value should be used. This default is configured using the DbChannel::set_timeout() method.

flags

This parameter must be set to either DB_MULTIPLE or 0.

If there is a possibility that the response can consist of multiple Dbt handles, specify DB_MULTIPLE to this parameter. In that case, the response buffer is formatted for bulk operations.

Errors

The DbChannel::send_request() method may fail and throw a DbException exception, encapsulating one of the following non-zero errors, or return one of the following non-zero errors:

DB_BUFFER_SMALL

DB_MULTIPLE was not specified for the response Dbt, but the remote site sent a response consisting of more than one Dbt; or a buffer supplied using DB_DBT_USERMEM was not large enough to contain the message response.

DB_NOSERVER

A message was sent to a remote site that has not configured a message dispatch callback function. Use the DbEnv::repmgr_msg_dispatch() method at every site belonging to the replication group to configure a message dispatch callback function.

EINVAL

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

Class

DbEnv, DbChannel

See Also

Replication and Related Methods