MySQL :: MySQL NDB Cluster API Developer Guide :: 3.2.4 Management Server Connection Functions

ndb_mgm_get_connectstring()

Description: This function retrieves the connection string used for a connection.

Note

This function returns the default connection string if no call to ndb_mgm_set_connectstring() has been performed. In addition, the returned connection string may be formatted slightly differently than the original in that it may contain specifiers not present in the original.

The connection string format is the same as that discussed for ndb_mgm_set_connectstring().

Signature

const char* ndb_mgm_get_connectstring
    (
      NdbMgmHandle handle,
      char*        buffer,
      int          size
    )

Parameters

This function takes three arguments:

An NdbMgmHandle.
A pointer to a buffer in which to place the result.
The size of the buffer.

Return value

The connection string—this is the same value that is pushed to the buffer.

ndb_mgm_get_configuration_nodeid()

Description

This function gets the ID of the node to which the connection is being (or was) made.

Signature

int ndb_mgm_get_configuration_nodeid
    (
      NdbMgmHandle handle
    )

Parameters

A management server handle.

Return value

A node ID.

ndb_mgm_get_connected_port()

Description

This function retrieves the number of the port used by the connection.

Signature

int ndb_mgm_get_connected_port
    (
      NdbMgmHandle handle
    )

Parameters

An NdbMgmHandle.

Return value

A port number.

ndb_mgm_get_connected_host()

Description

This function is used to obtain the name of the host to which the connection is made.

Signature

const char* ndb_mgm_get_connected_host
    (
      NdbMgmHandle handle
    )

Parameters

A management server handle.

Return value

A host name.

ndb_mgm_get_version()

Description

Given a management server handle, this function gets NDB engine and MySQL Server version information for the indicated management server.

Signature

int ndb_mgm_get_version
    (
      NdbMgmHandle handle,
      int* major,
      int* minor,
      int* build,
      int length,
      char* string
    )

Parameters

An NdbMgmHandle, and pointers to the NDB engine major, minor, and build version values, as well as a pointer to the version string (along with the strength's length).

The version string uses the format mysql-x.x.x ndb-y.y.y-status, where x.x.x is the three-part MySQL Server version, and y.y.y is the three-part NDB storage engine version. The status string indicates the release level or status; usually this is one of beta, rc, or ga, but other values are sometimes possible.

Return value: ndb_mgm_get_version() returns an integer: 0 on success; any nonzero value indicates an error.

ndb_mgm_is_connected()

Description: Used to determine whether a connection has been established.

Note

This function does not determine whether or not there is a “live” management server at the other end of the connection. Use ndb_mgm_check_connection() to accomplish that task.

Signature

int ndb_mgm_is_connected
    (
      NdbMgmHandle handle
    )

Parameters

A management server handle.

Return value

This function returns an integer, whose value is interpreted as follows:

0: Not connected to the management node.
Any nonzero value: A connection has been established with the management node.

ndb_mgm_check_connection()

Description

This function can be used to determine whether a management server is running on a given connection from a management client.

Signature

int ndb_mgm_check_connection
    (
      NdbMgmHandle handle
    )

Parameters

An NdbMgmHandle (see Section 3.1, “MGM API Concepts”).

Return value

In NDB 7.5 and later, this function returns 0 on success, -1 when the handle is null, and -2 when not connected.

In NDB 7.4 and earlier, this function returned -1 in the event of an error; otherwise it returned 0, even when the management server handle was NULL, or when the connection check failed (Bug #53242, Bug #11760802).

ndb_mgm_number_of_mgmd_in_connect_string()

Description

This is a convenience function which provides an easy way to determine the number of management servers referenced in a connection string as set using ndb_mgm_set_connectstring().

Signature

int ndb_mgm_number_of_mgmd_in_connect_string
    (
      NdbMgmHandle handle
    )

Parameters

A management handle (NdbMgmHandle).

Return value

On success, a nonnegative integer; a negative integer indicates failure.

ndb_mgm_set_bindaddress()

Description

This function makes it possible to set a local bind address for the management server. If used, it must be called before connecting to the management server.

Signature

int ndb_mgm_set_bindaddress
    (
      NdbMgmHandle handle,
      const char*  address
    )

Parameters

This function takes two parameters:

A management handle (NdbMgmHandle).
A string address of the form host[:port].

Return value

Returns an integer:

0 indicates success
Any nonzero value indicates failure (the address was not valid)

Important

Errors caused by binding an otherwise valid local address are not reported until the connection to the management is actually attempted.

ndb_mgm_set_connect_timeout()

Description

Sets the number of seconds for timeout of network operations; the default is 3 seconds.

Supported in NDB 8.0.37 and later. Not supported by NDB 8.3.0.

Signature

int ndb_mgm_set_connect_timeout
    (
      NdbMgmHandle handle, 
      unsigned int seconds
    )

Parameters

ndb_mgm_set_connect_timeout() takes two parameters:

A management server handle.
A timeout in seconds.

Return value

This function returns 0 in the event of failure, otherwise indicates success.

ndb_mgm_set_connectstring()

Description

This function is used to set the connection string for a management server connection to a node.

Signature

int ndb_mgm_set_connectstring
    (
      NdbMgmHandle handle,
      const char*  connection_string
    )

Parameters

ndb_mgm_set_connectstring() takes two parameters:

A management server handle.
A connection_string whose format is shown here:
```
connection_string :=
    [nodeid-specification,]host-specification[,host-specification]
```
ndb_mgm_get_connectstring() also uses this format for connection strings.

It is possible to establish connections with multiple management servers using a single connection string.
```
nodeid-specification := nodeid=id
host-specification := host[:port]
```
id, port, and host are defined as follows:
- id: An integer greater than 0 identifying a node in config.ini.
- port: An integer referring to a standard Unix port.
- host: A string containing a valid network host address.

Return value

This function returns -1 in the event of failure.

ndb_mgm_set_configuration_nodeid()

Description

This function sets the connection node ID.

Signature

int ndb_mgm_set_configuration_nodeid
    (
      NdbMgmHandle handle,
      int          id
    )

Parameters

This function requires two parameters:

An NdbMgmHandle.
The id of the node to connect to.

Return value

This function returns -1 in the event of failure.

ndb_mgm_set_timeout()

Description: Sets the number of milliseconds for timeout of network operations; the default is 60 seconds.

Important

The timeout set by this function applies not only to establishing network connections, but to every operation requiring communication using a network connection. This includes each network read or write performed by any MGM API function, NDB API method call, or ndb_mgm client command.

Signature

int ndb_mgm_set_timeout
    (
      NdbMgmHandle handle,
      unsigned int timeout_ms
    )

Parameters

This function takes two parameters:

A management server handle (NdbMgmHandle).
The amount of time to wait before timing out, expressed in milliseconds. Only multiples of 1000 are supported; no function is guaranteed to return in a fraction of a second.

Return value

Returns 0 on success, with any other value representing failure.

ndb_mgm_connect()

Description

This function establishes a connection to a management server specified by the connection string set by ndb_mgm_set_connectstring().

Signature

int ndb_mgm_connect
    (
      NdbMgmHandle handle,
      int          retries,
      int          delay,
      int          verbose
    )

Parameters

This function takes 4 arguments:

A management server handle.
The number of retries to make when attempting to connect. 0 for this value means that one connection attempt is made.
The number of seconds to delay between connection attempts.

NDB 8.0.37 and later : Uses the value specified by ndb_mgm_set_connect_timeout() if unspecified.
If verbose is 1, then a message is printed for each connection attempt.

Return value

This function returns -1 in the event of failure.

ndb_mgm_disconnect()

Description

This function terminates a management server connection.

Signature

int ndb_mgm_disconnect
    (
      NdbMgmHandle handle
    )

Parameters

An NdbMgmHandle.

Return value

Returns -1 if unable to disconnect.