Author: jstephens
Date: 2006-06-27 11:38:07 +0200 (Tue, 27 Jun 2006)
New Revision: 2526
Log:
MGM API log event functions.
Modified:
trunk/ndbapi/mgm-api.xml
Modified: trunk/ndbapi/mgm-api.xml
===================================================================
--- trunk/ndbapi/mgm-api.xml 2006-06-27 07:40:30 UTC (rev 2525)
+++ trunk/ndbapi/mgm-api.xml 2006-06-27 09:38:07 UTC (rev 2526)
@@ -210,6 +210,11 @@
}
</programlisting>
+ <para>
+ For more information, see
+ <xref linkend="mgm-api-functions-log-events"/>.
+ </para>
+
<note>
<para>
Available log events are listed in
@@ -234,8 +239,593 @@
</abstract>
- <section id="mgm-api-error-handling">
+ <section id="mgm-api-functions-log-events">
+ <title>Log Event Functions</title>
+
+ <abstract>
+
+ <para>
+ This section discusses functions that are used for listening
+ to log events.
+ </para>
+
+ </abstract>
+
+ <section id="mgm-api-ndb-mgm-listen-event">
+
+ <title><literal>ndb_mgm_listen_event()</literal></title>
+
+ <formalpara>
+
+ <title>Description</title>
+
+ <para>
+ 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.
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Signature</title>
+
+ <para>
+<programlisting>
+int ndb_mgm_listen_event
+ (
+ NdbMgmHandle <replaceable>handle</replaceable>,
+ const int <replaceable>filter[]</replaceable>
+ )
+</programlisting>
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Parameters</title>
+
+ <para>
+ This function takes two arguments:
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ An <literal>NdbMgmHandle</literal>
+ <replaceable>handle</replaceable>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ A <replaceable>filter</replaceable> which consists of
+ a series of <literal>{level,
+ ndb_mgm_event_category}</literal> pairs (in a single
+ array) that are pushed to a file descriptor. Use
+ <literal>0</literal> for the level to terminate the
+ list.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Return Value</title>
+
+ <para>
+ The file descriptor from which events are to be read.
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Example</title>
+
+ <para>
+<programlisting>
+[<emphasis>To be supplied...</emphasis>]
+</programlisting>
+ </para>
+
+ </formalpara>
+
+ </section>
+
+ <section id="mgm-api-ndb-mgm-create-logevent-handle">
+
+ <title><literal>ndb_mgm_create_logevent_handle()</literal></title>
+
+ <formalpara>
+
+ <title>Description</title>
+
+ <para>
+ This function is used to create a log event handle.
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Signature</title>
+
+ <para>
+<programlisting>
+NdbLogEventHandle ndb_mgm_create_logevent_handle
+ (
+ NdbMgmHandle <replaceable>handle</replaceable>,
+ const int <replaceable>filter[]</replaceable>
+ )
+</programlisting>
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Parameters</title>
+
+ <para>
+ This function takes two arguments:
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ An <literal>NdbMgmHandle</literal>
+ <replaceable>handle</replaceable>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ A <replaceable>filter</replaceable> which consists of
+ a series of <literal>{level,
+ ndb_mgm_event_category}</literal> pairs (in a single
+ array) that are pushed to a file descriptor. Use
+ <literal>0</literal> for the level to terminate the
+ list.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Return Value</title>
+
+ <para>
+ A log event handle.
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Example</title>
+
+ <para>
+<programlisting>
+[<emphasis>To be supplied...</emphasis>]
+</programlisting>
+ </para>
+
+ </formalpara>
+
+ </section>
+
+ <section id="mgm-api-ndb-mgm-destroy-logevent-handle">
+
+ <title><literal>ndb_mgm_destroy_logevent_handle()</literal></title>
+
+ <formalpara>
+
+ <title>Description</title>
+
+ <para>
+ Use this function to destroy a log event handle when there
+ is no further need for it.
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Signature</title>
+
+ <para>
+<programlisting>
+void ndb_mgm_destroy_logevent_handle
+ (
+ NdbLogEventHandle* <replaceable>handle</replaceable>
+ )
+</programlisting>
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Parameters</title>
+
+ <para>
+ A pointer to a log event <replaceable>handle</replaceable>.
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Return Value</title>
+
+ <para>
+ <emphasis>None</emphasis>.
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Example</title>
+
+ <para>
+<programlisting>
+[<emphasis>To be supplied...</emphasis>]
+</programlisting>
+ </para>
+
+ </formalpara>
+
+ </section>
+
+ <section id="mgm-api-ndb-logevent-get-fd">
+
+ <title><literal>ndb_logevent_get_fd()</literal></title>
+
+ <formalpara>
+
+ <title>Description</title>
+
+ <para>
+ This function retrieves a file descriptor from an
+ <literal>NdbMgmLogEventHandle</literal>.
+ </para>
+
+ </formalpara>
+
+ <warning>
+ <para>
+ Do not attempt to read from the file descriptor returned by
+ this function.
+ </para>
+ </warning>
+
+ <formalpara>
+
+ <title>Signature</title>
+
+ <para>
+<programlisting>
+int ndb_logevent_get_fd
+ (
+ const NdbLogEventHandle <replaceable>handle</replaceable>
+ )
+</programlisting>
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Parameters</title>
+
+ <para>
+ A <literal>LogEventHandle</literal>.
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Return Value</title>
+
+ <para>
+ A file descriptor. In the event of failure,
+ <literal>-1</literal> is returned.
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Example</title>
+
+ <para>
+<programlisting>
+[<emphasis>To be supplied...</emphasis>]
+</programlisting>
+ </para>
+
+ </formalpara>
+
+ </section>
+
+ <section id="mgm-api-ndb_logevent_get_next">
+
+ <title><literal>ndb_logevent_get_next()</literal></title>
+
+ <formalpara>
+
+ <title>Description</title>
+
+ <para>
+ This funciton is used to retrieve the next log event, using
+ the event's data to fill in the supplied
+ <literal>ndb_logevent</literal> structure.
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Signature</title>
+
+ <para>
+<programlisting>
+int ndb_logevent_get_next
+ (
+ const NdbLogEventHandle <replaceable>handle</replaceable>,
+ struct ndb_logevent* <replaceable>logevent</replaceable>,
+ unsigned <replaceable>timeout</replaceable>
+ )
+</programlisting>
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Parameters</title>
+
+ <para>
+ Three parameters are expected by this functions:
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ An <literal>NdbLogEventHandle</literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ A pointer to an <literal>ndb_logevent</literal> data
+ structure
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The number of milliseconds to wait for the event
+ before toming out
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Return Value</title>
+
+ <para>
+ The value returned by this function is interpreted as
+ follows:
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ <literal>> 0</literal>: The event exists, and it
+ data was retrieved into the
+ <replaceable>logevent</replaceable>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>0</literal>: A timeout occurred while waiting
+ for the event (more than
+ <replaceable>timeout</replaceable> milliseconds
+ elapsed)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>< 0</literal>: An error occurred.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ If the return value is less than or equal to zero, then the
+ <replaceable>logevent</replaceable> is not altered or
+ affected in any way.
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Example</title>
+
+ <para>
+<programlisting>
+[<emphasis>To be supplied...</emphasis>]
+</programlisting>
+ </para>
+
+ </formalpara>
+
+ </section>
+
+ <section id="mgm-api-ndb-logevent-get-latest-error">
+
+ <title><literal>ndb_logevent_get_latest_error()</literal></title>
+
+ <formalpara>
+
+ <title>Description</title>
+
+ <para>
+ This function retrieves the error code from the most recent
+ error.
+ </para>
+
+ </formalpara>
+
+ <note>
+ <para>
+ You may prefer to use
+ <literal>ndb_logevent_get_latest_error_msg()</literal>
+ instead. See
+ <xref linkend="mgm-api-ndb-logevent-get-latest-error-msg"/>
+ </para>
+ </note>
+
+ <formalpara>
+
+ <title>Signature</title>
+
+ <para>
+<programlisting>
+int ndb_logevent_get_latest_error
+ (
+ const NdbLogEventHandle <replaceable>handle</replaceable>
+ )
+</programlisting>
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Parameters</title>
+
+ <para>
+ A log event handle.
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Return Value</title>
+
+ <para>
+ An error code.
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Example</title>
+
+ <para>
+<programlisting>
+[<emphasis>To be supplied...</emphasis>]
+</programlisting>
+ </para>
+
+ </formalpara>
+
+ </section>
+
+ <section id="mgm-api-ndb-logevent-get-latest-error-msg">
+
+ <title><literal>ndb_logevent_get_latest_error_msg()</literal></title>
+
+ <formalpara>
+
+ <title>Description</title>
+
+ <para>
+ Retrieves the text of the most recent error obtained while
+ trying to read log events.
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Signature</title>
+
+ <para>
+<programlisting>
+const char* ndb_logevent_get_latest_error_msg
+ (
+ const NdbLogEventHandle <replaceable>handle</replaceable>
+ )
+</programlisting>
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Parameters</title>
+
+ <para>
+ A log event handle.
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Return Value</title>
+
+ <para>
+ The text of the error message.
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Example</title>
+
+ <para>
+<programlisting>
+[<emphasis>To be supplied...</emphasis>]
+</programlisting>
+ </para>
+
+ </formalpara>
+
+ </section>
+
+ </section>
+
+ <section id="mgm-api-functions-error-handling">
+
<title>Error-Handling Functions</title>
<abstract>
@@ -539,7 +1129,7 @@
</section>
- <section id="mgm-api-management-server-handles">
+ <section id="mgm-api-functions-management-server-handles">
<title>Creating & Destroying Management Server Handles</title>
@@ -551,7 +1141,7 @@
</section>
- <section id="mgm-api-management-server-connections">
+ <section id="mgm-api-functions-management-server-connections">
<title>Management Server Connections & Disconnections</title>
@@ -563,7 +1153,7 @@
</section>
- <section id="mgm-api-cluster-status">
+ <section id="mgm-api-functions-cluster-status">
<title>Cluster Status</title>
@@ -575,7 +1165,7 @@
</section>
- <section id="mgm-api-start-stop-nodes">
+ <section id="mgm-api-functions-start-stop-nodes">
<title>Starting & Stopping Nodes</title>
@@ -587,7 +1177,7 @@
</section>
- <section id="mgm-api-cluster-log-functions">
+ <section id="mgm-api-functions-cluster-log">
<title>Functions for Controlling the Cluster Log</title>
@@ -599,7 +1189,7 @@
</section>
- <section id="mgm-api-backup-functions">
+ <section id="mgm-api-functions-backup">
<title>Backup-Control Functions</title>
@@ -611,7 +1201,7 @@
</section>
- <section id="mgm-api-single-user-mode-functions">
+ <section id="mgm-api-functions-single-user-mode">
<title>Single-User Mode Functions</title>
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r2526 - trunk/ndbapi | jon | 27 Jun |
