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

[jon]

Author: jstephens
Date: 2006-12-20 02:48:38 +0100 (Wed, 20 Dec 2006)
New Revision: 4310

Log:

Documenting ndb_mgm_get_clusterlog_loglevel() MGM API function and
deprecated version ndb_mgm_get_loglevel_clusterlog() (Thanks, Martin!)



Modified:
   trunk/ndbapi/mgm-api.xml


Modified: trunk/ndbapi/mgm-api.xml
===================================================================
--- trunk/ndbapi/mgm-api.xml	2006-12-19 20:24:08 UTC (rev 4309)
+++ trunk/ndbapi/mgm-api.xml	2006-12-20 01:48:38 UTC (rev 4310)
Changed blocks: 9, Lines Added: 160, Lines Deleted: 18; 8652 bytes

@@ -3296,21 +3296,21 @@
           </para>
 
         </formalpara>
-        
+
         <important>
           <para>
             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 <citetitle>Signature</citetitle>,
             <citetitle>Parameters</citetitle>, and <citetitle>Return
-              Type</citetitle> sections that follow.
+            Type</citetitle> sections that follow.
           </para>
-          
+
           <para>
             These changes were done in order to make this function
             thread-safe. The pre-5.1.14 version is still supported for
-            backwards compatibility, but you should protect it with
-            a mutex if you intend to call it from more than one thread.
+            backwards compatibility, but you should protect it with a
+            mutex if you intend to call it from more than one thread.
           </para>
         </important>
 

@@ -3320,6 +3320,7 @@
 
           <para>
             As of MySQL 5.1.14:
+
 <programlisting>
 int ndb_mgm_get_clusterlog_severity_filter
     (

@@ -3327,9 +3328,11 @@
       struct ndb_mgm_severity* <replaceable>severity</replaceable>,
       unsigned int <replaceable>size</replaceable>
     )
-</programlisting>            
+</programlisting>
+
             In MySQL 5.1.13 and earlier, this function took only a
             single parameter, as shown here:
+
 <programlisting>
 const unsigned int* ndb_mgm_get_clusterlog_severity_filter
     (

@@ -3346,25 +3349,28 @@
 
           <para>
             This function added two new parameters in MySQL 5.1.14.
+
             <itemizedlist>
+
               <listitem>
                 <para>
                   <emphasis>All MySQL 5.1 releases</emphasis>:
                 </para>
-                
+
                 <para>
                   An <literal>NdbMgmHandle</literal>.
                 </para>
               </listitem>
-              
+
               <listitem>
                 <para>
                   <emphasis>Additionally, in MySQL 5.1.14 and
-                    later</emphasis>:
+                  later</emphasis>:
                 </para>
-                
+
                 <para>
                   <itemizedlist>
+
                     <listitem>
                       <para>
                         A vector <replaceable>severity</replaceable> of

@@ -3382,10 +3388,11 @@
                         <literal>NDB_MGM_EVENT_SEVERITY_ERROR</literal>.
                         The first element (position
                         <literal>NDB_MGM_EVENT_SEVERITY_ON</literal>) in
-                        the vector signals whether the cluster log is disabled or
enabled.
+                        the vector signals whether the cluster log is
+                        disabled or enabled.
                       </para>
                     </listitem>
-                    
+
                     <listitem>
                       <para>
                         The <replaceable>size</replaceable> of the

@@ -3393,10 +3400,11 @@
                         (<literal>NDB_MGM_EVENT_SEVERITY_ALL</literal>).
                       </para>
                     </listitem>
+
                   </itemizedlist>
-                  
                 </para>
               </listitem>
+
             </itemizedlist>
           </para>
 

@@ -3409,13 +3417,14 @@
           <para>
             This function's return type changed beginning with MySQL
             5.1.14.
-            
+
             <itemizedlist>
+
               <listitem>
                 <para>
                   <emphasis>MySQL 5.1.13 and earlier</emphasis>:
                 </para>
-                
+
                 <para>
                   A <firstterm>severity filter</firstterm>, which is a
                   vector containing 7 elements. Each element equals

@@ -3428,20 +3437,21 @@
                   <literal>NDB_MGM_EVENT_SEVERITY_ERROR</literal>. The
                   first element in the vector
                   (<literal>NDB_MGM_EVENT_SEVERITY_ON</literal>) signals
-                  whether the cluster log is enabled or disabled. 
+                  whether the cluster log is enabled or disabled.
                 </para>
               </listitem>
-              
+
               <listitem>
                 <para>
                   <emphasis>MySQL 5.1.14 and later</emphasis>:
                 </para>
-                
+
                 <para>
                   The number of returned severities, or
                   <literal>-1</literal> in the event of an error.
                 </para>
               </listitem>
+
             </itemizedlist>
           </para>
 

@@ -3570,6 +3580,138 @@
 
       </section>
 
+      <section id="mgm-mgm-get-clusterlog-loglevel">
+
+       
<title><literal>ndb_mgm_get_clusterlog_loglevel()</literal></title>
+
+        <indexterm>
+          <primary><literal>ndb_mgm_get_clusterlog_loglevel()</literal>
function (MGM API)</primary>
+        </indexterm>
+
+        <indexterm>
+          <primary><literal>ndb_mgm_get_loglevel_clusterlog()</literal>
function (MGM API)
+            - DEPRECATED</primary>
+        </indexterm>
+
+        <formalpara>
+
+          <title>Description</title>
+
+          <para>
+            This function, added in MySQL 5.1.14, is used to obtain log
+            category and level information. It replaces the older
+            <literal>ndb_mgm_get_loglevel_clusterlog()</literal>
+            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.)
+          </para>
+
+        </formalpara>
+
+        <formalpara>
+
+          <title>Signature</title>
+
+          <para>
+<programlisting>
+int ndb_mgm_get_clusterlog_loglevel
+    (
+      NdbMgmHandle <replaceable>handle</replaceable>,
+      struct ndb_mgm_loglevel* <replaceable>loglevel</replaceable>,
+      unsigned int <replaceable>size</replaceable>
+    )
+</programlisting>
+          </para>
+
+        </formalpara>
+
+        <formalpara>
+
+          <title>Parameters</title>
+
+          <para>
+            <literal>ndb_mgm_get_clusterlog_loglevel()</literal> takes
+            the following parameters:
+
+            <itemizedlist>
+
+              <listitem>
+                <para>
+                  A management <replaceable>handle</replaceable>
+                  (<literal>NdbMgmHandle</literal>).
+                </para>
+              </listitem>
+
+              <listitem>
+                <para>
+                  A <replaceable>loglevel</replaceable> (log level)
+                  vector consisting of twelve elements, each of which is
+                  an <literal>ndb_mgm_loglevel</literal> structure and
+                  which represents a log level of the corresponding
+                  category.
+                </para>
+              </listitem>
+
+              <listitem>
+                <para>
+                  The <replaceable>size</replaceable> of the vector
+                  (<literal>MGM_LOGLEVELS</literal>).
+                </para>
+              </listitem>
+
+            </itemizedlist>
+          </para>
+
+        </formalpara>
+
+        <formalpara>
+
+          <title>Return Value</title>
+
+          <para>
+            This function returns the number of returned loglevels or
+            <literal>-1</literal> in the event of an error.
+          </para>
+
+        </formalpara>
+
+        <note>
+          <para>
+            Prior to MySQL 5.1.14, this function was known as
+            <literal>ndb_mgm_get_loglevel_clusterlog()</literal>, and
+            had the following signature:
+
+<programlisting>
+const unsigned int* ndb_mgm_get_loglevel_clusterlog
+    (
+      NdbMgmHandle <replaceable>handle</replaceable>
+    )
+</programlisting>
+
+            This version of the function is now deprecated, but is still
+            available for backwards compatibility; however, in new
+            applications, it is recommended that you use
+            <literal>ndb_mgm_get_clusterlog_loglevel()</literal>, since
+            it is thread-safe, and the older function is not.
+          </para>
+        </note>
+
+<!--        
+  <formalpara>
+
+    <title>Example</title>
+
+    <para>
+<programlisting>
+[<emphasis>To be supplied...</emphasis>]
+</programlisting>
+    </para>
+
+  </formalpara>
+-->
+
+      </section>
+
       <section id="ndb-mgm-set-clusterlog-loglevel">
 
        
<title><literal>ndb_mgm_set_clusterlog_loglevel()</literal></title>