ha_attach()

Attach a recovery function to a connection to make it HA-aware

Synopsis:

#include <ha/cover.h>

int ha_attach(int coid, 
              RFp rfn, 
              void *rhdl, 
              unsigned flags);

Library:

libha

Description:

The ha_attach() function attaches a recovery function to a connection in order to make the connection identified by coid HA-aware. If any operation on the connection coid returns an EBADF error, the recovery function pointed to by rfn will be called. The recovery function is defined by the following type declaration in <ha/types.h>:

typedef int (*RFp)(int coid, void *rhdl);

The recovery function identified by rfn will be called with rhdl as a parameter. The rhdl parameter is an opaque handle to data that will be interpreted and used by the recovery function itself. The recovery function is expected to perform client-specific recovery on the existing connection.

The recovery function returns a connection ID associated with the recovered connection. This connection ID must be the same as the one that had failed. The client can choose to recover in any way it thinks appropriate. It could reconnect to the same server (if the service is available), and then reconstruct its state with respect to the connection as appropriate from the client's perspective.

The client could also reconnect to a new server. The client recovery function must return the same connection ID in order to indicate successful recovery to the HA library so that the library can re-initiate the previous failed operation on the connection.

If the client doesn't want to — or can't — recover, it can return -1 to the library. The library will then immediately propagate the error relating to the failed operation on the connection back to the caller. For convenience, the HA library provides ha_reopen() and ha_ReConnectAttach() calls that close the old connection and obtain the new connection appropriately.

You normally call ha_attach() after a connection is established and a valid coid is available.

The other method to make a connection HA-aware is to call the convenience functions ha_open(), ha_creat|64(), ha_ConnectAttach|_r(), or ha_fopen().

Currently the following flag is defined:

HAREPLACERECOVERYFN

Indicates that the call to ha_attach() is replacing the recovery function with a new one. You can replace recovery functions only if the connection already has a recovery function associated with it.

Returns:

0

Success

-1

An error occurred (errno is set).

Errors:

EBADF

There's no connection identified by coid.

Or, HAREPLACERECOVERYFN is set, but there's no HA-aware connection identified by coid.

EEXIST

There's already an HA-aware connection identified by coid.

The flag HAREPLACERECOVERYFN isn't set.

ENOMEM

Memory couldn't be allocated while creating the structures in the library.

Classification:

QNX Neutrino

See also:

ha_close(), ha_detach(), ha_ConnectAttach(), ha_ConnectDetach(), ha_creat(), ha_fclose(), ha_fopen(), ha_open(), ha_ReConnectAttach(), ha_reopen()