Table of Contents
Abstract
This chapter discusses the MySQL 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 concepts, programming constructs, and event types.
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.
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);
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);
The following steps are involved:
Create an NdbLogEventHandle using
ndb_mgm_create_logevent_handle().
Wait for and store log events using
ndb_logevent_get_next().
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 MySQL 5.1 sources.
Abstract
This section covers the structures and functions used in the MGM API. Listings are grouped by purpose or use.
Abstract
This section discusses functions that are used for listening to log events.
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.
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.
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.
Description.
This function retrieves a file descriptor from an
NdbMgmLogEventHandle. It was implemented
in MySQL 5.1.12.
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.
Description.
This function is used to retrieve the next log event, using
the event's data to fill in the supplied
ndb_logevent structure.
Signature.
int ndb_logevent_get_next
(
const NdbLogEventHandle handle,
struct ndb_logevent* logevent,
unsigned timeout
)
Parameters. Three parameters are expected by this functions:
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.
Description. This function retrieves the error code from the most recent error.
You may prefer to use
ndb_logevent_get_latest_error_msg()
instead. See
Section 3.2.1.7, “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.
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.
Description. This function is used to get the latest error code associated with a given management server handle.
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; see
Section 3.3.3, “The ndb_mgm_error Type”. You can obtain the
related error message using
ndb_mgm_get_latest_error_msg(); see
Section 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.
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(); see
Section 3.2.2.3, “ndb_mgm_get_latest_error_desc()”, for
details.
Description.
Get the most recent error description associated with an
NdbMgmHandle; this description provides
additional information regarding the error message.
Signature.
const char* ndb_mgm_get_latest_error_desc
(
const NdbMgmHandle handle
)
Parameters.
An NdbMgmHandle.
Return value. The error description text.
Abstract
This section contains information about the MGM API functions used to create and destroy management server handles.
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.
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.
Description.
Beginning with MySQL Cluster NDB 6.3.19, 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.)
Previous to MySQL Cluster NDB 6.3.19, MGM API applications simply exited without returning an error whenever the connection to the management server was lost. (Bug#40498)
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.
ndb_mgm_get_connectstring()ndb_mgm_get_configuration_nodeid()ndb_mgm_get_connected_port()ndb_mgm_get_connected_host()ndb_mgm_get_version()ndb_mgm_is_connected()ndb_mgm_check_connection()ndb_mgm_number_of_mgmd_in_connect_string()ndb_mgm_set_bindaddress()ndb_mgm_set_connectstring()ndb_mgm_set_configuration_nodeid()ndb_mgm_set_timeout()ndb_mgm_connect()ndb_mgm_disconnect()Abstract
This section discusses MGM API functions that are used to
initiate, configure, and terminate connections to an
NDB management server.
Description. This function retrieves the connectstring used for a connection.
This function returns the default connectstring if no call
to ndb_mgm_set_connectstring() has been
performed. In addition, the returned connectstring may be
formatted slightly differently than the original in that it
may contain specifiers not present in the original.
The connectstring 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 connectstring—this is the same value that is
pushed to the buffer.
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.
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.
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.
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-,
where x.x.x
ndb-y.y.y-statusx.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, and any nonzero value indicating an error.
Description. Used to determine whether a connection has been established.
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. See
Section 3.2.4.7, “ndb_mgm_check_connection()”, for more
information.
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.
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, “General Concepts”).
Return value.
This function returns -1 in the event of
an error; otherwise it returns 0.
Description.
This is a convenience function which provides an easy way to
determine the number of management servers referenced in a
connectstring 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.
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)
Errors caused by binding an otherwise valid local address are not reported until the connection to the management is actually attempted.
Description. This function is used to set the connectstring for a management server connection to a node.
Signature.
int ndb_mgm_set_connectstring
(
NdbMgmHandle handle,
const char* connectstring
)
Parameters.
ndb_mgm_set_connectstring() takes two
parameters: Section 3.2.4.1, “ndb_mgm_get_connectstring()”
also uses this format for connectstrings.
A management server handle.
A connectstring whose format is
shown here:
connectstring:= [nodeid-specification,]host-specification[,host-specification]
(It is possible to establish connections with multiple management servers using a single connectstring.)
nodeid-specification:= nodeid=idhost-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.
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.
Description. Normally, network operations time out after 60 seconds. This function permits you to vary this time.
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.
The timeout must be an even
multiple of 1000—that is, it must be equivalent to
an integral number of seconds. Fractional seconds are
not supported.
Return value.
Returns 0 on success, with any other
value representing failure.
Description.
This function establishes a connection to a management
server specified by the connectstring 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.
Abstract
This section discusses how to obtain status information from MySQL Cluster nodes.
Description. This function is used to obtain the status of the nodes in a MySQL Cluster.
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. See
Section 3.4.3, “The ndb_mgm_cluster_state Structure”, for more
information.
Description.
This function can be used to dump debugging information to
the cluster log. The MySQL Cluster management client
DUMP command is a wrapper for this
function.
ndb_mgm_dump_state(), like the
DUMP command, can cause a running MySQL
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 Section 6.2, “DUMP Commands”.
This function became available in MySQL Cluster NDB 6.1.2.17 and MySQL Cluster NDB 6.3.19.
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 cntains a return
code along with a response or error message (see
Section 3.4.4, “The ndb_mgm_reply Structure”, for more
information).
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);
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: These functions are detailed in the next few sections.
Starting Nodes.
Use ndb_mgm_start().
Stopping Nodes.
Use ndb_mgm_stop(),
ndb_mgm_stop2(), or
ndb_mgm_stop3().
Restarting Nodes.
Use ndb_mgm_restart(),
ndb_mgm_restart2(), or
ndb_mgm_restart3().
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.
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(. See
Section 3.2.6.3, “handle,
number,
list, 0)ndb_mgm_stop2()”.
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.
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.
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.
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.
This function was added in MySQL Cluster NDB 7.0.19 and MySQL Cluster NDB 7.1.8.
Signature.
int ndb_mgm_stop3
(
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.
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.
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.
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.
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.
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 MySQL 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.
This function was added in MySQL Cluster NDB 7.0.19 and MySQL Cluster NDB 7.1.8.
Signature.
int ndb_mgm_restart3
(
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.
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.
Abstract
This section covers the functions available in the MGM API for controlling the output of the cluster log.
Description. This function is used to retrieve the cluster log severity filter currently in force.
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.
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. See
Section 3.4.4, “The ndb_mgm_reply Structure”.
Return value.
The function returns -1 in the event of
failure.
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.
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.
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:
An NdbMgmHandle.
The id of the node affected.
An event categorymdash;this is
one of the values listed in
Section 3.3.7, “The ndb_mgm_event_category Type” .
A logging level.
A pointer to an ndb_mgm_reply structure
for the reply message. (See
Section 3.4.4, “The ndb_mgm_reply Structure”.)
Return value.
In the event of an error, this function returns
-1.
Abstract
This section covers the functions provided in the MGM API for starting and stopping backups.
Description. This function is used to initiate a backup of a MySQL 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.
No backup id is returned if
wait is set equal to 0.
A pointer to an ndb_mgm_reply structure
to accommodate a reply. See
Section 3.4.4, “The ndb_mgm_reply Structure”.
Return value.
In the event of failure, the function returns
-1.
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.
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.
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.
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:
An NdbMgmHandle.
A pointer to an ndb_mgm_reply.
Return value.
Returns -1 in case of an error.
Abstract
This section discusses the data types defined by the MGM API.
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.
Description. This is used to classify the different types of nodes in a MySQL Cluster.
Enumeration values. Possible values are shown, along with descriptions, in the following table:
| Value | Description |
|---|---|
NDB_MGM_NODE_TYPE_UNKNOWN | Unknown |
NDB_MGM_NODE_TYPE_API | API Node (SQL node) |
NDB_MGM_NODE_TYPE_NDB | Data node |
NDB_MGM_NODE_TYPE_MGM | Management node |
Description. This type describes a Cluster node's status.
Enumeration values. Possible values are shown, along with descriptions, in the following table:
| Value | Description |
|---|---|
NDB_MGM_NODE_STATUS_UNKNOWN | The node's status is not known |
NDB_MGM_NODE_STATUS_NO_CONTACT | The node cannot be contacted |
NDB_MGM_NODE_STATUS_NOT_STARTED | The node has not yet executed the startup protocol |
NDB_MGM_NODE_STATUS_STARTING | The node is executing the startup protocol |
NDB_MGM_NODE_STATUS_STARTED | The node is running |
NDB_MGM_NODE_STATUS_SHUTTING_DOWN | The node is shutting down |
NDB_MGM_NODE_STATUS_RESTARTING | The node is restarting |
NDB_MGM_NODE_STATUS_SINGLEUSER | The node is running in single-user (maintenance) mode |
NDB_MGM_NODE_STATUS_RESUME | The node is in resume mode |
Description.
The values for this type are the error codes that may be
generated by MGM API functions. These may be found in
Section 5.1, “MGM API Errors”.
See also Section 3.2.2.1, “ndb_mgm_get_latest_error()”, for
more information.
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:
| Category | Type | Description |
|---|---|---|
NDB_MGM_EVENT_CATEGORY_CONNECTION | (Connection events) | |
NDB_LE_Connected | The node has connected | |
NDB_LE_Disconnected | The node was disconnected | |
NDB_LE_CommunicationClosed | Communication with the node has been closed | |
NDB_LE_CommunicationOpened | Communication with the node has been started | |
NDB_LE_ConnectedApiVersion | The 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_GlobalCheckpointStarted | A global checkpoint has been started | |
NDB_LE_GlobalCheckpointCompleted | A global checkpoint has been completed | |
NDB_LE_LocalCheckpointStarted | The node has begun a local checkpoint | |
NDB_LE_LocalCheckpointCompleted | The node has completed a local checkpoint | |
NDB_LE_LCPStoppedInCalcKeepGci | The lcoal checkpoint was aborted, but the last global checkpoint was preserved | |
NDB_LE_LCPFragmentCompleted | Copying of a table fragment was completed | |
NDB_MGM_EVENT_CATEGORY_STARTUP | (Startup events) | |
NDB_LE_NDBStartStarted | The node has begun to start | |
NDB_LE_NDBStartCompleted | The node has completed the startup process | |
NDB_LE_STTORRYRecieved | The node received an STTORRY signal, indicating that
the reading of configuration data is underway; see
Section 6.5.2, “Configuration Read Phase (STTOR Phase -1)”,
and
Section 6.5.3, “STTOR Phase 0”,
for more information | |
NDB_LE_StartPhaseCompleted | A node start phase has been completed | |
NDB_LE_CM_REGCONF | The node has received a CM_REGCONF signal; see
Section 6.5.4, “STTOR Phase 1”,
for more information | |
NDB_LE_CM_REGREF | The node has received a CM_REGREF signal; see
Section 6.5.4, “STTOR Phase 1”,
for more information | |
NDB_LE_FIND_NEIGHBOURS | The node has discovered its neighboring nodes in the cluster | |
NDB_LE_NDBStopStarted | The node is beginning to shut down | |
NDB_LE_NDBStopCompleted | ||
NDB_LE_NDBStopForced | The node is being forced to shut down (usually indicates a severe problem in the cluster) | |
NDB_LE_NDBStopAborted | The 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_StartREDOLog | Redo logging has been started | |
NDB_LE_StartLog | Logging has started | |
NDB_LE_UNDORecordsExecuted | The node has read and executed all records from the redo log | |
NDB_LE_StartReport | The node is issuing a start report | |
NDB_MGM_EVENT_CATEGORY_NODE_RESTART | (Restart events) | |
NDB_LE_NR_CopyDict | The node is copying the data dictionary | |
NDB_LE_NR_CopyDistr | The node is copying data distribution information | |
NDB_LE_NR_CopyFragsStarted | The node is copying table fragments | |
NDB_LE_NR_CopyFragDone | The node has completed copying a table fragment | |
NDB_LE_NR_CopyFragsCompleted | The node has completed copying all necessary table fragments | |
NDB_MGM_EVENT_CATEGORY_NODE_RESTART | (Node failure and arbitration) | |
NDB_LE_NodeFailCompleted | All (remaining) nodes has been notified of the failure of a data node | |
NDB_LE_NODE_FAILREP | A data node has failed | |
NDB_LE_ArbitState | This event is used to report on the current state of arbitration in the cluster | |
NDB_LE_ArbitResult | This event is used to report on the outcome of node arbitration | |
NDB_LE_GCP_TakeoverStarted | The node is attempting to become the master node (to assume responsibility for GCPs) | |
NDB_LE_GCP_TakeoverCompleted | The node has become the master (and assumed responsibility for GCPs) | |
NDB_LE_LCP_TakeoverStarted | The node is attempting to become the master node (to assume responsibility for LCPs) | |
NDB_LE_LCP_TakeoverCompleted | The node has become the master (and assumed responsibility for LCPs) | |
NDB_MGM_EVENT_CATEGORY_STATISTIC | (Statistics events) | |
NDB_LE_TransReportCounters | This indicates a report of transaction activity, which is given approximately once every 10 seconds | |
NDB_LE_OperationReportCounters | Indicates a report on the number of operations performed by this node (also provided approximately once every 10 seconds) | |
NDB_LE_TableCreated | A new table has been created | |
NDB_LE_UndoLogBlocked | Undo logging is blocked because the log buffer is close to overflowing | |
NDB_LE_JobStatistic | ||
NDB_LE_SendBytesStatistic | Indicates a report of the average number of bytes transmitted per send operation by this node | |
NDB_LE_ReceiveBytesStatistic | Indicates a report of the average number of bytes received per send operation to this node | |
NDB_LE_MemoryUsage | A 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_TransporterError | A transporter error has occurred; see
Section 5.4, “NDB Transporter Errors”, for
transporter error codes and messages | |
NDB_LE_TransporterWarning | A potential problem is occurring in the transporter; see
Section 5.4, “NDB Transporter Errors”, for
transporter error codes and messages | |
NDB_LE_MissedHeartbeat | Indicates a data node has missed a hreatbeat expected from another data node | |
NDB_LE_DeadDueToHeartbeat | A 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_WarningEvent | Indicates a warning message | |
NDB_MGM_EVENT_CATEGORY_INFO | (Information events) | |
NDB_LE_SentHeartbeat | A node heartbeat has been sent | |
NDB_LE_CreateLogBytes | ||
NDB_LE_InfoEvent | Indicates an informational message | |
| [Single-User Mode] | NDB_LE_SingleUser | The cluster has entered or exited single user mode |
NDB_LE_EventBufferStatus | This type of event indicates potentially excessive usage of the event buffer | |
NDB_MGM_EVENT_CATEGORY_BACKUP | (Backups) | |
NDB_LE_BackupStarted | A backup has been started | |
NDB_LE_BackupFailedToStart | A backup has failed to start | |
NDB_LE_BackupCompleted | A backup has been completed successfully | |
NDB_LE_BackupAborted | A backup in progress was terminated by the user |
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:
| Value | Description |
|---|---|
NDB_MGM_ILLEGAL_EVENT_SEVERITY | Invalid event severity specified |
NDB_MGM_EVENT_SEVERITY_ON | Cluster logging is enabled |
NDB_MGM_EVENT_SEVERITY_DEBUG | Used for MySQL Cluster development only |
NDB_MGM_EVENT_SEVERITY_INFO | Informational messages |
NDB_MGM_EVENT_SEVERITY_WARNING | Conditions that are not errors as such, but that might require special handling |
NDB_MGM_EVENT_SEVERITY_ERROR | Nonfatal error conditions that should be corrected |
NDB_MGM_EVENT_SEVERITY_CRITICAL | Critical conditions such as device errors or out of memory errors |
NDB_MGM_EVENT_SEVERITY_ALERT | Conditions that require immediate attention, such as corruption of the cluster |
NDB_MGM_EVENT_SEVERITY_ALL | All 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.
Description. This type is used to describe log event errors.
Enumeration values. Possible values are shown, along with descriptions, in the following table:
| Value | Description |
|---|---|
NDB_LEH_NO_ERROR | No error |
NDB_LEH_READ_ERROR | Read error |
NDB_LEH_MISSING_EVENT_SPECIFIER | Invalid, incomplete, or missing log event specification |
NDB_LEH_UNKNOWN_EVENT_TYPE | Unknown log event type |
NDB_LEH_UNKNOWN_EVENT_VARIABLE | Unknown log event variable |
NDB_LEH_INTERNAL_ERROR | Internal error |
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:
| Value | Description |
|---|---|
NDB_MGM_ILLEGAL_EVENT_CATEGORY | Invalid log event category |
NDB_MGM_EVENT_CATEGORY_STARTUP | Log events occurring during startup |
NDB_MGM_EVENT_CATEGORY_SHUTDOWN | Log events occurring during shutdown |
NDB_MGM_EVENT_CATEGORY_STATISTIC | Statistics log events |
NDB_MGM_EVENT_CATEGORY_CHECKPOINT | Log events related to checkpoints |
NDB_MGM_EVENT_CATEGORY_NODE_RESTART | Log events occurring during node restart |
NDB_MGM_EVENT_CATEGORY_CONNECTION | Log events relating to connections between cluster nodes |
NDB_MGM_EVENT_CATEGORY_BACKUP | Log events relating to backups |
NDB_MGM_EVENT_CATEGORY_CONGESTION | Log events relating to congestion |
NDB_MGM_EVENT_CATEGORY_INFO | Uncategorised log events (severity level INFO) |
NDB_MGM_EVENT_CATEGORY_ERROR | Uncategorised 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.
Abstract
This section covers the programming structures available in the MGM API.
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* :
An handleNdbLogEventHandle, set by
ndb_logevent_get_next(). This handle is
used only for purposes of comparison.
enum Ndb_logevent_type
: Tells which type
of event this is.
type
See Section 3.3.4, “The Ndb_logevent_type Type”, for possible
values.
unsigned :
The time at which the log event was registered with the
management server.
time
enum ndb_mgm_event_category
: The log event
category.
category
See Section 3.3.7, “The ndb_mgm_event_category Type”, for
possible values.
enum ndb_mgm_event_severity
: The log event
severity.
severity
See Section 3.3.5, “The ndb_mgm_event_severity Type”, for
possible values.
unsigned
: The log event
level. This is a value in the range of 0 to 15, inclusive.
level
unsigned
: The node
ID of the node that reported this event.
source_nodeid
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 Value | Structure |
|---|---|
NDB_LE_Connected | Connected:
unsigned |
NDB_LE_Disconnected | Disconnected:
unsigned |
NDB_LE_CommunicationClosed | CommunicationClosed:
unsigned |
NDB_LE_CommunicationOpened | CommunicationOpened:
unsigned |
NDB_LE_ConnectedApiVersion | ConnectedApiVersion:
unsigned |
NDB_LE_GlobalCheckpointStarted | GlobalCheckpointStarted:
unsigned |
NDB_LE_GlobalCheckpointCompleted | GlobalCheckpointCompleted:
unsigned |
NDB_LE_LocalCheckpointStarted | LocalCheckpointStarted:
unsigned |
NDB_LE_LocalCheckpointCompleted | LocalCheckpointCompleted:
unsigned |
NDB_LE_LCPStoppedInCalcKeepGci | LCPStoppedInCalcKeepGci:
unsigned |
NDB_LE_LCPFragmentCompleted | LCPFragmentCompleted:
unsigned |
NDB_LE_UndoLogBlocked | UndoLogBlocked:
unsigned |
NDB_LE_NDBStartStarted | NDBStartStarted:
unsigned |
NDB_LE_NDBStartCompleted | NDBStartCompleted:
unsigned |
NDB_LE_STTORRYRecieved | STTORRYRecieved:
[NONE]
|
NDB_LE_StartPhaseCompleted | StartPhaseCompleted:
unsigned |
NDB_LE_CM_REGCONF | CM_REGCONF:
unsigned |
NDB_LE_CM_REGREF | CM_REGREF:
unsigned |
NDB_LE_FIND_NEIGHBOURS | FIND_NEIGHBOURS:
unsigned |
NDB_LE_NDBStopStarted | NDBStopStarted:
unsigned |
NDB_LE_NDBStopCompleted | NDBStopCompleted:
unsigned |
NDB_LE_NDBStopForced | NDBStopForced:
unsigned |
NDB_LE_NDBStopAborted | NDBStopAborted:
[NONE]
|
NDB_LE_StartREDOLog | StartREDOLog:
unsigned |
NDB_LE_StartLog | StartLog:
unsigned |
NDB_LE_UNDORecordsExecuted | UNDORecordsExecuted:
unsigned |
NDB_LE_NR_CopyDict | NR_CopyDict:
[NONE]
|
NDB_LE_NR_CopyDistr | NR_CopyDistr:
[NONE]
|
NDB_LE_NR_CopyFragsStarted | NR_CopyFragsStarted:
unsigned |
NDB_LE_NR_CopyFragDone | NR_CopyFragDone:
unsigned |
NDB_LE_NR_CopyFragsCompleted | NR_CopyFragsCompleted:
unsigned |
NDB_LE_NodeFailCompleted | NodeFailCompleted:
unsigned(For block and
completing_node,
0 is interpreted as
“all”.) |
NDB_LE_NODE_FAILREP | NODE_FAILREP:
unsigned |
NDB_LE_ArbitState | ArbitState:
unsigned |
NDB_LE_ArbitResult | ArbitResult:
unsigned |
NDB_LE_GCP_TakeoverStarted | GCP_TakeoverStarted:
[NONE]
|
NDB_LE_GCP_TakeoverCompleted | GCP_TakeoverCompleted:
[NONE]
|
NDB_LE_LCP_TakeoverStarted | LCP_TakeoverStarted:
[NONE]
|
NDB_LE_TransReportCounters | TransReportCounters:
unsigned |
NDB_LE_OperationReportCounters | OperationReportCounters:
unsigned |
NDB_LE_TableCreated | TableCreated:
unsigned |
NDB_LE_JobStatistic | JobStatistic:
unsigned |
NDB_LE_SendBytesStatistic | SendBytesStatistic:
unsigned |
NDB_LE_ReceiveBytesStatistic | ReceiveBytesStatistic:
unsigned |
NDB_LE_MemoryUsage | MemoryUsage:
int |
NDB_LE_TransporterError | TransporterError:
unsigned |
NDB_LE_TransporterWarning | TransporterWarning:
unsigned |
NDB_LE_MissedHeartbeat | MissedHeartbeat:
unsigned |
NDB_LE_DeadDueToHeartbeat | DeadDueToHeartbeat:
unsigned |
NDB_LE_WarningEvent | WarningEvent:
[NOT YET IMPLEMENTED]
|
NDB_LE_SentHeartbeat | SentHeartbeat:
unsigned |
NDB_LE_CreateLogBytes | CreateLogBytes:
unsigned |
NDB_LE_InfoEvent | InfoEvent:
[NOT YET IMPLEMENTED]
|
NDB_LE_EventBufferStatus | EventBufferStatus:
unsigned |
NDB_LE_BackupStarted | BackupStarted:
unsigned |
NDB_LE_BackupFailedToStart | BackupFailedToStart:
unsigned |
NDB_LE_BackupCompleted | BackupCompleted:
unsigned |
NDB_LE_BackupAborted | BackupAborted:
unsigned |
NDB_LE_SingleUser | SingleUser:
unsigned |
NDB_LE_StartReport | StartReport:
unsigned |
Description. Provides information on the status of a Cluster node.
Definition. This structure contains the following members:
int :
The cluster node's node ID.
node_id
enum ndb_mgm_node_type
: The node
type.
node_type
See Section 3.3.1, “The ndb_mgm_node_type Type”, for permitted
values.
enum ndb_mgm_node_status
: The node's
status.
node_status
See Section 3.3.2, “The ndb_mgm_node_status Type”, for permitted
values.
int
: The start
phase.
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
: The ID for
heartbeats and master takeover.
dynamic_id
Valid only for data (ndbd) nodes.
int
: The node
group to which the node belongs.
node_group
Valid only for data (ndbd) nodes.
int :
Internal version number.
version
int
: The
number of times this node has connected to or disconnected
from the management server.
connect_count
char
: The
IP address of the node when it connected to the management
server.
connect_address[]
This value is empty if the management server has been restarted since the node last connected.
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
: The number
of elements in the no_of_nodesnode_states
array.
struct ndb_mgm_node_state
: An array
containing the states of the nodes.
node_states[]
Each element of this array is an
ndb_mgm_node_state structure. For more
information, see Section 3.4.2, “The ndb_mgm_node_state 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
: For a
successful operation, this value is return_code0;
otherwise, it contains an error code.
For error codes, see Section 3.3.3, “The ndb_mgm_error Type”.
char
: contains
the text of the response or error message.
message[256]
See Section 3.2.2.1, “ndb_mgm_get_latest_error()”, and
Section 3.2.2.2, “ndb_mgm_get_latest_error_msg()”.
This section contains MGM API coding examples.
This example shows the basics of handling event logging using the MGM API.
The source code for this program may be found in the MySQL
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 connectstring\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;
}
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 MySQL
Cluster source tree, in the file
storage/ndb/ndbapi-examples/mgmapi_logevent2/main.cpp.
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 connectstring\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;
}