<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
<title>MySQL Cluster Management API</title>
<link href="doxygen.css" rel="stylesheet" type="text/css">
<link href="tabs.css" rel="stylesheet" type="text/css">
</head><body>
<!-- Generated by Doxygen 1.5.5 -->
<div class="contents">
<h1>MySQL Cluster Management API</h1>
<p>
The MySQL Cluster Management API (MGM API) is a C language API that is used for:<ul>
<li>Starting and stopping database nodes (ndbd processes)</li><li>Starting and stopping Cluster backups</li><li>Controlling the NDB Cluster log</li><li>Performing other administrative tasks</li></ul>
<h2><a class="anchor" name="secMgmApiGeneral">
General Concepts</a></h2>
Each MGM API function needs a management server handle of type <a class="el" href="group__MGM__C__API.html#g197a3fdbd9cb4123b82807a294fcbe33">NdbMgmHandle</a>. This handle is created by calling the function function <a class="el" href="group__MGM__C__API.html#gb4fbfb30050c42b030796e958c20ddf2">ndb_mgm_create_handle()</a> and freed by calling <a class="el" href="group__MGM__C__API.html#g7fcf926b7f47192e104999c176c6a93d">ndb_mgm_destroy_handle()</a>.<p>
A function can return any of the following:<ol type=1>
<li>An integer value, with a value of <b>-1</b> indicating an error.</li><li>A non-constant pointer value. A <em>NULL</em> value indicates an error; otherwise, the return value must be freed by the programmer</li><li>A constant pointer value, with a <em>NULL</em> value indicating an error. The returned value should <em>not</em> be freed.</li></ol>
<p>
Error conditions can be identified by using the appropriate error-reporting functions <a class="el" href="group__MGM__C__API.html#g63d1960aee3501ff941016959b15331a">ndb_mgm_get_latest_error()</a> and <a class="el" href="group__MGM__C__API.html#gfe7d8f72caf6aa219b0b7e7e68a2f78e">ndb_mgm_error</a>.<p>
Here is an example using the MGM API (without error handling for brevity's sake). <div class="fragment"><pre class="fragment"> <a class="code" href="group__MGM__C__API.html#g197a3fdbd9cb4123b82807a294fcbe33">NdbMgmHandle</a> handle= <a class="code" href="group__MGM__C__API.html#gb4fbfb30050c42b030796e958c20ddf2">ndb_mgm_create_handle</a>();
<a class="code" href="group__MGM__C__API.html#g450d7297c4c9e634fd3db071c60beb2c">ndb_mgm_connect</a>(handle,0,0,0);
<span class="keyword">struct </span><a class="code" href="structndb__mgm__cluster__state.html">ndb_mgm_cluster_state</a> *state= <a class="code" href="group__MGM__C__API.html#g3a1e5dc9add984c46836a2cf59ee8f10">ndb_mgm_get_status</a>(handle);
<span class="keywordflow">for</span>(<span class="keywordtype">int</span> i=0; i < state-><a class="code" href="structndb__mgm__cluster__state.html#e6e13e9f8b46bae10ce29d3f2a17ced4">no_of_nodes</a>; i++)
{
<span class="keyword">struct </span><a class="code" href="structndb__mgm__node__state.html">ndb_mgm_node_state</a> *node_state= &state-><a class="code" href="group__MGM__C__API.html#g6a0a1b287fca2cb9898305f20b6c1ba9">node_states</a>[i];
printf(<span class="stringliteral">"node with ID=%d "</span>, node_state-><a class="code" href="structndb__mgm__node__state.html#eb47932009fa4acb0b2bf5bca65dd7af">node_id</a>);
<span class="keywordflow">if</span>(node_state-><a class="code" href="group__MGM__C__API.html#gd26195c2245670b170de5a76d33e97ce">version</a> != 0)
printf(<span class="stringliteral">"connected\n"</span>);
<span class="keywordflow">else</span>
printf(<span class="stringliteral">"not connected\n"</span>);
}
free((<span class="keywordtype">void</span>*)state);
<a class="code" href="group__MGM__C__API.html#g7fcf926b7f47192e104999c176c6a93d">ndb_mgm_destroy_handle</a>(&handle);
</pre></div><h2><a class="anchor" name="secLogEvents">
Log Events</a></h2>
The database nodes and management server(s) regularly and on specific occations report on various log events that occurs in the cluster. These log events are written to the cluster log. Optionally a mgmapi client may listen to these events by using the method <a class="el" href="group__MGM__C__API.html#g66740e0d12df36b1fb1ced0a6c075ae4">ndb_mgm_listen_event()</a>. Each log event belongs to a category, <a class="el" href="group__MGM__C__API.html#gb3e4baaeb93176f0c58dcb2ef6375f4f">ndb_mgm_event_category</a>, and has a severity, <a class="el" href="group__MGM__C__API.html#g68590adf48e1cbd1d18ffdc3cf68e413">ndb_mgm_event_severity</a>, associated with it. Each log event also has a level (0-15) associated with it.<p>
Which log events that come out is controlled with <a class="el" href="group__MGM__C__API.html#g66740e0d12df36b1fb1ced0a6c075ae4">ndb_mgm_listen_event()</a>, <a class="el" href="group__MGM__C__API.html#g0cc2d08a20ed69626c655876c54acbc5">ndb_mgm_set_clusterlog_loglevel()</a>, and <a class="el" href="group__MGM__C__API.html#gad30082bc3658d20f88303aaa05fc8b4">ndb_mgm_set_clusterlog_severity_filter()</a>.<p>
Below is an example of how to listen to events related to backup.<p>
<div class="fragment"><pre class="fragment"> <span class="keywordtype">int</span> filter[] = { 15, <a class="code" href="group__MGM__C__API.html#ggb3e4baaeb93176f0c58dcb2ef6375f4fd23d1c6901e89189c2875d48e132e9b6">NDB_MGM_EVENT_CATEGORY_BACKUP</a>, 0 };
<span class="keywordtype">int</span> fd = <a class="code" href="group__MGM__C__API.html#g66740e0d12df36b1fb1ced0a6c075ae4">ndb_mgm_listen_event</a>(handle, filter);
</pre></div><h2><a class="anchor" name="secSLogEvents">
Structured Log Events</a></h2>
The following steps are involved:<ul>
<li>Create a NdbEventLogHandle using <a class="el" href="group__MGM__C__API.html#gb0c12feda5183dcf17d37fd1c6042f2b">ndb_mgm_create_logevent_handle()</a></li><li>Wait and store log events using <a class="el" href="group__MGM__C__API.html#g07675636efb0d835a0b898e1e42cfa4d">ndb_logevent_get_next()</a></li><li>The log event data is available in the struct <a class="el" href="structndb__logevent.html">ndb_logevent</a>. The data which is specific to a particular event is stored in a union between structs so use <a class="el" href="structndb__logevent.html#d92fe51ef390d72dd6b09a218763e6b6">ndb_logevent::type</a> to decide which struct is valid.</li></ul>
<p>
Sample code for listening to Backup related events. The availaable log events are listed in ndb_logevent::h<p>
<div class="fragment"><pre class="fragment"> <span class="keywordtype">int</span> filter[] = { 15, <a class="code" href="group__MGM__C__API.html#ggb3e4baaeb93176f0c58dcb2ef6375f4fd23d1c6901e89189c2875d48e132e9b6">NDB_MGM_EVENT_CATEGORY_BACKUP</a>, 0 };
NdbEventLogHandle le_handle= <a class="code" href="group__MGM__C__API.html#gb0c12feda5183dcf17d37fd1c6042f2b">ndb_mgm_create_logevent_handle</a>(handle, filter);
<span class="keyword">struct </span><a class="code" href="structndb__logevent.html">ndb_logevent</a> le;
<span class="keywordtype">int</span> r= <a class="code" href="group__MGM__C__API.html#g07675636efb0d835a0b898e1e42cfa4d">ndb_logevent_get_next</a>(le_handle,&le,0);
<span class="keywordflow">if</span> (r < 0) error
<span class="keywordflow">else</span> <span class="keywordflow">if</span> (r == 0) no <span class="keyword">event</span>
<span class="keywordflow">switch</span> (le.type)
{
<span class="keywordflow">case</span> <a class="code" href="group__MGM__C__API.html#gg13048468b99dd635143a8a3930e41f5ed83bffeb897f106cf2781f59da33dfe7">NDB_LE_BackupStarted</a>:
... le.BackupStarted.starting_node;
... le.BackupStarted.backup_id;
<span class="keywordflow">break</span>;
<span class="keywordflow">case</span> <a class="code" href="group__MGM__C__API.html#gg13048468b99dd635143a8a3930e41f5eb09c8964cbcf05b8d3a96eca840f5504">NDB_LE_BackupFailedToStart</a>:
... le.BackupFailedToStart.error;
<span class="keywordflow">break</span>;
<span class="keywordflow">case</span> <a class="code" href="group__MGM__C__API.html#gg13048468b99dd635143a8a3930e41f5e7d536ff5944df12f8358390da9c68606">NDB_LE_BackupCompleted</a>:
... le.BackupCompleted.stop_gci;
<span class="keywordflow">break</span>;
<span class="keywordflow">case</span> <a class="code" href="group__MGM__C__API.html#gg13048468b99dd635143a8a3930e41f5e66a2bc7def6a3f77d294d88d4ab5c984">NDB_LE_BackupAborted</a>:
... le.BackupStarted.backup_id;
<span class="keywordflow">break</span>;
<span class="keywordflow">default</span>:
<span class="keywordflow">break</span>;
}
</pre></div> </div>
<hr>
<address>
<small>
<center>
Documentation generated Sun Apr 20 06:25:33 2008 from mysql source files.<br>
© 2003-2004
<a href="http://www.mysql.com">MySQL AB</a>
<br>
</center>
</small></address>
</body>
</html>
distrib
>
Mandriva
>
2008.1
>
x86_64
>
media
>
main-testing
>
by-pkgid
>
91128064e1b251eab84e1c0e3ea0dd7a
>
files
>
87
