Chapter 3 The MGM API
Previous   Next

Chapter 3 The MGM API

Table of Contents

3.1 MGM API Concepts
3.1.1 Working with Log Events
3.1.2 Structured Log Events
3.2 MGM API Function Listing
3.2.1 Log Event Functions
3.2.2 MGM API Error Handling Functions
3.2.3 Management Server Handle Functions
3.2.4 Management Server Connection Functions
3.2.5 Cluster Status Functions
3.2.6 Functions for Starting & Stopping Nodes
3.2.7 Cluster Log Functions
3.2.8 Backup Functions
3.2.9 Single-User Mode Functions
3.3 MGM API Data Types
3.3.1 The ndb_mgm_node_type Type
3.3.2 The ndb_mgm_node_status Type
3.3.3 The ndb_mgm_error Type
3.3.4 The Ndb_logevent_type Type
3.3.5 The ndb_mgm_event_severity Type
3.3.6 The ndb_logevent_handle_error Type
3.3.7 The ndb_mgm_event_category Type
3.4 MGM API Structures
3.4.1 The ndb_logevent Structure
3.4.2 The ndb_mgm_node_state Structure
3.4.3 The ndb_mgm_cluster_state Structure
3.4.4 The ndb_mgm_reply Structure
3.5 MGM API Errors
3.5.1 Request Errors
3.5.2 Node ID Allocation Errors
3.5.3 Service Errors
3.5.4 Backup Errors
3.5.5 Single User Mode Errors
3.5.6 General Usage Errors
3.6 MGM API Examples
3.6.1 Basic MGM API Event Logging Example
3.6.2 MGM API Event Handling with Multiple Clusters

Abstract

This chapter discusses the NDB Cluster Management API, a C language API that is used for administrative tasks such as starting and stopping Cluster nodes, backups, and logging. It also covers MGM API concepts, programming constructs, and event types.

3.1 MGM API Concepts

3.1.1 Working with Log Events
3.1.2 Structured Log Events

Each MGM API function needs a management server handle of type NdbMgmHandle. This handle is created by calling the function ndb_mgm_create_handle() and freed by calling ndb_mgm_destroy_handle().

See Section 3.2.3.1, “ndb_mgm_create_handle()”, and Section 3.2.3.4, “ndb_mgm_destroy_handle()”, for more information about these two functions.

Important

You should not share an NdbMgmHandle between threads. While it is possible to do so (if you implement your own locks), this is not recommended; each thread should use its own management server handle.

A function can return any of the following:

  • An integer value, with a value of -1 indicating an error.

  • A nonconstant pointer value. A NULL value indicates an error; otherwise, the return value must be freed by the programmer.

  • A constant pointer value, with a NULL value indicating an error. The returned value should not be freed.

Error conditions can be identified by using the appropriate error-reporting functions ndb_mgm_get_latest_error() and ndb_mgm_error().

Here is an example using the MGM API (without error handling for brevity's sake): 

NdbMgmHandle handle= ndb_mgm_create_handle();
ndb_mgm_connect(handle,0,0,0);
struct ndb_mgm_cluster_state *state= ndb_mgm_get_status(handle);
for(int i=0; i < state->no_of_nodes; i++)
{
  struct ndb_mgm_node_state *node_state= &state->node_states[i];
  printf("node with ID=%d ", node_state->node_id);

  if(node_state->version != 0)
    printf("connected\n");
  else
    printf("not connected\n");
}
free((void*)state);
ndb_mgm_destroy_handle(&handle);

3.1.1 Working with Log Events

Data nodes and management servers regularly and on specific occasions report on various log events that occur in the cluster. These log events are written to the cluster log. Optionally an MGM API client may listen to these events using the method ndb_mgm_listen_event(). Each log event belongs to a category ndb_mgm_event_category) and has a severity ndb_mgm_event_severity associated with it. Each log event also has a level (0-15) associated with it.

Which log events that come out is controlled with ndb_mgm_listen_event(), ndb_mgm_set_clusterlog_loglevel(), and ndb_mgm_set_clusterlog_severity_filter().

This is an example showing how to listen to events related to backup: 

int filter[] = { 15, NDB_MGM_EVENT_CATEGORY_BACKUP, 0 };
int fd = ndb_mgm_listen_event(handle, filter);

3.1.2 Structured Log Events

The following steps are involved:

  1. Create an NdbLogEventHandle using ndb_mgm_create_logevent_handle().

  2. Wait for and store log events using ndb_logevent_get_next().

  3. The log event data is available in the structure ndb_logevent. The data which is specific to a particular event is stored in a union between structures; use ndb_logevent::type to decide which structure is valid.

The following sample code demonstrates listening to events related to backups: 

int filter[] = { 15, NDB_MGM_EVENT_CATEGORY_BACKUP, 0 };
NdbLogEventHandle le_handle= ndb_mgm_create_logevent_handle(handle, filter);
struct ndb_logevent le;
int r= ndb_logevent_get_next(le_handle, &le, 0);
if(r < 0)
  /*  error  */
else if(r == 0)
  /*  no event  */

switch(le.type)
{
  case NDB_LE_BackupStarted:
    ... le.BackupStarted.starting_node;
    ... le.BackupStarted.backup_id;
    break;
  case NDB_LE_BackupFailedToStart:
    ... le.BackupFailedToStart.error;
    break;
  case NDB_LE_BackupCompleted:
    ... le.BackupCompleted.stop_gci;
    break;
  case NDB_LE_BackupAborted:
    ... le.BackupStarted.backup_id;
    break;
  default:
    break;
}

For more information, see Section 3.2.1, “Log Event Functions”.

Available log event types are listed in Section 3.3.4, “The Ndb_logevent_type Type”, as well as in the file /storage/ndb/include/mgmapi/ndb_logevent.h in the NDB Cluster sources.

3.2 MGM API Function Listing

3.2.1 Log Event Functions
3.2.2 MGM API Error Handling Functions
3.2.3 Management Server Handle Functions
3.2.4 Management Server Connection Functions
3.2.5 Cluster Status Functions
3.2.6 Functions for Starting & Stopping Nodes
3.2.7 Cluster Log Functions
3.2.8 Backup Functions
3.2.9 Single-User Mode Functions

Abstract

This section covers the structures and functions used in the MGM API. Listings are grouped by purpose or use.

3.2.1 Log Event Functions

3.2.1.1 ndb_mgm_listen_event()
3.2.1.2 ndb_mgm_create_logevent_handle()
3.2.1.3 ndb_mgm_destroy_logevent_handle()
3.2.1.4 ndb_logevent_get_fd()
3.2.1.5 ndb_logevent_get_next()
3.2.1.6 ndb_logevent_get_next2()
3.2.1.7 ndb_logevent_get_latest_error()
3.2.1.8 ndb_logevent_get_latest_error_msg()

Abstract

This section discusses functions that are used for listening to log events.

3.2.1.1 ndb_mgm_listen_event()

Description.  This function is used to listen to log events, which are read from the return file descriptor. Events use a text-based format, the same as in the cluster log.

Signature.  

int ndb_mgm_listen_event
    (
      NdbMgmHandle handle,
      const int    filter[]
    )

Parameters.  This function takes two arguments:

  • An NdbMgmHandle handle.

  • A filter which consists of a series of {level, ndb_mgm_event_category} pairs (in a single array) that are pushed to a file descriptor. Use 0 for the level to terminate the list.

Return value.  The file descriptor from which events are to be read.

3.2.1.2 ndb_mgm_create_logevent_handle()

Description.  This function is used to create a log event handle.

Signature.  

NdbLogEventHandle ndb_mgm_create_logevent_handle
    (
      NdbMgmHandle handle,
      const int    filter[]
    )

Parameters.  This function takes two arguments:

  • An NdbMgmHandle handle.

  • A filter which consists of a series of {level, ndb_mgm_event_category} pairs (in a single array) that are pushed to a file descriptor. Use 0 for the level to terminate the list.

Return value.  A log event handle.

3.2.1.3 ndb_mgm_destroy_logevent_handle()

Description.  Use this function to destroy a log event handle when there is no further need for it.

Signature.  

void ndb_mgm_destroy_logevent_handle
    (
      NdbLogEventHandle* handle
    )

Parameters.  A pointer to a log event handle.

Return value.  None.

3.2.1.4 ndb_logevent_get_fd()

Description.  This function retrieves a file descriptor from an NdbMgmLogEventHandle. It was implemented in MySQL 5.1.12.

Warning

Do not attempt to read from the file descriptor returned by this function.

Signature.  

int ndb_logevent_get_fd
    (
      const NdbLogEventHandle handle
    )

Parameters.  A LogEventHandle.

Return value.  A file descriptor. In the event of failure, -1 is returned.

3.2.1.5 ndb_logevent_get_next()

Description.  This function is used to retrieve the next log event, using data from the event to fill in the supplied ndb_logevent structure.

Signature.  

int ndb_logevent_get_next
    (
      const NdbLogEventHandle handle,
      struct ndb_logevent*    logevent,
      unsigned                timeout
    )

Important

Prior to NDB 7.2.14 and NDB 7.3.2, the log event's ndb_mgm_event_category was cast to an enum type. This behavior, although incorrect, interefered with existing applications and was reinstated in NDB 7.2.18 and NDB 7.3.7; a new function exhibiting the corrected behavior ndb_logevent_get_next2() was added in these releases.

Parameters.  Three parameters are expected by this function:

  • An NdbLogEventHandle

  • A pointer to an ndb_logevent data structure

  • The number of milliseconds to wait for the event before timing out; passing 0 for this parameter causes the function to block until the next log event is received

Return value.  The value returned by this function is interpreted as follows: If the return value is less than or equal to zero, then the logevent is not altered or affected in any way.

  • > 0: The event exists, and it data was retrieved into the logevent

  • 0: A timeout occurred while waiting for the event (more than timeout milliseconds elapsed)

  • < 0: An error occurred.

3.2.1.6 ndb_logevent_get_next2()

Description.  This function is used to retrieve the next log event, using data from the event to fill in the supplied ndb_logevent structure.

ndb_logevent_get_next2() was added in NDB 7.2.18 and NDB 7.3.7. It is intended to serve as a replacement for ndb_logevent_get_next() which corrects that function's handling of the structure's ndb_mgm_event_category, for applications which do not require backward compatibility. It is otherwise identical to ndb_logevent_get_next().

Signature.  

int ndb_logevent_get_next2
    (
      const NdbLogEventHandle handle,
      struct ndb_logevent*    logevent,
      unsigned                timeout
    )

Parameters.  Three parameters are expected by this function:

  • An NdbLogEventHandle

  • A pointer to an ndb_logevent data structure

  • The number of milliseconds to wait for the event before timing out; passing 0 for this parameter causes the function to block until the next log event is received

Return value.  The value returned by this function is interpreted as follows: If the return value is less than or equal to zero, then the logevent is not altered or affected in any way.

  • > 0: The event exists, and it data was retrieved into the logevent

  • 0: A timeout occurred while waiting for the event (more than timeout milliseconds elapsed)

  • < 0: An error occurred.

3.2.1.7 ndb_logevent_get_latest_error()

Description.  This function retrieves the error code from the most recent error.

Note

You may prefer to use ndb_logevent_get_latest_error_msg() instead. See Section 3.2.1.8, “ndb_logevent_get_latest_error_msg()”

Signature.  

int ndb_logevent_get_latest_error
    (
      const NdbLogEventHandle handle
    )

Parameters.  A log event handle.

Return value.  An error code.

3.2.1.8 ndb_logevent_get_latest_error_msg()

Description.  Retrieves the text of the most recent error obtained while trying to read log events.

Signature.  

const char* ndb_logevent_get_latest_error_msg
    (
      const NdbLogEventHandle handle
    )

Parameters.  A log event handle.

Return value.  The text of the error message.

3.2.2 MGM API Error Handling Functions

3.2.2.1 ndb_mgm_get_latest_error()
3.2.2.2 ndb_mgm_get_latest_error_msg()
3.2.2.3 ndb_mgm_get_latest_error_desc()
3.2.2.4 ndb_mgm_set_error_stream()

Abstract

The MGM API functions used for error handling are discussed in this section.

Each MGM API error is characterised by an error code and an error message. There may also be an error description that may provide additional information about the error. The API provides functions to obtain this information in the event of an error.

3.2.2.1 ndb_mgm_get_latest_error()

Description.  This function is used to get the latest error code associated with a given management server handle.

Prior to NDB 7.4.8, this function was not safe for use with NULL. In later versions, ndb_mgm_get_latest_error() is null-safe but returns an arbitrary value. (Bug #78130, Bug #21651706)

Signature.  

int ndb_mgm_get_latest_error
    (
      const NdbMgmHandle handle
    )

Parameters.  An NdbMgMHandle.

Return value.  An error code corresponding to an ndb_mgm_error value. You can obtain the related error message using ndb_mgm_get_latest_error_msg().

3.2.2.2 ndb_mgm_get_latest_error_msg()

Description.  This function is used to obtain the latest general error message associated with an NdbMgmHandle.

Prior to NDB 7.4.8, this function was not safe for use with NULL. In later versions, ndb_mgm_get_latest_error_msg() is null-safe but returns an arbitrary value. (Bug #78130, Bug #21651706)

Signature.  

const char* ndb_mgm_get_latest_error_msg
    (
      const NdbMgmHandle handle
    )

Parameters.  An NdbMgmHandle.

Return value.  The error message text. More specific information can be obtained using ndb_mgm_get_latest_error_desc()-

3.2.2.3 ndb_mgm_get_latest_error_desc()

Description.  Get the most recent error description associated with an NdbMgmHandle; this description provides additional information regarding the error message.

Prior to NDB 7.4.8, this function was not safe for use with NULL. In later versions, ndb_mgm_get_latest_error_desc() is null-safe but returns an arbitrary value. (Bug #78130, Bug #21651706)

Signature.  

const char* ndb_mgm_get_latest_error_desc
    (
      const NdbMgmHandle handle
    )

Parameters.  An NdbMgmHandle.

Return value.  The error description text.

3.2.2.4 ndb_mgm_set_error_stream()

Description.  The function can be used to set the error output stream.

Signature.  

void ndb_mgm_set_error_stream
    (
      NdbMgmHandle handle,
      FILE*        file
    )

Parameters.  This function requires two parameters:

  • An NdbMgmHandle

  • A pointer to the file to which errors are to be sent.

Return value.  None.

3.2.3 Management Server Handle Functions

3.2.3.1 ndb_mgm_create_handle()
3.2.3.2 ndb_mgm_set_name()
3.2.3.3 ndb_mgm_set_ignore_sigpipe()
3.2.3.4 ndb_mgm_destroy_handle()

Abstract

This section contains information about the MGM API functions used to create and destroy management server handles.

3.2.3.1 ndb_mgm_create_handle()

Description.  This function is used to create a handle to a management server.

Signature.  

NdbMgmHandle ndb_mgm_create_handle
    (
      void
    )

Parameters.  None.

Return value.  An NdbMgmHandle.

3.2.3.2 ndb_mgm_set_name()

Description.  This function can be used to set a name for the management server handle, which is then reported in the Cluster log.

Signature.  

void ndb_mgm_set_name
    (
      NdbMgmHandle handle,
      const char*  name
    )

Parameters.  This function takes two arguments:

  • A management server handle.

  • The desired name for the handle.

Return value.  None.

3.2.3.3 ndb_mgm_set_ignore_sigpipe()

Description.  The MGM API by default installs a signal handler that ignores all SIGPIPE signals that might occur when writing to asocket that has been closed or reset. An application that provides its own handler for SIGPIPE should call this function after creating the management server handle and before using the handle to connect to the management server. (In other words, call this function after using ndb_mgm_create_handle() but before calling ndb_mgm_connect(), which causes the MGM API's SIGPIPE handler to be installed unless overridden.)

Signature.  

int ndb_mgm_set_ignore_sigpipe
    (
      NdbMgmHandle handle,
      int ignore = 1
    )

Parameters.  This function takes two parameters:

  • A management server handle

  • An integer value which determines whether to ignore SIGPIPE errors. Set this to 1 (the default) to cause the MGM API to ignore SIGPIPE; set to zero if you wish for SIGPIPE to propagate to your MGM API application.

Return value.  None.

3.2.3.4 ndb_mgm_destroy_handle()

Description.  This function destroys a management server handle

Signature.  

void ndb_mgm_destroy_handle
    (
      NdbMgmHandle* handle
    )

Parameters.  A pointer to the NdbMgmHandle to be destroyed.

Return value.  None.

3.2.4 Management Server Connection Functions

3.2.4.1 ndb_mgm_get_connectstring()
3.2.4.2 ndb_mgm_get_configuration_nodeid()
3.2.4.3 ndb_mgm_get_connected_port()
3.2.4.4 ndb_mgm_get_connected_host()
3.2.4.5 ndb_mgm_get_version()
3.2.4.6 ndb_mgm_is_connected()
3.2.4.7 ndb_mgm_check_connection()
3.2.4.8 ndb_mgm_number_of_mgmd_in_connect_string()
3.2.4.9 ndb_mgm_set_bindaddress()
3.2.4.10 ndb_mgm_set_connectstring()
3.2.4.11 ndb_mgm_set_configuration_nodeid()
3.2.4.12 ndb_mgm_set_timeout()
3.2.4.13 ndb_mgm_connect()
3.2.4.14 ndb_mgm_disconnect()

Abstract

This section discusses MGM API functions that are used to initiate, configure, and terminate connections to an NDB management server.

3.2.4.1 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 Section 3.2.4.10, “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.

3.2.4.2 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.

3.2.4.3 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.

3.2.4.4 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.

3.2.4.5 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.

3.2.4.6 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. Beginning with MySQL 5.1.17, you can 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.

3.2.4.7 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.

Prior to MySQL 5.1.17, this function was available but required extremely large timeouts to be configured for it to be effective.

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).

3.2.4.8 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().

This function was added in MySQL 5.1.18.

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.

3.2.4.9 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.

This function was added in MySQL 5.1.18.

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.

3.2.4.10 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.

3.2.4.11 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.

3.2.4.12 ndb_mgm_set_timeout()

Description.  Normally, network operations time out after 60 seconds. This function permits you to vary this time.

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.

This function was introduced in MySQL 5.1.18.

Signature.  

int ndb_mgm_set_timeout
    (
      NdbMgmHandle handle,
      unsigned int timeout
    )

Parameters.  This function takes two parameters:

  • A management server handle (NdbMgmHandle).

  • An amount of time to wait before timing out, expressed in milliseconds.

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

3.2.4.13 ndb_mgm_connect()

Description.  This function establishes a connection to a management server specified by the connection string set by Section 3.2.4.10, “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.

  • If verbose is 1, then a message is printed for each connection attempt.

Return value.  This function returns -1 in the event of failure.

3.2.4.14 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.

3.2.5 Cluster Status Functions

3.2.5.1 ndb_mgm_get_status()
3.2.5.2 ndb_mgm_get_status2()
3.2.5.3 ndb_mgm_dump_state()

Abstract

This section discusses how to obtain status information from NDB Cluster nodes.

3.2.5.1 ndb_mgm_get_status()

Description.  This function is used to obtain the status of the nodes in an NDB Cluster.

Note

The caller must free the pointer returned by this function.

Signature.  

struct ndb_mgm_cluster_state* ndb_mgm_get_status
    (
      NdbMgmHandle handle
    )

Parameters.  This function takes a single parameter, a management server handle.

Return value.  A pointer to an ndb_mgm_cluster_state data structure.

3.2.5.2 ndb_mgm_get_status2()

Description.  This function is similar to ndb_mgm_get_status(), in that it is used to obtain the status of the nodes in an NDB Cluster. However, ndb_mgm_get_status2() allows one to specify the type or types of nodes (ndb_mgm_node_type) to be checked.

Note

The caller must free the pointer returned by this function.

Signature.  

struct ndb_mgm_cluster_state* ndb_mgm_get_status2
    (
      NdbMgmHandle handle,
      const enum ndb_mgm_node_type types[]
    )

Parameters.  This function takes two parameters:

  • A management server handle

  • A pointer to array of the node types to be checked. These are ndb_mgm_node_type values. The array should be terminated by an element of type NDB_MGM_NODE_TYPE_UNKNOWN.

Return value.  A pointer to an ndb_mgm_cluster_state data structure.

3.2.5.3 ndb_mgm_dump_state()

Description.  This function can be used to dump debugging information to the cluster log. The NDB Cluster management client DUMP command is a wrapper for this function.

Important

ndb_mgm_dump_state(), like the DUMP command, can cause a running NDB Cluster to malfunction or even to fail completely if it is used improperly. Be sure to consult the relevant documentation before using this function. For more information on the DUMP command, and for a listing of current DUMP codes and their effects, see NDB Cluster Management Client DUMP Commands.

Signature.  

int ndb_mgm_dump_state
    (
      NdbMgmHandle handle,
      int nodeId,
      const int* arguments,
      int numberOfArguments,
      struct ndb_mgm_reply* reply
    )

Parameters.  This function takes the following pararemeters:

  • A management server handle (NdbMgmHandle)

  • The nodeId of a cluster data node.

  • An array of arguments. The first of these is the DUMP code to be executed. Subsequent arguments can be passed in this array if needed by or desired for the corresponding DUMP command.

  • The numberOfArguments to be passed.

  • An ndb_mgm_reply, which contains a return code along with a response or error message.

Return value.  0 on success; otherwise, an error code.

Example.  The following example has the same result as running 2 DUMP 1000 in the management client: 

//  [...]
#include <mgmapi_debug.h>
//  [...]
struct ndb_mgm_reply reply;
int args[1];
int stat, arg_count, node_id;

args[0] = 1000;
arg_count = 1;
node_id = 2;

stat = ndb_mgm_dump_state(h, node_id, args, arg_count, &reply);

3.2.6 Functions for Starting & Stopping Nodes

3.2.6.1 ndb_mgm_start()
3.2.6.2 ndb_mgm_stop()
3.2.6.3 ndb_mgm_stop2()
3.2.6.4 ndb_mgm_stop3()
3.2.6.5 ndb_mgm_stop4()
3.2.6.6 ndb_mgm_restart()
3.2.6.7 ndb_mgm_restart2()
3.2.6.8 ndb_mgm_restart3()
3.2.6.9 ndb_mgm_restart4()

Abstract

The MGM API provides several functions which can be used to start, stop, and restart one or more Cluster data nodes. These functions are discussed in this section.

Starting, Stopping, and Restarting Nodes.  You can start, stop, and restart Cluster nodes using the following functions, which are described in more detail in the next few sections.

3.2.6.1 ndb_mgm_start()

Description.  This function can be used to start one or more Cluster nodes. The nodes to be started must have been started with the no-start option (-n), meaning that the data node binary was started and is waiting for a START management command which actually enables the node.

Signature.  

int ndb_mgm_start
    (
      NdbMgmHandle handle,
      int          number,
      const int*   list
    )

Parameters.  ndb_mgm_start() takes 3 parameters:

  • An NdbMgmHandle.

  • A number of nodes to be started. Use 0 to start all of the data nodes in the cluster.

  • A list of the node IDs of the nodes to be started.

Return value.  The number of nodes actually started; in the event of failure, -1 is returned.

3.2.6.2 ndb_mgm_stop()

Description.  This function stops one or more data nodes.

Signature.  

int ndb_mgm_stop
    (
      NdbMgmHandle handle,
      int          number,
      const int*   list
    )

Parameters.  ndb_mgm_stop() takes 3 parameters: Calling this function is equivalent to calling ndb_mgm_stop2(handle, number, list, 0).

  • An NdbMgmHandle.

  • The number of nodes to be stopped. Use 0 to stop all of the data nodes in the cluster.

  • A list of the node IDs of the nodes to be stopped.

Return value.  The number of nodes actually stopped; in the event of failure, -1 is returned.

3.2.6.3 ndb_mgm_stop2()

Description.  Like ndb_mgm_stop(), this function stops one or more data nodes. However, it offers the ability to specify whether or not the nodes shut down gracefully.

Signature.  

int ndb_mgm_stop2
    (
      NdbMgmHandle handle,
      int          number,
      const int*   list,
      int          abort
    )

Parameters.  ndb_mgm_stop2() takes 4 parameters:

  • An NdbMgmHandle.

  • The number of nodes to be stopped. Use 0 to stop all of the data nodes in the cluster.

  • A list of the node IDs of the nodes to be stopped.

  • The value of abort determines how the nodes will be shut down. 1 indicates the nodes will shut down immediately; 0 indicates that the nodes will stop gracefully.

Return value.  The number of nodes actually stopped; in the event of failure, -1 is returned.

3.2.6.4 ndb_mgm_stop3()

Description.  Like ndb_mgm_stop() and ndb_mgm_stop2(), this function stops one or more data nodes. Like ndb_mgm_stop2(), it offers the ability to specify whether the nodes should shut down gracefully. In addition, it provides for a way to check to see whether disconnection is required prior to stopping a node.

Signature.  

int ndb_mgm_stop3
    (
      NdbMgmHandle handle,
      int          number,
      const int*   list,
      int          abort,
      int*         disconnect
    )

Parameters.  ndb_mgm_stop3() takes 5 parameters:

  • An NdbMgmHandle.

  • The number of nodes to be stopped. Use 0 to stop all of the data nodes in the cluster.

  • A list of the node IDs of the nodes to be stopped.

  • The value of abort determines how the nodes will be shut down. 1 indicates the nodes will shut down immediately; 0 indicates that the nodes will stop gracefully.

  • If disconnect returns 1 (true), this means the you must disconnect before you can apply the command to stop. For example, disconnecting is required when stopping the management server to which the handle is connected.

Return value.  The number of nodes actually stopped; in the event of failure, -1 is returned.

3.2.6.5 ndb_mgm_stop4()

Description.  Like the other ndb_mgm_stop*() functions, this function stops one or more data nodes. Like ndb_mgm_stop2(), it offers the ability to specify whether the nodes should shut down gracefully; like ndb_mgm_stop3() it provides for a way to check to see whether disconnection is required prior to stopping a node. In addition, it is possible to force the node to shut down even if this would cause the cluster to become nonviable.

Signature.  

int ndb_mgm_stop4
    (
      NdbMgmHandle handle,
      int          number,
      const int*   list,
      int          abort,
      int          force,
      int*         disconnect
    )

Parameters.  ndb_mgm_stop4() takes 6 parameters:

  • An NdbMgmHandle.

  • The number of nodes to be stopped. Use 0 to stop all of the data nodes in the cluster.

  • A list of the node IDs of the nodes to be stopped.

  • The value of abort determines how the nodes will be shut down. 1 indicates the nodes will shut down immediately; 0 indicates that the nodes will stop gracefully.

  • The value of force determines the action to be taken in the event that the shutdown of a given node would cause an incomplete cluster. 1 causes the node—and the entire cluster—to be shut down in such cases, 0 means the node will not be shut down.

    Setting force equal to 1 also makes it possible to stop a node even while other nodes are starting. (Bug #58451)

  • If disconnect returns 1 (true), this means the you must disconnect before you can apply the command to stop. For example, disconnecting is required when stopping the management server to which the handle is connected.

Return value.  The number of nodes actually stopped; in the event of failure, -1 is returned.

3.2.6.6 ndb_mgm_restart()

Description.  This function can be used to restart one or more Cluster data nodes.

Signature.  

int ndb_mgm_restart
    (
      NdbMgmHandle handle,
      int          number,
      const int*   list
    )

Parameters.  ndb_mgm_restart() takes 3 parameters:

  • An NdbMgmHandle.

  • The number of nodes to be stopped. Use 0 to stop all of the data nodes in the cluster.

  • A list of the node IDs of the nodes to be stopped.

Calling this function is equivalent to calling 

ndb_mgm_restart2(handle, number, list, 0, 0, 0);

See Section 3.2.6.7, “ndb_mgm_restart2()”, for more information.

Return value.  The number of nodes actually restarted; -1 on failure.

3.2.6.7 ndb_mgm_restart2()

Description.  Like ndb_mgm_restart(), this function can be used to restart one or more Cluster data nodes. However, ndb_mgm_restart2() provides additional restart options, including initial restart, waiting start, and immediate (forced) restart.

Signature.  

int ndb_mgm_restart2
    (
      NdbMgmHandle handle,
      int          number,
      const int*   list,
      int          initial
      int          nostart,
      int          abort
    )

Parameters.  ndb_mgm_restart2() takes 6 parameters:

  • An NdbMgmHandle.

  • The number of nodes to be stopped. Use 0 to stop all of the data nodes in the cluster.

  • A list of the node IDs of the nodes to be stopped.

  • If initial is true (1), then each node undergoes an initial restart—that is, its file system is removed.

  • If nostart is true, then the nodes are not actually started, but instead are left ready for a start command.

  • If abort is true, then the nodes are restarted immediately, bypassing any graceful restart.

Return value.  The number of nodes actually restarted; -1 on failure.

3.2.6.8 ndb_mgm_restart3()

Description.  Like ndb_mgm_restart2(), this function can be used to cause an initial restart, waiting restart, and immediate (forced) restart on one or more Cluster data nodes. However, ndb_mgm_restart3() provides the additional options of checking whether disconnection is required prior to the restart.

Signature.  

int ndb_mgm_restart3
    (
      NdbMgmHandle handle,
      int          number,
      const int*   list,
      int          initial
      int          nostart,
      int          abort,
      int*         disconnect
    )

Parameters.  ndb_mgm_restart3() takes 7 parameters:

  • An NdbMgmHandle.

  • The number of nodes to be stopped. Use 0 to stop all of the data nodes in the cluster.

  • A list of the node IDs of the nodes to be stopped.

  • If initial is true (1), then each node undergoes an initial restart—that is, its file system is removed.

  • If nostart is true, then the nodes are not actually started, but instead are left ready for a start command.

  • If abort is true, then the nodes are forced to restart immediately without performing a graceful restart.

  • If disconnect returns 1 (true), this means the you must disconnect before you can apply the command to restart. For example, disconnecting is required when stopping the management server to which the handle is connected.

Return value.  The number of nodes actually restarted; -1 on failure.

3.2.6.9 ndb_mgm_restart4()

Description.  Like the other ndb_mgm_restart*() functions, this function restarts one or more data nodes. Like ndb_mgm_restart2(), it can be used to cause an initial restart, waiting restart, and immediate (forced) restart on one or more NDB Cluster data nodes; like ndb_mgm_stop3() it provides for a way to check to see whether disconnection is required prior to stopping a node. In addition, it is possible to force the node to restart even if this would cause a restart of the cluster.

Signature.  

int ndb_mgm_restart4
    (
      NdbMgmHandle handle,
      int          number,
      const int*   list,
      int          initial
      int          nostart,
      int          abort,
      int          force,
      int*         disconnect
    )

Parameters.  ndb_mgm_restart4() takes 7 parameters:

  • An NdbMgmHandle.

  • The number of nodes to be stopped. Use 0 to stop all of the data nodes in the cluster.

  • A list of the node IDs of the nodes to be stopped.

  • If initial is true (1), then each node undergoes an initial restart—that is, its file system is removed.

  • If nostart is true, then the nodes are not actually started, but instead are left ready for a start command.

  • If abort is true, then the nodes are forced to restart immediately without performing a graceful restart.

  • The value of force determines the action to be taken in the event that the loss of a given node due to restarting would cause an incomplete cluster.

    1 causes the node—and the entire cluster—to be restarted in such cases, 0 means that the node will not be restarted.

    Setting force equal to 1 also makes it possible to restart a node even while other nodes are starting. (Bug #58451)

  • If disconnect returns 1 (true), this means the you must disconnect before you can apply the command to restart. For example, disconnecting is required when stopping the management server to which the handle is connected.

Return value.  The number of nodes actually restarted; -1 on failure.

3.2.7 Cluster Log Functions

3.2.7.1 ndb_mgm_get_clusterlog_severity_filter()
3.2.7.2 ndb_mgm_set_clusterlog_severity_filter()
3.2.7.3 ndb_mgm_get_clusterlog_loglevel()
3.2.7.4 ndb_mgm_set_clusterlog_loglevel()

Abstract

This section covers the functions available in the MGM API for controlling the output of the cluster log.

3.2.7.1 ndb_mgm_get_clusterlog_severity_filter()

Description.  This function is used to retrieve the cluster log severity filter currently in force.

Important

The parameters and return type of this function changed significantly between MySQL 5.1.13 and 5.1.14. The changes are detailed in the Signature, Parameters, and Return Type sections that follow.

These changes were done in order to make this function thread-safe. The pre-5.1.14 version is still supported for backward compatibility, but you should protect it with a mutex if you intend to call it from more than one thread.

Signature.  As of MySQL 5.1.14: 

int ndb_mgm_get_clusterlog_severity_filter
    (
      NdbMgmHandle handle,
      struct ndb_mgm_severity* severity,
      unsigned int size
    )

In MySQL 5.1.13 and earlier, this function took only a single parameter, as shown here: 

const unsigned int* ndb_mgm_get_clusterlog_severity_filter
    (
      NdbMgmHandle handle
    )

Parameters.  This function added two new parameters in MySQL 5.1.14.

  • All MySQL 5.1 releases:

    An NdbMgmHandle.

  • Additionally, in MySQL 5.1.14 and later:

    • A vector severity of seven (NDB_MGM_EVENT_SEVERITY_ALL) elements, each of which is an ndb_mgm_severity structure, where each element contains 1 if a severity indicator is enabled and 0 if not. A severity level is stored at position ndb_mgm_clusterlog_level; for example the error level is stored at position NDB_MGM_EVENT_SEVERITY_ERROR. The first element (position NDB_MGM_EVENT_SEVERITY_ON) in the vector signals whether the cluster log is disabled or enabled.

    • The size of the vector (NDB_MGM_EVENT_SEVERITY_ALL).

Return value.  This function's return type changed beginning with MySQL 5.1.14.

  • MySQL 5.1.13 and earlier: A severity filter, which is a vector containing 7 elements. Each element equals 1 if the corresponding severity indicator is enabled, and 0 if it is not. A severity level is stored at position ndb_mgm_clusterlog_level—for example, the “error” level is stored at position NDB_MGM_EVENT_SEVERITY_ERROR. The first element in the vector (NDB_MGM_EVENT_SEVERITY_ON) signals whether the cluster log is enabled or disabled.

  • MySQL 5.1.14 and later: The number of returned severities, or -1 in the event of an error.

3.2.7.2 ndb_mgm_set_clusterlog_severity_filter()

Description.  This function is used to set a cluster log severity filter.

Signature.  

int ndb_mgm_set_clusterlog_severity_filter
    (
      NdbMgmHandle                handle,
      enum ndb_mgm_event_severity severity,
      int                         enable,
      struct ndb_mgm_reply*       reply
    )

Parameters.  This function takes 4 parameters:

  • A management server handle.

  • A cluster log severity to filter.

  • A flag to enable or disable the filter; 1 enables and 0 disables the filter.

  • A pointer to an ndb_mgm_reply structure for a reply message.

Return value.  The function returns -1 in the event of failure.

3.2.7.3 ndb_mgm_get_clusterlog_loglevel()

Description.  This function, added in MySQL 5.1.16, is used to obtain log category and level information. It replaces the older ndb_mgm_get_loglevel_clusterlog() function, which performed the same purpose, but was not thread-safe. (See later in this section for a brief description of the deprecated version of the function.)

Signature.  

int ndb_mgm_get_clusterlog_loglevel
    (
      NdbMgmHandle handle,
      struct ndb_mgm_loglevel* loglevel,
      unsigned int size
    )

Parameters.  ndb_mgm_get_clusterlog_loglevel() takes the following parameters:

  • A management handle (NdbMgmHandle).

  • A loglevel (log level) vector consisting of twelve elements, each of which is an ndb_mgm_loglevel structure and which represents a log level of the corresponding category.

  • The size of the vector (MGM_LOGLEVELS).

Return value.  This function returns the number of returned loglevels or -1 in the event of an error.

Note

Prior to MySQL 5.1.14, this function was known as ndb_mgm_get_loglevel_clusterlog(), and had the following signature: 

const unsigned int* ndb_mgm_get_loglevel_clusterlog
    (
      NdbMgmHandle handle
    )

This version of the function is now deprecated, but is still available for backward compatibility; however, in new applications, it is recommended that you use ndb_mgm_get_clusterlog_loglevel(), since it is thread-safe, and the older function is not.

3.2.7.4 ndb_mgm_set_clusterlog_loglevel()

Description.  This function is used to set the log category and levels for the cluster log.

Signature.  

int ndb_mgm_set_clusterlog_loglevel
    (
      NdbMgmHandle                handle,
      int                         id,
      enum ndb_mgm_event_category category,
      int                         level,
      struct ndb_mgm_reply*       reply)

Parameters.  This function takes 5 parameters:

Return value.  In the event of an error, this function returns -1.

3.2.8 Backup Functions

3.2.8.1 ndb_mgm_start_backup()
3.2.8.2 ndb_mgm_abort_backup()

Abstract

This section covers the functions provided in the MGM API for starting and stopping backups.

3.2.8.1 ndb_mgm_start_backup()

Description.  This function is used to initiate a backup of an NDB Cluster.

Signature.  

int ndb_mgm_start_backup
    (
      NdbMgmHandle          handle,
      int                   wait,
      unsigned int*         id,
      struct ndb_mgm_reply* reply
    )

Parameters.  This function requires 4 parameters:

  • A management server handle (an NdbMgmHandle).

  • A wait flag, with the following possible values:

    • 0: Do not wait for confirmation of the backup.

    • 1: Wait for the backup to be started.

    • 2: Wait for the backup to be completed.

  • A backup id to be returned by the function.

    Note

    No backup id is returned if wait is set equal to 0.

  • A pointer to an ndb_mgm_reply structure to accommodate a reply.

Return value.  In the event of failure, the function returns -1.

3.2.8.2 ndb_mgm_abort_backup()

Description.  This function is used to stop a Cluster backup.

Signature.  

int ndb_mgm_abort_backup
    (
      NdbMgmHandle          handle,
      unsigned int          id,
      struct ndb_mgm_reply* reply)

Parameters.  This function takes 3 parameters:

  • An NdbMgmHandle.

  • The id of the backup to be aborted.

  • A pointer to an ndb_mgm_reply structure.

Return value.  In case of an error, this function returns -1.

3.2.9 Single-User Mode Functions

3.2.9.1 ndb_mgm_enter_single_user()
3.2.9.2 ndb_mgm_exit_single_user()

Abstract

The MGM API makes it possible for the programmer to put the cluster into single-user mode—and to return it to normal mode again—from within an application. This section covers the functions that are used for these operations.

3.2.9.1 ndb_mgm_enter_single_user()

Description.  This function is used to enter single-user mode on a given node.

Signature.  

int ndb_mgm_enter_single_user
    (
      NdbMgmHandle          handle,
      unsigned int          id,
      struct ndb_mgm_reply* reply
    )

Parameters.  This function takes 3 parameters:

  • An NdbMgmHandle.

  • The id of the node to be used in single-user mode.

  • A pointer to an ndb_mgm_reply structure, used for a reply message.

Return value.  Returns -1 in the event of failure.

3.2.9.2 ndb_mgm_exit_single_user()

Description.  This function is used to exit single-user mode and to return to normal operation.

Signature.  

int ndb_mgm_exit_single_user
    (
      NdbMgmHandle          handle,
      struct ndb_mgm_reply* reply
    )

Parameters.  This function requires 2 arguments:

Return value.  Returns -1 in case of an error.

3.3 MGM API Data Types

3.3.1 The ndb_mgm_node_type Type
3.3.2 The ndb_mgm_node_status Type
3.3.3 The ndb_mgm_error Type
3.3.4 The Ndb_logevent_type Type
3.3.5 The ndb_mgm_event_severity Type
3.3.6 The ndb_logevent_handle_error Type
3.3.7 The ndb_mgm_event_category Type

Abstract

This section discusses the data types defined by the MGM API.

Note

The types described in this section are all defined in the file /storage/ndb/include/mgmapi/mgmapi.h, with the exception of Ndb_logevent_type, ndb_mgm_event_severity, ndb_mgm_logevent_handle_error, and ndb_mgm_event_category, which are defined in /storage/ndb/include/mgmapi/ndb_logevent.h.

3.3.1 The ndb_mgm_node_type Type

Description.  This is used to classify the different types of nodes in an NDB Cluster.

Enumeration values.  Possible values are shown, along with descriptions, in the following table:

ValueDescription
NDB_MGM_NODE_TYPE_UNKNOWNUnknown
NDB_MGM_NODE_TYPE_APIAPI Node (SQL node)
NDB_MGM_NODE_TYPE_NDBData node
NDB_MGM_NODE_TYPE_MGM Management node

3.3.2 The ndb_mgm_node_status Type

Description.  This type describes a Cluster node's status.

Enumeration values.  Possible values are shown, along with descriptions, in the following table:

ValueDescription
NDB_MGM_NODE_STATUS_UNKNOWNThe node's status is not known
NDB_MGM_NODE_STATUS_NO_CONTACTThe node cannot be contacted
NDB_MGM_NODE_STATUS_NOT_STARTEDThe node has not yet executed the startup protocol
NDB_MGM_NODE_STATUS_STARTINGThe node is executing the startup protocol
NDB_MGM_NODE_STATUS_STARTEDThe node is running
NDB_MGM_NODE_STATUS_SHUTTING_DOWNThe node is shutting down
NDB_MGM_NODE_STATUS_RESTARTINGThe node is restarting
NDB_MGM_NODE_STATUS_SINGLEUSERThe node is running in single-user (maintenance) mode
NDB_MGM_NODE_STATUS_RESUMEThe node is in resume mode
NDB_MGM_NODE_STATUS_CONNECTEDThe node is connected

3.3.3 The ndb_mgm_error Type

Description.  The values for this type are the error codes that may be generated by MGM API functions. These may be found in Section 3.5, “MGM API Errors”.

See also Section 3.2.2.1, “ndb_mgm_get_latest_error()”, for more information.

3.3.4 The Ndb_logevent_type Type

Description.  These are the types of log events available in the MGM API, grouped by event category. (See Section 3.3.7, “The ndb_mgm_event_category Type”.)

Enumeration values.  Possible values are shown, along with descriptions, in the following table:

CategoryTypeDescription
NDB_MGM_EVENT_CATEGORY_CONNECTION(Connection events)
 NDB_LE_ConnectedThe node has connected
 NDB_LE_DisconnectedThe node was disconnected
 NDB_LE_CommunicationClosedCommunication with the node has been closed
 NDB_LE_CommunicationOpenedCommunication with the node has been started
 NDB_LE_ConnectedApiVersionThe API version used by an API node; in the case of a MySQL server (SQL node), this is the same as displayed by SELECT VERSION()
NDB_MGM_EVENT_CATEGORY_CHECKPOINT(Checkpoint events)
 NDB_LE_GlobalCheckpointStartedA global checkpoint has been started
 NDB_LE_GlobalCheckpointCompletedA global checkpoint has been completed
 NDB_LE_LocalCheckpointStartedThe node has begun a local checkpoint
 NDB_LE_LocalCheckpointCompletedThe node has completed a local checkpoint
 NDB_LE_LCPStoppedInCalcKeepGciThe lcoal checkpoint was aborted, but the last global checkpoint was preserved
 NDB_LE_LCPFragmentCompletedCopying of a table fragment was completed
NDB_MGM_EVENT_CATEGORY_STARTUP(Startup events)
 NDB_LE_NDBStartStartedThe node has begun to start
 NDB_LE_NDBStartCompletedThe node has completed the startup process
 NDB_LE_STTORRYRecievedThe node received an STTORRY signal, indicating that the reading of configuration data is underway; see Configuration Read Phase (STTOR Phase -1), and STTOR Phase 0, for more information
 NDB_LE_StartPhaseCompletedA node start phase has been completed
 NDB_LE_CM_REGCONFThe node has received a CM_REGCONF signal; see STTOR Phase 1, for more information
 NDB_LE_CM_REGREFThe node has received a CM_REGREF signal; see STTOR Phase 1, for more information
 NDB_LE_FIND_NEIGHBOURSThe node has discovered its neighboring nodes in the cluster
 NDB_LE_NDBStopStartedThe node is beginning to shut down
 NDB_LE_NDBStopCompleted 
 NDB_LE_NDBStopForcedThe node is being forced to shut down (usually indicates a severe problem in the cluster)
 NDB_LE_NDBStopAbortedThe started to shut down, but was forced to continue running; this happens, for example, when a STOP command was issued in the management client for a node such that the cluster would no longer be able to keep all data available if the node were shut down
 NDB_LE_StartREDOLogRedo logging has been started
 NDB_LE_StartLogLogging has started
 NDB_LE_UNDORecordsExecutedThe node has read and executed all records from the redo log
 NDB_LE_StartReportThe node is issuing a start report
NDB_MGM_EVENT_CATEGORY_NODE_RESTART(Restart events)
 NDB_LE_NR_CopyDictThe node is copying the data dictionary
 NDB_LE_NR_CopyDistrThe node is copying data distribution information
 NDB_LE_NR_CopyFragsStartedThe node is copying table fragments
 NDB_LE_NR_CopyFragDoneThe node has completed copying a table fragment
 NDB_LE_NR_CopyFragsCompletedThe node has completed copying all necessary table fragments
NDB_MGM_EVENT_CATEGORY_NODE_RESTART(Node failure and arbitration)
 NDB_LE_NodeFailCompletedAll (remaining) nodes has been notified of the failure of a data node
 NDB_LE_NODE_FAILREPA data node has failed
 NDB_LE_ArbitStateThis event is used to report on the current state of arbitration in the cluster
 NDB_LE_ArbitResultThis event is used to report on the outcome of node arbitration
 NDB_LE_GCP_TakeoverStartedThe node is attempting to become the master node (to assume responsibility for GCPs)
 NDB_LE_GCP_TakeoverCompletedThe node has become the master (and assumed responsibility for GCPs)
 NDB_LE_LCP_TakeoverStartedThe node is attempting to become the master node (to assume responsibility for LCPs)
 NDB_LE_LCP_TakeoverCompletedThe node has become the master (and assumed responsibility for LCPs)
NDB_MGM_EVENT_CATEGORY_STATISTIC(Statistics events)
 NDB_LE_TransReportCountersThis indicates a report of transaction activity, which is given approximately once every 10 seconds
 NDB_LE_OperationReportCountersIndicates a report on the number of operations performed by this node (also provided approximately once every 10 seconds)
 NDB_LE_TableCreatedA new table has been created
 NDB_LE_UndoLogBlockedUndo logging is blocked because the log buffer is close to overflowing
 NDB_LE_JobStatistic 
 NDB_LE_SendBytesStatisticIndicates a report of the average number of bytes transmitted per send operation by this node
 NDB_LE_ReceiveBytesStatisticIndicates a report of the average number of bytes received per send operation to this node
 NDB_LE_MemoryUsageA DUMP 1000 command has been issued to this node, and it is reporting its memory usage in turn
NDB_MGM_EVENT_CATEGORY_ERROR(Errors and warnings)
 NDB_LE_TransporterErrorA transporter error has occurred; see NDB Transporter Errors, for transporter error codes and messages
 NDB_LE_TransporterWarningA potential problem is occurring in the transporter; see NDB Transporter Errors, for transporter error codes and messages
 NDB_LE_MissedHeartbeatIndicates a data node has missed a hreatbeat expected from another data node
 NDB_LE_DeadDueToHeartbeatA data node has missed at least 3 heartbeats in succssion from another data node, and is reporting that it can no longer communicate with that data node
 NDB_LE_WarningEventIndicates a warning message
NDB_MGM_EVENT_CATEGORY_INFO(Information events)
 NDB_LE_SentHeartbeatA node heartbeat has been sent
 NDB_LE_CreateLogBytes 
 NDB_LE_InfoEventIndicates an informational message
[Single-User Mode]NDB_LE_SingleUserThe cluster has entered or exited single user mode
 NDB_LE_EventBufferStatusThis type of event indicates potentially excessive usage of the event buffer
 NDB_LE_EventBufferStatus2Provides improved reporting of event buffer status; added in NDB 7.5.1
NDB_MGM_EVENT_CATEGORY_BACKUP(Backups)
 NDB_LE_BackupStartedA backup has been started
 NDB_LE_BackupFailedToStartA backup has failed to start
 NDB_LE_BackupCompletedA backup has been completed successfully
 NDB_LE_BackupAbortedA backup in progress was terminated by the user

3.3.5 The ndb_mgm_event_severity Type

Description.  These are the log event severities used to filter the cluster log by ndb_mgm_set_clusterlog_severity_filter(), and to filter listening to events by ndb_mgm_listen_event().

Enumeration values.  Possible values are shown, along with descriptions, in the following table:

ValueDescription
NDB_MGM_ILLEGAL_EVENT_SEVERITYInvalid event severity specified
NDB_MGM_EVENT_SEVERITY_ONCluster logging is enabled
NDB_MGM_EVENT_SEVERITY_DEBUGUsed for NDB Cluster development only
NDB_MGM_EVENT_SEVERITY_INFOInformational messages
NDB_MGM_EVENT_SEVERITY_WARNINGConditions that are not errors as such, but that might require special handling
NDB_MGM_EVENT_SEVERITY_ERRORNonfatal error conditions that should be corrected
NDB_MGM_EVENT_SEVERITY_CRITICALCritical conditions such as device errors or out of memory errors
NDB_MGM_EVENT_SEVERITY_ALERTConditions that require immediate attention, such as corruption of the cluster
NDB_MGM_EVENT_SEVERITY_ALLAll severity levels

See Section 3.2.7.2, “ndb_mgm_set_clusterlog_severity_filter()”, and Section 3.2.1.1, “ndb_mgm_listen_event()”, for information on how this type is used by those functions.

3.3.6 The ndb_logevent_handle_error Type

Description.  This type is used to describe log event errors.

Enumeration values.  Possible values are shown, along with descriptions, in the following table:

ValueDescription
NDB_LEH_NO_ERRORNo error
NDB_LEH_READ_ERRORRead error
NDB_LEH_MISSING_EVENT_SPECIFIERInvalid, incomplete, or missing log event specification
NDB_LEH_UNKNOWN_EVENT_TYPEUnknown log event type
NDB_LEH_UNKNOWN_EVENT_VARIABLEUnknown log event variable
NDB_LEH_INTERNAL_ERRORInternal error
NDB_LEH_CONNECTION_ERRORConnection error, or lost connection with management server

NDB_LEH_CONNECTION_ERROR was added in NDB 7.4.13 and NDB 7.5.4. (BUG #19474782)

3.3.7 The ndb_mgm_event_category Type

Description.  These are the log event categories referenced in Section 3.3.4, “The Ndb_logevent_type Type”. They are also used by the MGM API functions ndb_mgm_set_clusterlog_loglevel() and ndb_mgm_listen_event().

Enumeration values.  Possible values are shown, along with descriptions, in the following table:

ValueDescription
NDB_MGM_ILLEGAL_EVENT_CATEGORYInvalid log event category
NDB_MGM_EVENT_CATEGORY_STARTUPLog events occurring during startup
NDB_MGM_EVENT_CATEGORY_SHUTDOWNLog events occurring during shutdown
NDB_MGM_EVENT_CATEGORY_STATISTICStatistics log events
NDB_MGM_EVENT_CATEGORY_CHECKPOINTLog events related to checkpoints
NDB_MGM_EVENT_CATEGORY_NODE_RESTARTLog events occurring during node restart
NDB_MGM_EVENT_CATEGORY_CONNECTIONLog events relating to connections between cluster nodes
NDB_MGM_EVENT_CATEGORY_BACKUPLog events relating to backups
NDB_MGM_EVENT_CATEGORY_CONGESTIONLog events relating to congestion
NDB_MGM_EVENT_CATEGORY_INFOUncategorised log events (severity level INFO)
NDB_MGM_EVENT_CATEGORY_ERRORUncategorised log events (severity level WARNING, ERROR, CRITICAL, or ALERT)

See Section 3.2.7.4, “ndb_mgm_set_clusterlog_loglevel()”, and Section 3.2.1.1, “ndb_mgm_listen_event()”, for more information.

3.4 MGM API Structures

3.4.1 The ndb_logevent Structure
3.4.2 The ndb_mgm_node_state Structure
3.4.3 The ndb_mgm_cluster_state Structure
3.4.4 The ndb_mgm_reply Structure

Abstract

This section covers the programming structures available in the MGM API.

3.4.1 The ndb_logevent Structure

Description.  This structure models a Cluster log event, and is used for storing and retrieving log event information.

Definition.  ndb_logevent has 8 members, the first 7 of which are shown in the following list:

  • void* handle: An NdbLogEventHandle, set by ndb_logevent_get_next(). This handle is used only for purposes of comparison.

  • type: Tells which type of event (Ndb_logevent_type) this is.

  • unsigned time: The time at which the log event was registered with the management server.

  • category: The log event category (ndb_mgm_event_category).

  • severity: The log event severity (ndb_mgm_event_severity).

  • unsigned level: The log event level. This is a value in the range of 0 to 15, inclusive.

  • unsigned source_nodeid: The node ID of the node that reported this event.

The 8th member of this structure contains data specific to the log event, and is dependent on its type. It is defined as the union of a number of data structures, each corresponding to a log event type. Which structure to use is determined by the value of type, and is shown in the following table:

Ndb_logevent_type ValueStructure
NDB_LE_ConnectedConnected: 
unsigned node
NDB_LE_DisconnectedDisconnected: 
unsigned node
NDB_LE_CommunicationClosedCommunicationClosed: 
unsigned node
NDB_LE_CommunicationOpenedCommunicationOpened: 
unsigned node
NDB_LE_ConnectedApiVersionConnectedApiVersion: 
unsigned node
unsigned version
NDB_LE_GlobalCheckpointStartedGlobalCheckpointStarted: 
unsigned gci
NDB_LE_GlobalCheckpointCompletedGlobalCheckpointCompleted: 
unsigned gci
NDB_LE_LocalCheckpointStartedLocalCheckpointStarted: 
unsigned lci
unsigned keep_gci
unsigned restore_gci
NDB_LE_LocalCheckpointCompletedLocalCheckpointCompleted: 
unsigned lci
NDB_LE_LCPStoppedInCalcKeepGciLCPStoppedInCalcKeepGci: 
unsigned data
NDB_LE_LCPFragmentCompletedLCPFragmentCompleted: 
unsigned node
unsigned table_id
unsigned fragment_id
NDB_LE_UndoLogBlockedUndoLogBlocked: 
unsigned acc_count
unsigned tup_count
NDB_LE_NDBStartStartedNDBStartStarted: 
unsigned version
NDB_LE_NDBStartCompletedNDBStartCompleted: 
unsigned version
NDB_LE_STTORRYRecievedSTTORRYRecieved: 
[NONE]
NDB_LE_StartPhaseCompletedStartPhaseCompleted: 
unsigned phase
unsigned starttype
NDB_LE_CM_REGCONFCM_REGCONF: 
unsigned own_id
unsigned president_id
unsigned dynamic_id
NDB_LE_CM_REGREFCM_REGREF: 
unsigned own_id
unsigned other_id
unsigned cause
NDB_LE_FIND_NEIGHBOURSFIND_NEIGHBOURS: 
unsigned own_id
unsigned left_id
unsigned right_id
unsigned dynamic_id
NDB_LE_NDBStopStartedNDBStopStarted: 
unsigned stoptype
NDB_LE_NDBStopCompletedNDBStopCompleted: 
unsigned action
unsigned signum
NDB_LE_NDBStopForcedNDBStopForced: 
unsigned action
unsigned signum
unsigned error
unsigned sphase
unsigned extra
NDB_LE_NDBStopAbortedNDBStopAborted: 
[NONE]
NDB_LE_StartREDOLogStartREDOLog: 
unsigned node
unsigned keep_gci
unsigned completed_gci
unsigned restorable_gci
NDB_LE_StartLogStartLog: 
unsigned log_part
unsigned start_mb
unsigned stop_mb
unsigned gci
NDB_LE_UNDORecordsExecutedUNDORecordsExecuted: 
unsigned block
unsigned data1
unsigned data2
unsigned data3
unsigned data4
unsigned data5
unsigned data6
unsigned data7
unsigned data8
unsigned data9
unsigned data10
NDB_LE_NR_CopyDictNR_CopyDict: 
[NONE]
NDB_LE_NR_CopyDistrNR_CopyDistr: 
[NONE]
NDB_LE_NR_CopyFragsStartedNR_CopyFragsStarted: 
unsigned dest_node
NDB_LE_NR_CopyFragDoneNR_CopyFragDone: 
unsigned dest_node
unsigned table_id
unsigned fragment_id
NDB_LE_NR_CopyFragsCompletedNR_CopyFragsCompleted: 
unsigned dest_node
NDB_LE_NodeFailCompletedNodeFailCompleted: 
unsigned block
unsigned failed_node
unsigned completing_node
(For block and completing_node, 0 is interpreted as “all”.)
NDB_LE_NODE_FAILREPNODE_FAILREP: 
unsigned failed_node
unsigned failure_state
NDB_LE_ArbitStateArbitState: 
unsigned code
unsigned arbit_node
unsigned ticket_0
unsigned ticket_1
NDB_LE_ArbitResultArbitResult: 
unsigned code
unsigned arbit_node
unsigned ticket_0
unsigned ticket_1
NDB_LE_GCP_TakeoverStartedGCP_TakeoverStarted: 
[NONE]
NDB_LE_GCP_TakeoverCompletedGCP_TakeoverCompleted: 
[NONE]
NDB_LE_LCP_TakeoverStartedLCP_TakeoverStarted: 
[NONE]
NDB_LE_TransReportCountersTransReportCounters: 
unsigned trans_count
unsigned commit_count
unsigned read_count
unsigned simple_read_count
unsigned write_count
unsigned attrinfo_count
unsigned conc_op_count
unsigned abort_count
unsigned scan_count
unsigned range_scan_count
NDB_LE_OperationReportCountersOperationReportCounters: 
unsigned ops
NDB_LE_TableCreatedTableCreated: 
unsigned table_id
NDB_LE_JobStatisticJobStatistic: 
unsigned mean_loop_count
NDB_LE_SendBytesStatisticSendBytesStatistic: 
unsigned to_node
unsigned mean_sent_bytes
NDB_LE_ReceiveBytesStatisticReceiveBytesStatistic: 
unsigned from_node
unsigned mean_received_bytes
NDB_LE_MemoryUsageMemoryUsage: 
int      gth
unsigned page_size_kb
unsigned pages_used
unsigned pages_total
unsigned block
NDB_LE_TransporterErrorTransporterError: 
unsigned to_node
unsigned code
NDB_LE_TransporterWarningTransporterWarning: 
unsigned to_node
unsigned code
NDB_LE_MissedHeartbeatMissedHeartbeat: 
unsigned node
unsigned count
NDB_LE_DeadDueToHeartbeatDeadDueToHeartbeat: 
unsigned node
NDB_LE_WarningEventWarningEvent: 
[NOT YET IMPLEMENTED]
NDB_LE_SentHeartbeatSentHeartbeat: 
unsigned node
NDB_LE_CreateLogBytesCreateLogBytes: 
unsigned node
NDB_LE_InfoEventInfoEvent: 
[NOT YET IMPLEMENTED]
NDB_LE_EventBufferStatus (NDB 7.5.0 and earlier)EventBufferStatus:: 
unsigned usage
unsigned alloc
unsigned max
unsigned apply_gci_l
unsigned apply_gci_h
unsigned latest_gci_l
unsigned latest_gci_h
NDB_LE_EventBufferStatus2 (NDB 7.5.1 and later)EventBufferStatus2: 
unsigned usage
unsigned alloc
unsigned max
unsigned latest_consumed_epoch_l
unsigned latest_consumed_epoch_h
unsigned latest_buffered_epoch_l
unsigned latest_buffered_epoch_h
unsigned ndb_reference
unsigned report_reason
report_reason is one of NO_REPORT, COMPLETELY_BUFFERING, PARTIALLY_DISCARDING, COMPLETELY_DISCARDING, PARTIALLY_BUFFERING, BUFFERED_EPOCHS_OVER_THRESHOLD, ENOUGH_FREE_EVENTBUFFER, or LOW_FREE_EVENTBUFFER; see Event Buffer Reporting in the Cluster Log, for descriptions of these values
NDB_LE_BackupStartedBackupStarted: 
unsigned starting_node
unsigned backup_id
NDB_LE_BackupFailedToStartBackupFailedToStart: 
unsigned starting_node
unsigned error
NDB_LE_BackupCompletedBackupCompleted: 
unsigned starting_node
unsigned backup_id
unsigned start_gci
unsigned stop_gci
unsigned n_records 
unsigned n_log_records
unsigned n_bytes
unsigned n_log_bytes
NDB_LE_BackupAbortedBackupAborted: 
unsigned starting_node
unsigned backup_id
unsigned error
NDB_LE_SingleUserSingleUser: 
unsigned type
unsigned node_id
NDB_LE_StartReportStartReport: 
unsigned report_type
unsigned remaining_time
unsigned bitmask_size
unsigned bitmask_data[1]

3.4.2 The ndb_mgm_node_state Structure

Description.  Provides information on the status of a Cluster node.

Definition.  This structure contains the following members:

  • int node_id: The cluster node's node ID.

  • enum ndb_mgm_node_type node_type: The node type.

    See Section 3.3.1, “The ndb_mgm_node_type Type”, for permitted values.

  • enum ndb_mgm_node_status node_status: The node's status.

    See Section 3.3.2, “The ndb_mgm_node_status Type”, for permitted values.

  • int start_phase: The start phase.

    This is valid only if the node_type is NDB_MGM_NODE_TYPE_NDB and the node_status is NDB_MGM_NODE_STATUS_STARTING.

  • int dynamic_id: The ID for heartbeats and master takeover.

    Valid only for data (ndbd) nodes.

  • int node_group: The node group to which the node belongs.

    Valid only for data (ndbd) nodes.

  • int version: Internal version number.

  • int connect_count: The number of times this node has connected to or disconnected from the management server.

  • char connect_address[]: The IP address of this node as seen by the other nodes in the cluster.

3.4.3 The ndb_mgm_cluster_state Structure

Description.  Provides information on the status of all Cluster nodes. This structure is returned by ndb_mgm_get_status().

Definition.  This structure has the following two members;

  • int no_of_nodes: The number of elements in the node_states array.

  • struct ndb_mgm_node_state node_states[]: An array containing the states of the nodes.

    Each element of this array is an ndb_mgm_node_state structure.

See Section 3.2.5.1, “ndb_mgm_get_status()”.

3.4.4 The ndb_mgm_reply Structure

Description.  Contains response information, consisting of a response code and a corresponding message, from the management server.

Definition.  This structure contains two members, as shown here:

  • int return_code: For a successful operation, this value is 0; otherwise, it contains an error code.

    For error codes, see Section 3.3.3, “The ndb_mgm_error Type”.

  • char message[256]: contains the text of the response or error message.

See Section 3.2.2.1, “ndb_mgm_get_latest_error()”, and Section 3.2.2.2, “ndb_mgm_get_latest_error_msg()”.

3.5 MGM API Errors

3.5.1 Request Errors
3.5.2 Node ID Allocation Errors
3.5.3 Service Errors
3.5.4 Backup Errors
3.5.5 Single User Mode Errors
3.5.6 General Usage Errors

The following sections list the values of MGM errors by type. There are six types of MGM errors:

  1. request errors

  2. node ID allocation errors

  3. service errors

  4. backup errors

  5. single user mode errors

  6. general usage errors

There is only one general usage error.

3.5.1 Request Errors

These are errors generated by failures to connect to a management server.

ValueDescription
NDB_MGM_ILLEGAL_CONNECT_STRINGInvalid connection string
NDB_MGM_ILLEGAL_SERVER_HANDLEInvalid management server handle
NDB_MGM_ILLEGAL_SERVER_REPLYInvalid response from management server
NDB_MGM_ILLEGAL_NUMBER_OF_NODESInvalid number of nodes
NDB_MGM_ILLEGAL_NODE_STATUSInvalid node status
NDB_MGM_OUT_OF_MEMORYMemory allocation error
NDB_MGM_SERVER_NOT_CONNECTEDManagement server not connected
NDB_MGM_COULD_NOT_CONNECT_TO_SOCKETNot able to connect to socket

3.5.2 Node ID Allocation Errors

These errors result from a failure to assign a node ID to a cluster node.

ValueDescription
NDB_MGM_ALLOCID_ERRORGeneric error; may be possible to retry and recover
NDB_MGM_ALLOCID_CONFIG_MISMATCHNon-recoverable generic error

3.5.3 Service Errors

These errors result from the failure of a node or cluster to start, shut down, or restart.

ValueDescription
NDB_MGM_START_FAILEDStartup failure
NDB_MGM_STOP_FAILEDShutdown failure
NDB_MGM_RESTART_FAILEDRestart failure

3.5.4 Backup Errors

These are errors which result from problems with initiating or aborting backups.

ValueDescription
NDB_MGM_COULD_NOT_START_BACKUPUnable to initiate backup
NDB_MGM_COULD_NOT_ABORT_BACKUPUnable to abort backup

3.5.5 Single User Mode Errors

These errors result from failures to enter or exit single user mode.

ValueDescription
NDB_MGM_COULD_NOT_ENTER_SINGLE_USER_MODEUnable to enter single-user mode
NDB_MGM_COULD_NOT_EXIT_SINGLE_USER_MODEUnable to exit single-user mode

3.5.6 General Usage Errors

This is a general error type for errors which are otherwise not classifiable.

ValueDescription
NDB_MGM_USAGE_ERRORGeneral usage error

3.6 MGM API Examples

3.6.1 Basic MGM API Event Logging Example
3.6.2 MGM API Event Handling with Multiple Clusters

This section contains MGM API coding examples.

3.6.1 Basic MGM API Event Logging Example

This example shows the basics of handling event logging using the MGM API.

The source code for this program may be found in the NDB Cluster source tree, in the file storage/ndb/ndbapi-examples/mgmapi_logevent/main.cpp. 

#include <mysql.h>
#include <ndbapi/NdbApi.hpp>
#include <mgmapi.h>
#include <stdio.h>
#include <stdlib.h>

/*
 * export LD_LIBRARY_PATH=../../../../libmysql_r/.libs:../../src/.libs
 */

#define MGMERROR(h) \
{ \
  fprintf(stderr, "code: %d msg: %s\n", \
          ndb_mgm_get_latest_error(h), \
          ndb_mgm_get_latest_error_msg(h)); \
  exit(-1); \
}

#define LOGEVENTERROR(h) \
{ \
  fprintf(stderr, "code: %d msg: %s\n", \
          ndb_logevent_get_latest_error(h), \
          ndb_logevent_get_latest_error_msg(h)); \
  exit(-1); \
}

#define make_uint64(a,b) (((Uint64)(a)) + (((Uint64)(b)) << 32))

int main(int argc, char** argv)
{
  NdbMgmHandle h;
  NdbLogEventHandle le;
  int filter[] = { 15, NDB_MGM_EVENT_CATEGORY_BACKUP,
		   15, NDB_MGM_EVENT_CATEGORY_CONNECTION,
		   15, NDB_MGM_EVENT_CATEGORY_NODE_RESTART,
		   15, NDB_MGM_EVENT_CATEGORY_STARTUP,
		   15, NDB_MGM_EVENT_CATEGORY_ERROR,
		   0 };
  struct ndb_logevent event;

  if (argc < 2)
  {
    printf("Arguments are <connect_string cluster> [<iterations>].\n");
    exit(-1);
  }
  const char *connectstring = argv[1];
  int iterations = -1;
  if (argc > 2)
    iterations = atoi(argv[2]);
  ndb_init();

  h= ndb_mgm_create_handle();
  if ( h == 0)
  {
    printf("Unable to create handle\n");
    exit(-1);
  }
  if (ndb_mgm_set_connectstring(h, connectstring) == -1)
  {
    printf("Unable to set connection string\n");
    exit(-1);
  }
  if (ndb_mgm_connect(h,0,0,0)) MGMERROR(h);

  le= ndb_mgm_create_logevent_handle(h, filter);
  if ( le == 0 )  MGMERROR(h);

  while (iterations-- != 0)
  {
    int timeout= 1000;
    int r= ndb_logevent_get_next(le,&event,timeout);
    if (r == 0)
      printf("No event within %d milliseconds\n", timeout);
    else if (r < 0)
      LOGEVENTERROR(le)
    else
    {
      switch (event.type) {
      case NDB_LE_BackupStarted:
	printf("Node %d: BackupStarted\n", event.source_nodeid);
	printf("  Starting node ID: %d\n", event.BackupStarted.starting_node);
	printf("  Backup ID: %d\n", event.BackupStarted.backup_id);
	break;
      case NDB_LE_BackupStatus:
	printf("Node %d: BackupStatus\n", event.source_nodeid);
	printf("  Starting node ID: %d\n", event.BackupStarted.starting_node);
	printf("  Backup ID: %d\n", event.BackupStarted.backup_id);
	printf("  Data written: %llu bytes (%llu records)\n",
               make_uint64(event.BackupStatus.n_bytes_lo,
                           event.BackupStatus.n_bytes_hi),
               make_uint64(event.BackupStatus.n_records_lo,
                           event.BackupStatus.n_records_hi));
	printf("  Log written: %llu bytes (%llu records)\n",
               make_uint64(event.BackupStatus.n_log_bytes_lo,
                           event.BackupStatus.n_log_bytes_hi),
               make_uint64(event.BackupStatus.n_log_records_lo,
                           event.BackupStatus.n_log_records_hi));
	break;
      case NDB_LE_BackupCompleted:
	printf("Node %d: BackupCompleted\n", event.source_nodeid);
	printf("  Backup ID: %d\n", event.BackupStarted.backup_id);
	printf("  Data written: %llu bytes (%llu records)\n",
               make_uint64(event.BackupCompleted.n_bytes,
                           event.BackupCompleted.n_bytes_hi),
               make_uint64(event.BackupCompleted.n_records,
                           event.BackupCompleted.n_records_hi));
	printf("  Log written: %llu bytes (%llu records)\n",
               make_uint64(event.BackupCompleted.n_log_bytes,
                           event.BackupCompleted.n_log_bytes_hi),
               make_uint64(event.BackupCompleted.n_log_records,
                           event.BackupCompleted.n_log_records_hi));
	break;
      case NDB_LE_BackupAborted:
	printf("Node %d: BackupAborted\n", event.source_nodeid);
	break;
      case NDB_LE_BackupFailedToStart:
	printf("Node %d: BackupFailedToStart\n", event.source_nodeid);
	break;

      case NDB_LE_NodeFailCompleted:
	printf("Node %d: NodeFailCompleted\n", event.source_nodeid);
	break;
      case NDB_LE_ArbitResult:
	printf("Node %d: ArbitResult\n", event.source_nodeid);
	printf("  code %d, arbit_node %d\n",
	       event.ArbitResult.code & 0xffff,
	       event.ArbitResult.arbit_node);
	break;
      case NDB_LE_DeadDueToHeartbeat:
	printf("Node %d: DeadDueToHeartbeat\n", event.source_nodeid);
	printf("  node %d\n", event.DeadDueToHeartbeat.node);
	break;

      case NDB_LE_Connected:
	printf("Node %d: Connected\n", event.source_nodeid);
	printf("  node %d\n", event.Connected.node);
	break;
      case NDB_LE_Disconnected:
	printf("Node %d: Disconnected\n", event.source_nodeid);
	printf("  node %d\n", event.Disconnected.node);
	break;
      case NDB_LE_NDBStartCompleted:
	printf("Node %d: StartCompleted\n", event.source_nodeid);
	printf("  version %d.%d.%d\n",
	       event.NDBStartCompleted.version >> 16 & 0xff,
	       event.NDBStartCompleted.version >> 8 & 0xff,
	       event.NDBStartCompleted.version >> 0 & 0xff);
	break;
      case NDB_LE_ArbitState:
	printf("Node %d: ArbitState\n", event.source_nodeid);
	printf("  code %d, arbit_node %d\n",
	       event.ArbitState.code & 0xffff,
	       event.ArbitResult.arbit_node);
	break;

      default:
	break;
      }
    }
  }
    
  ndb_mgm_destroy_logevent_handle(&le);
  ndb_mgm_destroy_handle(&h);
  ndb_end(0);
  return 0;
}

3.6.2 MGM API Event Handling with Multiple Clusters

This example shown in this section illustrates the handling of log events using the MGM API on multiple clusters in a single application.

The source code for this program may be found in the NDB Cluster source tree, in the file storage/ndb/ndbapi-examples/mgmapi_logevent2/main.cpp.

Note

This file was previously named mgmapi_logevent2.cpp. 

#include <mysql.h>
#include <ndbapi/NdbApi.hpp>
#include <mgmapi.h>
#include <stdio.h>
#include <stdlib.h>

/*
 * export LD_LIBRARY_PATH=../../../libmysql_r/.libs:../../../ndb/src/.libs
 */

#define MGMERROR(h) \
{ \
  fprintf(stderr, "code: %d msg: %s\n", \
          ndb_mgm_get_latest_error(h), \
          ndb_mgm_get_latest_error_msg(h)); \
  exit(-1); \
}

#define LOGEVENTERROR(h) \
{ \
  fprintf(stderr, "code: %d msg: %s\n", \
          ndb_logevent_get_latest_error(h), \
          ndb_logevent_get_latest_error_msg(h)); \
  exit(-1); \
}

int main(int argc, char** argv)
{
  NdbMgmHandle h1,h2;
  NdbLogEventHandle le1,le2;
  int filter[] = { 15, NDB_MGM_EVENT_CATEGORY_BACKUP,
		   15, NDB_MGM_EVENT_CATEGORY_CONNECTION,
		   15, NDB_MGM_EVENT_CATEGORY_NODE_RESTART,
		   15, NDB_MGM_EVENT_CATEGORY_STARTUP,
		   15, NDB_MGM_EVENT_CATEGORY_ERROR,
		   0 };
  struct ndb_logevent event1, event2;

  if (argc < 3)
  {
    printf("Arguments are <connect_string cluster 1>",
           "<connect_string cluster 2> [<iterations>].\n");
    exit(-1);
  }
  const char *connectstring1 = argv[1];
  const char *connectstring2 = argv[2];
  int iterations = -1;
  if (argc > 3)
    iterations = atoi(argv[3]);
  ndb_init();

  h1= ndb_mgm_create_handle();
  h2= ndb_mgm_create_handle();
  if ( h1 == 0 || h2 == 0 )
  {
    printf("Unable to create handle\n");
    exit(-1);
  }
  if (ndb_mgm_set_connectstring(h1, connectstring1) == -1 ||
      ndb_mgm_set_connectstring(h2, connectstring1))
  {
    printf("Unable to set connection string\n");
    exit(-1);
  }
  if (ndb_mgm_connect(h1,0,0,0)) MGMERROR(h1);
  if (ndb_mgm_connect(h2,0,0,0)) MGMERROR(h2);

  if ((le1= ndb_mgm_create_logevent_handle(h1, filter)) == 0) MGMERROR(h1);
  if ((le2= ndb_mgm_create_logevent_handle(h1, filter)) == 0) MGMERROR(h2);

  while (iterations-- != 0)
  {
    int timeout= 1000;
    int r1= ndb_logevent_get_next(le1,&event1,timeout);
    if (r1 == 0)
      printf("No event within %d milliseconds\n", timeout);
    else if (r1 < 0)
      LOGEVENTERROR(le1)
    else
    {
      switch (event1.type) {
      case NDB_LE_BackupStarted:
	printf("Node %d: BackupStarted\n", event1.source_nodeid);
	printf("  Starting node ID: %d\n", event1.BackupStarted.starting_node);
	printf("  Backup ID: %d\n", event1.BackupStarted.backup_id);
	break;
      case NDB_LE_BackupCompleted:
	printf("Node %d: BackupCompleted\n", event1.source_nodeid);
	printf("  Backup ID: %d\n", event1.BackupStarted.backup_id);
	break;
      case NDB_LE_BackupAborted:
	printf("Node %d: BackupAborted\n", event1.source_nodeid);
	break;
      case NDB_LE_BackupFailedToStart:
	printf("Node %d: BackupFailedToStart\n", event1.source_nodeid);
	break;

      case NDB_LE_NodeFailCompleted:
	printf("Node %d: NodeFailCompleted\n", event1.source_nodeid);
	break;
      case NDB_LE_ArbitResult:
	printf("Node %d: ArbitResult\n", event1.source_nodeid);
	printf("  code %d, arbit_node %d\n",
	       event1.ArbitResult.code & 0xffff,
	       event1.ArbitResult.arbit_node);
	break;
      case NDB_LE_DeadDueToHeartbeat:
	printf("Node %d: DeadDueToHeartbeat\n", event1.source_nodeid);
	printf("  node %d\n", event1.DeadDueToHeartbeat.node);
	break;

      case NDB_LE_Connected:
	printf("Node %d: Connected\n", event1.source_nodeid);
	printf("  node %d\n", event1.Connected.node);
	break;
      case NDB_LE_Disconnected:
	printf("Node %d: Disconnected\n", event1.source_nodeid);
	printf("  node %d\n", event1.Disconnected.node);
	break;
      case NDB_LE_NDBStartCompleted:
	printf("Node %d: StartCompleted\n", event1.source_nodeid);
	printf("  version %d.%d.%d\n",
	       event1.NDBStartCompleted.version >> 16 & 0xff,
	       event1.NDBStartCompleted.version >> 8 & 0xff,
	       event1.NDBStartCompleted.version >> 0 & 0xff);
	break;
      case NDB_LE_ArbitState:
	printf("Node %d: ArbitState\n", event1.source_nodeid);
	printf("  code %d, arbit_node %d\n",
	       event1.ArbitState.code & 0xffff,
	       event1.ArbitResult.arbit_node);
	break;

      default:
	break;
      }
    }

    int r2= ndb_logevent_get_next(le1,&event2,timeout);
    if (r2 == 0)
      printf("No event within %d milliseconds\n", timeout);
    else if (r2 < 0)
      LOGEVENTERROR(le2)
    else
    {
      switch (event2.type) {
      case NDB_LE_BackupStarted:
	printf("Node %d: BackupStarted\n", event2.source_nodeid);
	printf("  Starting node ID: %d\n", event2.BackupStarted.starting_node);
	printf("  Backup ID: %d\n", event2.BackupStarted.backup_id);
	break;
      case NDB_LE_BackupCompleted:
	printf("Node %d: BackupCompleted\n", event2.source_nodeid);
	printf("  Backup ID: %d\n", event2.BackupStarted.backup_id);
	break;
      case NDB_LE_BackupAborted:
	printf("Node %d: BackupAborted\n", event2.source_nodeid);
	break;
      case NDB_LE_BackupFailedToStart:
	printf("Node %d: BackupFailedToStart\n", event2.source_nodeid);
	break;

      case NDB_LE_NodeFailCompleted:
	printf("Node %d: NodeFailCompleted\n", event2.source_nodeid);
	break;
      case NDB_LE_ArbitResult:
	printf("Node %d: ArbitResult\n", event2.source_nodeid);
	printf("  code %d, arbit_node %d\n",
	       event2.ArbitResult.code & 0xffff,
	       event2.ArbitResult.arbit_node);
	break;
      case NDB_LE_DeadDueToHeartbeat:
	printf("Node %d: DeadDueToHeartbeat\n", event2.source_nodeid);
	printf("  node %d\n", event2.DeadDueToHeartbeat.node);
	break;

      case NDB_LE_Connected:
	printf("Node %d: Connected\n", event2.source_nodeid);
	printf("  node %d\n", event2.Connected.node);
	break;
      case NDB_LE_Disconnected:
	printf("Node %d: Disconnected\n", event2.source_nodeid);
	printf("  node %d\n", event2.Disconnected.node);
	break;
      case NDB_LE_NDBStartCompleted:
	printf("Node %d: StartCompleted\n", event2.source_nodeid);
	printf("  version %d.%d.%d\n",
	       event2.NDBStartCompleted.version >> 16 & 0xff,
	       event2.NDBStartCompleted.version >> 8 & 0xff,
	       event2.NDBStartCompleted.version >> 0 & 0xff);
	break;
      case NDB_LE_ArbitState:
	printf("Node %d: ArbitState\n", event2.source_nodeid);
	printf("  code %d, arbit_node %d\n",
	       event2.ArbitState.code & 0xffff,
	       event2.ArbitResult.arbit_node);
	break;

      default:
	break;
      }
    }
  }
    
  ndb_mgm_destroy_logevent_handle(&le1);
  ndb_mgm_destroy_logevent_handle(&le2);
  ndb_mgm_destroy_handle(&h1);
  ndb_mgm_destroy_handle(&h2);
  ndb_end(0);
  return 0;
}
Previous   Next
Chapter 2 The NDB API Home Chapter 4 MySQL Cluster Connector for Java