# mco_HA_attach_master

This function is called by the replica application to request a connection to the master.

### For an overview see page HA Applications

### Prototype

        MCO_RET mco_HA_attach_master(	mco_db_h* db,
                          const char* connection_string,
                          const mco_HA_replica_params_t* params,
                          MCO_E_HA_REPLICA_STOP_REASON* reason,
                          timer_unit timeout );

### Arguments

db | Pointer to a database connection handle. If *db is NULL, `mco_HA_attach_master()` creates a new database using parameters from `db_params`. If *db is a valid connection to an existing database, the database switches to replica mode and is synchronized with the master’s.
connection_string | Transport layer dependent connection string.. For TCP/UDP transport it should be “<masterhost>:<port>”, where masterhost is the hostname or IP-address of the master node, and <port> is the number of the listening port (defined on the master side by the “masterport” parameter of `mco_nw_attach_replica()`. For example, “192.168.0.1:10000”. For PIPES transport it should be a pipe name (e.g. “/tmp/test00”).
params | Connection parameters (see mco_HA_replica_params_init).
reason | The reason why `mco_HA_attach_master()` is being interrupted., as defined below.
timeout | Connection timeout period. If the master does not connect within this period, the function returns `MCO_E_NW_TIMEOUT`.

### Description

This function is called by a replica application after calling the `mco_db_open_dev()` or `mco_db_load()` to open a database. Note that `mco_HA_attach_master()` is a blocking call that internally performs handshaking with the master, loads the master’s current state (database), and waits to accept transactions from the master. It exits when one of the following occurs:

- An unrecoverable error is detected

- Requested by the master

- A local asynchronous request from the standby’s application is issued via `mco_HA_replica_stop()`

- A cancel request is issued via `mco_HA_cancel()`

- The flag passed to the function is `MCO_HAMODE_FORCE_MASTER`; this causes the attaching process (a replica at this moment) to synchronize the database with the current master, then send a `KILL_MASTER` message to the current master, detach itself from the master and become the new master. This flag is normally associated with Binary Schema Evolution.

When the function returns, the application may elect to destroy the database, to start using it as a master database, or to start using it as a standby database again.

### Return Codes

MCO_S_OK | The master was connected successfully.
MCO_E_HA_PROTOCOLERR | Incompatible protocol.
MCO_E_HA_IOERROR | The replica was unable to send or receive a message to/from the master.
MCO_E_NW_TIMEOUT | Master not connected within the specified timeout period.
other MCO_E_NW_* codes | Errors in the network transport layer.