svn commit - mysqldoc@docsrva: r12343 - trunk/ndbapi

[jon]

Author: jstephens
Date: 2008-11-08 13:56:52 +0100 (Sat, 08 Nov 2008)
New Revision: 12343

Log:

Documented ndb_mgm_dump_state() function

Fixes Docs Bug #40585 / CSC#30936 (Hartmut)



Modified:
   trunk/ndbapi/mgm-api.xml


Modified: trunk/ndbapi/mgm-api.xml
===================================================================
--- trunk/ndbapi/mgm-api.xml	2008-11-08 00:15:07 UTC (rev 12342)
+++ trunk/ndbapi/mgm-api.xml	2008-11-08 12:56:52 UTC (rev 12343)
Changed blocks: 3, Lines Added: 166, Lines Deleted: 4; 5542 bytes

@@ -2689,8 +2689,8 @@
       <abstract>
 
         <para>
-          This section discusses how to obtain the status of
-          <literal>NDB</literal> Cluster nodes.
+          This section discusses how to obtain status information from
+          MySQL Cluster nodes.
         </para>
 
       </abstract>

@@ -2708,8 +2708,8 @@
           <title>Description</title>
 
           <para>
-            This function is used to obtain the status of the nodes in
-            an <literal>NDB</literal> Cluster.
+            This function is used to obtain the status of the nodes in a
+            MySQL Cluster.
           </para>
 
         </formalpara>

@@ -2775,6 +2775,168 @@
 
       </section>
 
+      <section id="ndb-mgm-dump-state">
+
+        <title><literal>ndb_mgm_dump_state()</literal></title>
+
+        <indexterm>
+          <primary>ndb_mgm_dump_state() function (MGM API)</primary>
+        </indexterm>
+
+        <formalpara>
+
+          <title>Description</title>
+
+          <para>
+            This function can be used to dump debugging information to
+            the cluster log. The MySQL Cluster management client
+            <literal>DUMP</literal> command is a wrapper for this
+            function.
+          </para>
+
+        </formalpara>
+
+        <important>
+          <para>
+            <literal>ndb_mgm_dump_state()</literal>, like the
+            <literal>DUMP</literal> 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 <literal>DUMP</literal> command, and for
+            a listing of current <literal>DUMP</literal> codes and their
+            effects, see <xref linkend="ndb-internals-dump-commands"/>.
+          </para>
+        </important>
+
+        <formalpara>
+
+          <title>Signature</title>
+
+          <para>
+<programlisting>
+int ndb_mgm_dump_state
+    (
+      NdbMgmHandle <replaceable>handle</replaceable>,
+      int <replaceable>nodeId</replaceable>,
+      const int* <replaceable>arguments</replaceable>,
+      int <replaceable>numberOfArguments</replaceable>,
+      struct ndb_mgm_reply* <replaceable>reply</replaceable>
+    )
+</programlisting>
+          </para>
+
+        </formalpara>
+
+        <formalpara>
+
+          <title>Parameters</title>
+
+          <para>
+            This function takes the following pararemeters:
+
+            <itemizedlist>
+
+              <listitem>
+                <para>
+                  A management server handle
+                  (<literal>NdbMgmHandle</literal>)
+                </para>
+              </listitem>
+
+              <listitem>
+                <para>
+                  The <replaceable>nodeId</replaceable> of a cluster
+                  data node.
+                </para>
+
+                <note>
+                  <para>
+                    To dump from all data nodes in the cluster, use
+                    <literal>0</literal> as the value for this
+                    parameter.
+                  </para>
+                </note>
+              </listitem>
+
+              <listitem>
+                <para>
+                  An array of <replaceable>arguments</replaceable>. The
+                  first of these is the <literal>DUMP</literal> code to
+                  be executed. Subsequent arguments can be passed in
+                  this array if needed by or desired for the
+                  corresponding <literal>DUMP</literal> command.
+                </para>
+              </listitem>
+
+              <listitem>
+                <para>
+                  The <replaceable>numberOfArguments</replaceable> to be
+                  passed.
+                </para>
+              </listitem>
+
+              <listitem>
+                <para>
+                  An <literal>ndb_mgm_reply</literal> which cntains a
+                  return code along with a response or error message
+                  (see <xref linkend="struct-ndb-mgm-reply"/>, for more
+                  information).
+                </para>
+              </listitem>
+
+            </itemizedlist>
+          </para>
+
+        </formalpara>
+
+        <formalpara>
+
+          <title>Return Value</title>
+
+          <para>
+            <literal>0</literal> on success; otherwise, an error code.
+          </para>
+
+        </formalpara>
+
+        <formalpara>
+
+          <title>Example</title>
+
+          <para>
+            The following example has the same result as running
+            <literal>2 DUMP 1000</literal> in the management client:
+
+<programlisting>
+//  [...]
+#include &lt;mgmapi_debug.h&gt;
+//  [...]
+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, &amp;reply);
+            </programlisting>
+
+            <note>
+              <para>
+                Currently, you must include the header file
+                <filename>mgmapi_debug.h</filename> in your application
+                code in order to make use of
+                <literal>ndb_mgm_dump_state()</literal>.
+              </para>
+            </note>
+          </para>
+
+        </formalpara>
+
+      </section>
+
     </section>
 
     <section id="mgm-api-functions-start-stop-nodes">