List:Commits« Previous MessageNext Message »
From:jon.stephens Date:March 13 2009 2:05pm
Subject:svn commit - mysqldoc@docsrva: r14210 - in trunk/ndbapi: . images/published images/source/xmi
View as plain text  
Author: jstephens
Date: 2009-03-13 15:05:12 +0100 (Fri, 13 Mar 2009)
New Revision: 14210

Log:

1. Part of work needed to document fix for Cluster Bugs #37934/#43268:

  New pruning-aware variant of NdbIndexScanOperation::setBound()

  New Ndb::PartitionSpec struct

  Updated NdbIndexScanOperation class diagram

2. API docs maintenance/fixes/improvements:

  Previously undocumented Ndb::computeHash() method

  Added newer variants of Ndb::startTransaction() method

  Fixed/updated Ndb class diagram

  Moved out Ndb::Key_part-Ptr struct into own file/section (although
  defined in Ndb.hpp, seems it's used by methods from multiple classes)

  Updated object hierarchy listing page

  Rebuilt deps



Added:
   trunk/ndbapi/struct-key-part-ptr.xml
   trunk/ndbapi/struct-partitionspec.xml
Modified:
   trunk/ndbapi/Makefile.depends
   trunk/ndbapi/class-ndb.xml
   trunk/ndbapi/class-ndbindexscanoperation.xml
   trunk/ndbapi/images/published/Ndb-class.png
   trunk/ndbapi/images/published/NdbIndexScanOperation-class.png
   trunk/ndbapi/images/source/xmi/Ndb.xmi.tgz
   trunk/ndbapi/images/source/xmi/NdbIndexScanOperation.xmi.tgz
   trunk/ndbapi/interface-ndbrecord.xml
   trunk/ndbapi/ndb-classes.xml
   trunk/ndbapi/ndb-hierarchy.xml


Modified: trunk/ndbapi/Makefile.depends
===================================================================
--- trunk/ndbapi/Makefile.depends	2009-03-13 02:19:13 UTC (rev 14209)
+++ trunk/ndbapi/Makefile.depends	2009-03-13 14:05:12 UTC (rev 14210)
Changed blocks: 10, Lines Added: 55, Lines Deleted: 1; 6216 bytes

@@ -222,6 +222,7 @@
 	../ndbapi/metadata/class-table.idmap \
 	../ndbapi/metadata/ndb-errors.idmap \
 	../ndbapi/metadata/ndb-internals.idmap \
+	../ndbapi/metadata/struct-key-part-ptr.idmap \
 	../ndbapi/metadata/struct-ndberror.idmap
 class-ndb.validpure: $(class_ndb_SOURCES)
 class-ndb.titles: $(class_ndb_SOURCES)

@@ -351,7 +352,8 @@
 	../ndbapi/metadata/class-ndbscanoperation.idmap \
 	../ndbapi/metadata/interface-ndbrecord.idmap \
 	../ndbapi/metadata/overview.idmap \
-	../ndbapi/metadata/struct-indexbound.idmap
+	../ndbapi/metadata/struct-indexbound.idmap \
+	../ndbapi/metadata/struct-partitionspec.idmap
 class-ndbindexscanoperation.validpure: $(class_ndbindexscanoperation_SOURCES)
 class-ndbindexscanoperation.titles: $(class_ndbindexscanoperation_SOURCES)
 class-ndbindexscanoperation.useless: $(class_ndbindexscanoperation_SOURCES)

@@ -655,9 +657,11 @@
 interface_ndbrecord_SOURCES = interface-ndbrecord.xml $(interface_ndbrecord_INCLUDES)
 interface_ndbrecord_IDMAPS = \
 	../ndbapi/metadata/class-dictionary.idmap \
+	../ndbapi/metadata/class-ndbindexscanoperation.idmap \
 	../ndbapi/metadata/class-ndbscanoperation.idmap \
 	../ndbapi/metadata/class-ndbtransaction.idmap \
 	../ndbapi/metadata/struct-indexbound.idmap \
+	../ndbapi/metadata/struct-partitionspec.idmap \
 	../ndbapi/metadata/struct-recordspecification.idmap
 interface-ndbrecord.validpure: $(interface_ndbrecord_SOURCES)
 interface-ndbrecord.titles: $(interface_ndbrecord_SOURCES)

@@ -763,7 +767,9 @@
 	struct-autogrowspecification.xml \
 	struct-element.xml \
 	struct-indexbound.xml \
+	struct-key-part-ptr.xml \
 	struct-ndberror.xml \
+	struct-partitionspec.xml \
 	struct-recordspecification.xml
 ndb_classes_IMAGES = \
 	images/published/Ndb-class.png \

@@ -830,7 +836,9 @@
 	../ndbapi/metadata/struct-autogrowspecification.idmap \
 	../ndbapi/metadata/struct-element.idmap \
 	../ndbapi/metadata/struct-indexbound.idmap \
+	../ndbapi/metadata/struct-key-part-ptr.idmap \
 	../ndbapi/metadata/struct-ndberror.idmap \
+	../ndbapi/metadata/struct-partitionspec.idmap \
 	../ndbapi/metadata/struct-recordspecification.idmap \
 	../refman-5.1/metadata/apis-c.idmap \
 	../refman-5.1/metadata/data-types.idmap \

@@ -958,7 +966,9 @@
 	../ndbapi/metadata/struct-autogrowspecification.idmap \
 	../ndbapi/metadata/struct-element.idmap \
 	../ndbapi/metadata/struct-indexbound.idmap \
+	../ndbapi/metadata/struct-key-part-ptr.idmap \
 	../ndbapi/metadata/struct-ndberror.idmap \
+	../ndbapi/metadata/struct-partitionspec.idmap \
 	../ndbapi/metadata/struct-recordspecification.idmap
 ndb-hierarchy.validpure: $(ndb_hierarchy_SOURCES)
 ndb-hierarchy.titles: $(ndb_hierarchy_SOURCES)

@@ -1097,7 +1107,9 @@
 	struct-autogrowspecification.xml \
 	struct-element.xml \
 	struct-indexbound.xml \
+	struct-key-part-ptr.xml \
 	struct-ndberror.xml \
+	struct-partitionspec.xml \
 	struct-recordspecification.xml
 ndbapi_IMAGES = \
 	images/published/Ndb-class.png \

@@ -1175,7 +1187,9 @@
 	../ndbapi/metadata/struct-autogrowspecification.idmap \
 	../ndbapi/metadata/struct-element.idmap \
 	../ndbapi/metadata/struct-indexbound.idmap \
+	../ndbapi/metadata/struct-key-part-ptr.idmap \
 	../ndbapi/metadata/struct-ndberror.idmap \
+	../ndbapi/metadata/struct-partitionspec.idmap \
 	../ndbapi/metadata/struct-recordspecification.idmap \
 	../refman-5.1/metadata/apis-c.idmap \
 	../refman-5.1/metadata/data-types.idmap \

@@ -1303,6 +1317,25 @@
 struct-indexbound-manprepped.xml: $(struct_indexbound_SOURCES) $(struct_indexbound_IDMAPS)
 struct-indexbound-remprepped.xml: $(struct_indexbound_SOURCES) $(struct_indexbound_IDMAPS)
 
+struct_key_part_ptr_INCLUDES = \
+	../common/fixedchars.ent \
+	../common/phrases.ent \
+	../refman-common/urls.ent \
+	all-entities.ent \
+	ndb.en.ent
+struct_key_part_ptr_IMAGES =
+struct_key_part_ptr_SOURCES = struct-key-part-ptr.xml $(struct_key_part_ptr_INCLUDES)
+struct_key_part_ptr_IDMAPS = \
+	../ndbapi/metadata/class-ndb.idmap
+struct-key-part-ptr.validpure: $(struct_key_part_ptr_SOURCES)
+struct-key-part-ptr.titles: $(struct_key_part_ptr_SOURCES)
+struct-key-part-ptr.useless: $(struct_key_part_ptr_SOURCES)
+struct-key-part-ptr.valid: $(struct_key_part_ptr_SOURCES) $(struct_key_part_ptr_IDMAPS)
+struct-key-part-ptr.validwarn: $(struct_key_part_ptr_SOURCES) $(struct_key_part_ptr_IDMAPS)
+struct-key-part-ptr-prepped.xml: $(struct_key_part_ptr_SOURCES) $(struct_key_part_ptr_IDMAPS)
+struct-key-part-ptr-manprepped.xml: $(struct_key_part_ptr_SOURCES) $(struct_key_part_ptr_IDMAPS)
+struct-key-part-ptr-remprepped.xml: $(struct_key_part_ptr_SOURCES) $(struct_key_part_ptr_IDMAPS)
+
 struct_ndberror_INCLUDES = \
 	../common/fixedchars.ent \
 	../common/phrases.ent \

@@ -1327,6 +1360,27 @@
 struct-ndberror-manprepped.xml: $(struct_ndberror_SOURCES) $(struct_ndberror_IDMAPS)
 struct-ndberror-remprepped.xml: $(struct_ndberror_SOURCES) $(struct_ndberror_IDMAPS)
 
+struct_partitionspec_INCLUDES = \
+	../common/fixedchars.ent \
+	../common/phrases.ent \
+	../refman-common/urls.ent \
+	all-entities.ent \
+	ndb.en.ent
+struct_partitionspec_IMAGES =
+struct_partitionspec_SOURCES = struct-partitionspec.xml $(struct_partitionspec_INCLUDES)
+struct_partitionspec_IDMAPS = \
+	../ndbapi/metadata/class-ndb.idmap \
+	../ndbapi/metadata/interface-ndbrecord.idmap \
+	../ndbapi/metadata/struct-key-part-ptr.idmap
+struct-partitionspec.validpure: $(struct_partitionspec_SOURCES)
+struct-partitionspec.titles: $(struct_partitionspec_SOURCES)
+struct-partitionspec.useless: $(struct_partitionspec_SOURCES)
+struct-partitionspec.valid: $(struct_partitionspec_SOURCES) $(struct_partitionspec_IDMAPS)
+struct-partitionspec.validwarn: $(struct_partitionspec_SOURCES) $(struct_partitionspec_IDMAPS)
+struct-partitionspec-prepped.xml: $(struct_partitionspec_SOURCES) $(struct_partitionspec_IDMAPS)
+struct-partitionspec-manprepped.xml: $(struct_partitionspec_SOURCES) $(struct_partitionspec_IDMAPS)
+struct-partitionspec-remprepped.xml: $(struct_partitionspec_SOURCES) $(struct_partitionspec_IDMAPS)
+
 struct_recordspecification_INCLUDES = \
 	../common/fixedchars.ent \
 	../common/phrases.ent \


Modified: trunk/ndbapi/class-ndb.xml
===================================================================
--- trunk/ndbapi/class-ndb.xml	2009-03-13 02:19:13 UTC (rev 14209)
+++ trunk/ndbapi/class-ndb.xml	2009-03-13 14:05:12 UTC (rev 14210)
Changed blocks: 13, Lines Added: 198, Lines Deleted: 39; 11723 bytes

@@ -147,6 +147,10 @@
           <entry>Closes a transaction.</entry>
         </row>
         <row>
+          <entry><literal><link linkend="class-ndb-computehash">computeHash()</link></literal></entry>
+          <entry>Computes a distribution hash value.</entry>
+        </row>
+        <row>
           <entry><literal><link linkend="class-ndb-createeventoperation">createEventOperation()</link></literal></entry>
           <entry>Creates a subscription to a database event. (See
             <xref linkend="class-ndbeventoperation"/>.)</entry>

@@ -182,12 +186,12 @@
     <title>Class diagram</title>
 
     <para>
-      This diagram shows all the available methods of the
+      This diagram shows all the available members of the
       <literal>Ndb</literal> class:
 
       <mediaobject>
         <imageobject>
-          <imagedata contentwidth="540" contentdepth="360" fileref="images/published/Ndb-class.png" format="PNG"/>
+          <imagedata contentwidth="660" contentdepth="770" fileref="images/published/Ndb-class.png" format="PNG"/>
         </imageobject>
         <textobject>
           <phrase lang="en">Public methods of the <literal>Ndb</literal>

@@ -869,7 +873,11 @@
         <title>Description</title>
 
         <para>
-          This method is used to begin a new transaction.
+          This method is used to begin a new transaction. There are
+          three variants, the simplest of these using a table and a
+          partition key or partition ID to specify the transaction
+          coordinator (TC). The third variant allows you to specify the
+          TC by means of a pointer to the data of the key.
         </para>
 
       </formalpara>

@@ -897,9 +905,9 @@
 <programlisting>
 NdbTransaction* startTransaction
     (
-      const NdbDictionary::Table *<replaceable>table</replaceable> = 0,
-      const char                 *<replaceable>keyData</replaceable> = 0,
-      Uint32                     *<replaceable>keyLen</replaceable> = 0
+      const NdbDictionary::Table* <replaceable>table</replaceable> = 0,
+      const char* <replaceable>keyData</replaceable> = 0,
+      Uint32* <replaceable>keyLen</replaceable> = 0
     )
 </programlisting>
         </para>

@@ -947,15 +955,13 @@
 
       <formalpara>
 
-        <title>Distribution-aware form of <literal>startTransaction()</literal></title>
+        <title>Distribution-aware forms of <literal>startTransaction()</literal></title>
 
         <para>
           Beginning with MySQL Cluster NDB 6.1.4, it is possible to
           employ <firstterm>distribution awareness</firstterm> with this
           method &mdash; that is, to suggest which node should act as
-          the transaction coordinator. When
-          <literal>startTransaction()</literal> is used in this way, it
-          takes 4 arguments, as shown in the following paragraphs.
+          the transaction coordinator &mdash; .
         </para>
 
       </formalpara>

@@ -968,9 +974,9 @@
 <programlisting>
 NdbTransaction* startTransaction
     (
-      const NdbDictionary::Table *<replaceable>table</replaceable>,
-      const struct Key_part_ptr  *<replaceable>keyData</replaceable>,
-      void                       *<replaceable>xfrmbuf</replaceable> = 0,
+      const NdbDictionary::Table* <replaceable>table</replaceable>,
+      const struct Key_part_ptr*  <replaceable>keyData</replaceable>,
+      void*                       <replaceable>xfrmbuf</replaceable> = 0,
       Uint32                      <replaceable>xfrmbuflen</replaceable> = 0
     )
 </programlisting>

@@ -1005,16 +1011,8 @@
               </para>
 
               <para>
-                A <literal>Key_part_ptr</literal> is defined as shown
-                here:
-
-<programlisting>
-struct Key_part_ptr
-    {
-      const void *<replaceable>ptr</replaceable>;
-      unsigned    <replaceable>len</replaceable>;
-    }
-</programlisting>
+                A <literal>Key_part_ptr</literal> is defined as shown in
+                <xref linkend="struct-key-part-ptr"/>.
               </para>
             </listitem>
 

@@ -1049,7 +1047,7 @@
         <title>Example</title>
 
         <para>
-          Suppose that the table&apos;s partition key is single
+          Suppose that the table&apos;s partition key is a single
           <literal>BIGINT</literal> column. Then you would declare the
           distribution key array as shown here:
 

@@ -1074,7 +1072,7 @@
           The length of this pointer would be set accordingly:
 
 <programlisting>
-distkey[0].len=sizeof(distkeyValue);
+distkey[0].len= sizeof(distkeyValue);
 </programlisting>
 
           The distribution key array must terminate with a

@@ -1083,8 +1081,8 @@
           in the distribution key:
 
 <programlisting>
-distkey[1].ptr=NULL;
-distkey[1].len=NULL;
+distkey[1].ptr= NULL;
+distkey[1].len= NULL;
 </programlisting>
 
           Setting the buffer to <literal>NULL</literal> allows

@@ -1092,8 +1090,8 @@
           memory automatically:
 
 <programlisting>
-           xfrmbuf=NULL
-           xfrmbuflen=0
+xfrmbuf= NULL;
+xfrmbuflen= 0;
 </programlisting>
 
           <note>

@@ -1101,25 +1099,42 @@
               You can also specify a buffer to save having to make
               explicit <literal>malloc()</literal> and
               <literal>free()</literal> calls, but calculating an
-              appropriate size for this buffer is not a simple matter.
-              However, if you choose to specify the buffer, 1 MB is
-              usually sufficient for its size.
+              appropriate size for this buffer is not a simple matter;
+              if the buffer is not <literal>NULL</literal> but its
+              length is too short, then the startTransaction() call
+              fails. However, if you choose to specify the buffer, 1 MB
+              is usually a sufficient size.
             </para>
           </note>
 
-          Now, when you start the transaction, you access the node that
-          contains the desired information directly.
+          Now, when you start the transaction, you can access the node
+          that contains the desired information directly.
         </para>
 
       </formalpara>
 
       <para>
+        In MySQL Cluster NDB 6.2 and later, another distribution-aware
+        version of this method is available. This variant allows you to
+        specify a table and partition (using the partition ID) as a hint
+        for selecting the transaction coordinator, and is defined as
+        shown here:
+
+<programlisting>
+NdbTransaction* startTransaction
+    (
+      const NdbDictionary::Table* <replaceable>table</replaceable>,
+      Uint32 <replaceable>partitionId</replaceable>
+    )
+</programlisting>
+      </para>
+
+      <para>
         In the event that the cluster has the same number of data nodes
-        as it has replicas, there is no difference in performance
-        between the two versions of
-        <literal>startTransaction()</literal>, since each data node
-        contains the entire database. However, where the number of data
-        nodes is greater than the number of replicas (for example, where
+        as it has replicas, specifying the transaction coordinator gains
+        no improvement in performance, since each data node contains the
+        entire database. However, where the number of data nodes is
+        greater than the number of replicas (for example, where
         <literal>NoOfReplicas</literal> is set equal to 2 in a cluster
         with 4 data nodes), you should see a marked improvement in
         performance by using the distribution-aware version of this

@@ -1256,6 +1271,150 @@
 
     </section>
 
+    <section id="class-ndb-computehash">
+
+      <title><literal>Ndb::computeHash()</literal></title>
+
+      <indexterm>
+        <primary>Ndb::computeHash()</primary>
+      </indexterm>
+
+      <indexterm>
+        <primary>computeHash() (method of Ndb)</primary>
+      </indexterm>
+
+      <formalpara>
+
+        <title>Description</title>
+
+        <para>
+          This method can be used to compute a distribution hash value,
+          given a table and its keys.
+        </para>
+
+      </formalpara>
+
+      <important>
+        <para>
+          <literal>computeHash()</literal> can be used onlyt for tables
+          that use native NDB partitioning.
+        </para>
+      </important>
+
+      <formalpara>
+
+        <title>Signature</title>
+
+        <para>
+<programlisting>
+static int computeHash
+    (
+      Uint32*                     <replaceable>hashvalueptr</replaceable>,
+      const NdbDictionary::Table* <replaceable>table</replaceable>, 
+      const struct Key_part_ptr*  <replaceable>keyData</replaceable>,
+      void*                       <replaceable>xfrmbuf</replaceable> = 0, 
+      Uint32                      <replaceable>xfrmbuflen</replaceable> = 0
+    )
+</programlisting>
+        </para>
+
+      </formalpara>
+
+      <formalpara>
+
+        <title>Parameters</title>
+
+        <para>
+          This method takes the following parameters:
+
+          <itemizedlist>
+
+            <listitem>
+              <para>
+                If the method call id successful,
+                <replaceable>hashvalueptr</replaceable> is set to the
+                computed hash value.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                A pointer to a <replaceable>table</replaceable> (see
+                <xref linkend="class-table"/>).
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                <replaceable>keyData</replaceable> is a null-terminated
+                array of pointers to the key parts that are part of the
+                table&apos;s distribution key. The length of each key
+                part is read from metadata and checked against the
+                passed value (see
+                <xref linkend="struct-key-part-ptr"/>).
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                <replaceable>xfrmbuf</replaceable> is a pointer to
+                temporary buffer used to calculate the hash value.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                <replaceable>xfrmbuflen</replaceable> is the length of
+                this buffer.
+              </para>
+
+              <note>
+                <para>
+                  If <replaceable>xfrmbuf</replaceable> is
+                  <literal>NULL</literal> (the default), then a call to
+                  <literal>malloc()</literal> or
+                  <literal>free()</literal> is made automatically, as
+                  appropriate. <literal>computeHash()</literal> fails if
+                  <literal>xfrmbuf</literal> is not
+                  <literal>NULL</literal> and
+                  <replaceable>xfrmbuflen</replaceable> is too small.
+                </para>
+              </note>
+            </listitem>
+
+          </itemizedlist>
+        </para>
+
+      </formalpara>
+
+      <formalpara>
+
+        <title>Return Value</title>
+
+        <para>
+          0 on success, an error code on failure. (If the method call
+          succeeds, the computed hash value is made available via
+          <replaceable>hashvalueptr</replaceable>.)
+        </para>
+
+      </formalpara>
+
+<!--
+      <formalpara>
+        
+        <title>Example</title>
+        
+        <para>
+<programlisting>
+[<emphasis>To be supplied...</emphasis>]
+</programlisting>
+        </para>
+        
+      </formalpara>
+-->
+
+    </section>
+
     <section id="class-ndb-createeventoperation">
 
       <title><literal>Ndb::createEventOperation</literal></title>


Modified: trunk/ndbapi/class-ndbindexscanoperation.xml
===================================================================
--- trunk/ndbapi/class-ndbindexscanoperation.xml	2009-03-13 02:19:13 UTC (rev 14209)
+++ trunk/ndbapi/class-ndbindexscanoperation.xml	2009-03-13 14:05:12 UTC (rev 14210)
Changed blocks: 5, Lines Added: 183, Lines Deleted: 10; 7311 bytes

@@ -155,7 +155,7 @@
 
       <mediaobject>
         <imageobject>
-          <imagedata contentwidth="465" contentdepth="308" fileref="images/published/NdbIndexScanOperation-class.png" format="PNG"/>
+          <imagedata contentwidth="670" contentdepth="338" fileref="images/published/NdbIndexScanOperation-class.png" format="PNG"/>
         </imageobject>
         <textobject>
           <phrase lang="en">Public members of the

@@ -632,18 +632,27 @@
 
         <para>
           This method defines a bound on an index key used in a range
-          scan.
+          scan. In MySQL Cluster NDB 6.2.3 and later, it is also sets
+          bounds for index scans defined using
+          <literal>NdbRecord</literal>.
         </para>
 
       </formalpara>
 
-      <para>
-        Each index key can have a lower bound, upper bound, or both.
-        Setting the key equal to a value defines both upper and lower
-        bounds. Bounds can be defined in any order. Conflicting
-        definitions gives rise to an error.
-      </para>
+      <formalpara>
 
+        <title><quote>Old</quote> API usage (prior to introduction of
+          <literal>NdbRecord</literal>)</title>
+
+        <para>
+          Each index key can have a lower bound, upper bound, or both.
+          Setting the key equal to a value defines both upper and lower
+          bounds. Bounds can be defined in any order. Conflicting
+          definitions gives rise to an error.
+        </para>
+
+      </formalpara>
+
       <para>
         Bounds must be set on initial sequences of index keys, and all
         but possibly the last bound must be non-strict. This means, for

@@ -683,7 +692,7 @@
 
       <formalpara>
 
-        <title>Signature</title>
+        <title>Signature (<quote>Old</quote> API)</title>
 
         <para>
 <programlisting>

@@ -711,7 +720,7 @@
 
       <formalpara>
 
-        <title>Parameters</title>
+        <title>Parameters (<quote>Old</quote> API)</title>
 
         <para>
           This method takes 3 parameters:

@@ -747,6 +756,170 @@
 
       <formalpara>
 
+        <title>As used with <literal>NdbRecord</literal> (MySQL Cluster NDB 6.2.3 and
+          later)</title>
+
+        <para>
+          This method is called to add a range to an
+          <literal>IndexScan</literal> operation which has been defined
+          with a call to <literal>NdbTransaction::scanIndex()</literal>.
+          To add more than one range, the index scan operation must have
+          been defined with the <literal>SF_MultiRange</literal> flag
+          set. (See <xref linkend="class-ndbscanoperation-scanflag"/>.)
+        </para>
+
+      </formalpara>
+
+      <note>
+        <para>
+          Where multiple numbered ranges are defined with multiple calls
+          to <literal>setBound()</literal>, and the scan is ordered, the
+          range number for each range must be larger than the range
+          number for the previously defined range.
+        </para>
+      </note>
+
+      <formalpara>
+
+        <title>Signature (when used with <literal>NdbRecord</literal>)</title>
+
+        <para>
+          MySQL Cluster NDB 6.2.3 and later:
+
+<programlisting>
+int setBound
+    (
+      const NdbRecord* <replaceable>keyRecord</replaceable>,
+      const IndexBound&amp; <replaceable>bound</replaceable>
+    )          
+</programlisting>
+        </para>
+
+      </formalpara>
+
+      <formalpara>
+
+        <title>Parameters</title>
+
+        <para>
+          As used with <literal>NdbRecord</literal> in MySQL Cluster NDB
+          6.2.3 and later, this method takes 2 parameters:
+
+          <itemizedlist>
+
+            <listitem>
+              <para>
+                <replaceable>keyRecord</replaceable>: This is an
+                <literal>NdbRecord</literal> structure corresponding to
+                the key on which the index is defined.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                The <replaceable>bound</replaceable> to add (see
+                <xref linkend="struct-indexbound"/>).
+              </para>
+            </listitem>
+
+          </itemizedlist>
+        </para>
+
+      </formalpara>
+
+      <para>
+        Starting with MySQL Cluster NDB 6.3.24 and NDB 7.0.4, an
+        additional version of this method is available, which can be
+        used when the application knows that rows in-range will be found
+        only within a particular partition. This is the same as that
+        shown previously, except for the addition of a
+        <literal>PartitionSpecification</literal>. Doing so limits the
+        scan to a single partition, improving system efficiency.
+      </para>
+
+      <formalpara>
+
+        <title>Signature (when specifying a partition)</title>
+
+        <para>
+<programlisting>
+int setBound
+    (
+      const NdbRecord* <replaceable>keyRecord</replaceable>,
+      const IndexBound&amp; <replaceable>bound</replaceable>,
+      const Ndb::PartitionSpec* <replaceable>partInfo</replaceable>,
+      Uint32 <replaceable>sizeOfPartInfo</replaceable> = 0
+    )
+</programlisting>
+        </para>
+
+      </formalpara>
+
+      <formalpara>
+
+        <title>Parameters (when specifying a partition)</title>
+
+        <para>
+          Beginning with MySQL Cluster NDB 6.3.24 and MySQL Cluster NDB
+          7.0.4, this method can be invoked with the following 4
+          parameters:
+
+          <itemizedlist>
+
+            <listitem>
+              <para>
+                <replaceable>keyRecord</replaceable>: This is an
+                <literal>NdbRecord</literal> structure (see
+                <xref linkend="interface-ndbrecord"/>) corresponding to
+                the key on which the index is defined.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                The <replaceable>bound</replaceable> to be added to the
+                scan (see <xref linkend="struct-indexbound"/>).
+              </para>
+            </listitem>
+
+          </itemizedlist>
+
+          <note>
+            <para>
+              <replaceable>keyRecord</replaceable> and
+              <replaceable>bound</replaceable> are defined and used in
+              the same way as with the 2-parameter version of this
+              method.
+            </para>
+          </note>
+
+          <itemizedlist>
+
+            <listitem>
+              <para>
+                <replaceable>partInfo</replaceable>: This is a pointer
+                to an <literal>Ndb::PartitionSpec</literal>, which
+                provides extra information making it possible to scan a
+                reduced set of partitions. See
+                <xref linkend="struct-partitionspec"/>, for more
+                information.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                <replaceable>sizeOfPartInfo</replaceable>: The length of
+                the partition specification.
+              </para>
+            </listitem>
+
+          </itemizedlist>
+        </para>
+
+      </formalpara>
+
+      <formalpara>
+
         <title>Return Value</title>
 
         <para>


Modified: trunk/ndbapi/images/published/Ndb-class.png
===================================================================


Changed blocks: 0, Lines Added: 0, Lines Deleted: 0; 141 bytes


Modified: trunk/ndbapi/images/published/NdbIndexScanOperation-class.png
===================================================================


Changed blocks: 0, Lines Added: 0, Lines Deleted: 0; 159 bytes


Modified: trunk/ndbapi/images/source/xmi/Ndb.xmi.tgz
===================================================================


Changed blocks: 0, Lines Added: 0, Lines Deleted: 0; 140 bytes


Modified: trunk/ndbapi/images/source/xmi/NdbIndexScanOperation.xmi.tgz
===================================================================


Changed blocks: 0, Lines Added: 0, Lines Deleted: 0; 158 bytes


Modified: trunk/ndbapi/interface-ndbrecord.xml
===================================================================
--- trunk/ndbapi/interface-ndbrecord.xml	2009-03-13 02:19:13 UTC (rev 14209)
+++ trunk/ndbapi/interface-ndbrecord.xml	2009-03-13 14:05:12 UTC (rev 14210)
Changed blocks: 2, Lines Added: 11, Lines Deleted: 2; 1314 bytes

@@ -58,8 +58,8 @@
     by calling the <literal>createRecord()</literal> method of the
     <literal>NdbDictionary</literal> class. In addition, a number of NDB
     API methods have additional declarations in MySQL Cluster NDB 6.2.3
-    and later MySQL Cluster NDB 6.x releases that allow the programmer
-    to leverage <literal>NdbRecord</literal>:
+    and later MySQL Cluster releases that allow the programmer to
+    leverage <literal>NdbRecord</literal>:
 
     <itemizedlist>
 

@@ -166,6 +166,15 @@
       </listitem>
 
     </itemizedlist>
+
+    Beginning with MySQL Cluster NDB 6.3.24 and MySQL Cluster NDB 7.0.4,
+    you can also use <literal>NdbRecord</literal> in conjunction with
+    the new <literal>Ndb::PartitionSpec</literal> structure to perform
+    scans that take advantage of partition pruning, by means of a new
+    variant of <literal>NdbIndexScanOperation::setBound()</literal>. For
+    more information, see
+    <xref linkend="class-ndbindexscanoperation-setbound"/>, and
+    <xref linkend="struct-partitionspec"/>.
   </para>
 
 </section>


Modified: trunk/ndbapi/ndb-classes.xml
===================================================================
--- trunk/ndbapi/ndb-classes.xml	2009-03-13 02:19:13 UTC (rev 14209)
+++ trunk/ndbapi/ndb-classes.xml	2009-03-13 14:05:12 UTC (rev 14210)
Changed blocks: 1, Lines Added: 4, Lines Deleted: 0; 730 bytes

@@ -124,8 +124,12 @@
 
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="struct-indexbound.xml"/>
 
+  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="struct-key-part-ptr.xml"/>
+
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="struct-ndberror.xml"/>
 
+  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="struct-partitionspec.xml"/>
+
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="struct-recordspecification.xml"/>
 
 </section>


Modified: trunk/ndbapi/ndb-hierarchy.xml
===================================================================
--- trunk/ndbapi/ndb-hierarchy.xml	2009-03-13 02:19:13 UTC (rev 14209)
+++ trunk/ndbapi/ndb-hierarchy.xml	2009-03-13 14:05:12 UTC (rev 14210)
Changed blocks: 1, Lines Added: 16, Lines Deleted: 0; 817 bytes

@@ -18,6 +18,22 @@
       <listitem>
         <para>
           <link linkend="class-ndb"><literal>Ndb</literal></link>
+
+          <itemizedlist>
+
+            <listitem>
+              <para>
+                <link linkend="struct-key-part-ptr"><literal>Key_part_ptr</literal></link>
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                <link linkend="struct-partitionspec"><literal>PartitionSpec</literal></link>
+              </para>
+            </listitem>
+
+          </itemizedlist>
         </para>
       </listitem>
 


Added: trunk/ndbapi/struct-key-part-ptr.xml
===================================================================
--- trunk/ndbapi/struct-key-part-ptr.xml	                        (rev 0)
+++ trunk/ndbapi/struct-key-part-ptr.xml	2009-03-13 14:05:12 UTC (rev 14210)
Changed blocks: 1, Lines Added: 83, Lines Deleted: 0; 2910 bytes

@@ -0,0 +1,83 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+<!ENTITY % all.entities SYSTEM "all-entities.ent">
+%all.entities;
+]>
+<section id="struct-key-part-ptr">
+  <title>The <literal>Key_part_ptr</literal> Structure</title>
+  
+  <indexterm>
+    <primary>Ndb::Key_part_ptr structure</primary>
+  </indexterm>
+  
+  <indexterm>
+    <primary>Key_part_ptr (Ndb structure)</primary>
+  </indexterm>
+  <abstract>
+  <para>
+    This section describes the <literal>Key_part_ptr</literal> structure.
+  </para></abstract>
+  
+  
+  <formalpara>
+    
+    <title>Parent class</title>
+    
+    <para>
+      <link linkend="class-ndb">Ndb</link>
+    </para>
+    
+  </formalpara><formalpara>
+    <title>Description</title>
+  <para>
+    <literal>Key_part_ptr</literal> provides a convenient way to define
+    key-part data when starting transactions and computing hash values, by
+    passing in pointers to distribution key values. When the distribution key
+    has multiple parts, they should be passed as an array, with the last
+    part&apos;s pointer set equal to <literal>NULL</literal>. See 
+    <xref linkend="class-ndb-starttransaction"/>, and 
+    <xref linkend="class-ndb-computehash"/>, for more information about how this
+    structure is used.
+  </para></formalpara>
+  <formalpara>
+    
+    <title>Attributes</title>
+    
+    <para>
+      A <literal>Key_part_ptr</literal> has the attributes shown in the
+      following table:
+      
+      <informaltable>
+        <tgroup cols="4">
+          <colspec colwidth="25*"/>
+          <colspec colwidth="25*"/>
+          <colspec colwidth="25*"/>
+          <colspec colwidth="25*"/>
+          <thead>
+            <row>
+              <entry>Attribute</entry>
+              <entry>Type</entry>
+              <entry>Initial Value</entry>
+              <entry>Description</entry>
+            </row>
+          </thead>
+          <tbody>
+            <row>
+              <entry><literal>ptr</literal></entry>
+              <entry><literal>const void*</literal></entry>
+              <entry><emphasis>none</emphasis></entry>
+              <entry>Pointer to one or more distribution key values</entry>
+            </row>
+            <row>
+              <entry><literal>len</literal></entry>
+              <entry><literal>unsigned</literal></entry>
+              <entry><emphasis>none</emphasis></entry>
+              <entry>The length of the pointer</entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </informaltable>
+    </para>
+    
+  </formalpara>
+</section>
\ No newline at end of file


Added: trunk/ndbapi/struct-partitionspec.xml
===================================================================
--- trunk/ndbapi/struct-partitionspec.xml	                        (rev 0)
+++ trunk/ndbapi/struct-partitionspec.xml	2009-03-13 14:05:12 UTC (rev 14210)
Changed blocks: 1, Lines Added: 286, Lines Deleted: 0; 9951 bytes

@@ -0,0 +1,286 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+<!ENTITY % all.entities SYSTEM "all-entities.ent">
+%all.entities;
+]>
+<section id="struct-partitionspec">
+
+  <title>The <literal>PartitionSpec</literal> Structure</title>
+
+  <indexterm>
+    <primary>Ndb::PartitionSpec structure</primary>
+  </indexterm>
+
+  <indexterm>
+    <primary>PartitionSpec (Ndb structure)</primary>
+  </indexterm>
+
+  <abstract>
+
+    <para>
+      This section describes the <literal>PartitionSpec</literal>
+      structure.
+    </para>
+
+  </abstract>
+
+  <formalpara>
+
+    <title>Parent class</title>
+
+    <para>
+      <link linkend="class-ndb">Ndb</link>
+    </para>
+
+  </formalpara>
+
+  <formalpara>
+
+    <title>Description</title>
+
+    <para>
+      <literal>PartitionSpec</literal> is a structure available in MySQL
+      Cluster NDB 6.3.24 and later, and used for describing a table
+      partition in terms of any one of the following:
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            A specific partition ID for a table with user-defined
+            partitioning.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            An array made up of a table&apos;s distribution key values
+            for a table with native partitioning.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            (<emphasis>MySQL Cluster NDB 7.0.4 and later</emphasis>:) A
+            row in <literal>NdbRecord</literal> format containing a
+            natively partitioned table&apos;s distribution key values.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+    </para>
+
+  </formalpara>
+
+  <formalpara>
+
+    <title>Attributes</title>
+
+    <para>
+      A <literal>PartitionSpec</literal> has two attributes, a
+      <literal>SpecType</literal> and a <literal>Spec</literal> which is
+      a data structure corresponding to that
+      <literal>SpecType</literal>, as shown in the following table:
+
+      <informaltable>
+        <tgroup cols="4">
+          <colspec colwidth="20*"/>
+          <colspec colwidth="20*"/>
+          <colspec colwidth="30*"/>
+          <colspec colwidth="30*"/>
+          <thead>
+            <row>
+              <entry><literal>SpecType</literal> Enumeration</entry>
+              <entry><literal>SpecType</literal> Value (<literal>Uint32</literal>)</entry>
+              <entry>Data Structure</entry>
+              <entry>Description</entry>
+            </row>
+          </thead>
+          <tbody>
+            <row>
+              <entry><literal>PS_NONE</literal></entry>
+              <entry><literal>0</literal></entry>
+              <entry><emphasis>none</emphasis></entry>
+              <entry>No partitioning information is provided.</entry>
+            </row>
+            <row>
+              <entry><literal>PS_USER_DEFINED</literal></entry>
+              <entry><literal>1</literal></entry>
+              <entry><para>
+                  <literal>UserDefined</literal> structure:
+
+                  <informaltable>
+                    <tgroup cols="3">
+                      <colspec colwidth="33*"/>
+                      <colspec colwidth="34*"/>
+                      <colspec colwidth="33*"/>
+                      <thead>
+                        <row>
+                          <entry>Attribute</entry>
+                          <entry>Type</entry>
+                          <entry>Description</entry>
+                        </row>
+                      </thead>
+                      <tbody>
+                        <row>
+                          <entry><literal>partitionId</literal></entry>
+                          <entry><literal>Uint32</literal></entry>
+                          <entry>The partition ID for the desired table.</entry>
+                        </row>
+                      </tbody>
+                    </tgroup>
+                  </informaltable>
+                </para></entry>
+              <entry>For a table having user-defined partitioning, a specific partition is
+                identified by its partition ID.</entry>
+            </row>
+            <row>
+              <entry><literal>PS_DISTR_KEY_PART_PTR</literal></entry>
+              <entry><literal>2</literal></entry>
+              <entry><para>
+                  <literal>KeyPartPtr</literal> structure:
+
+                  <informaltable>
+                    <tgroup cols="3">
+                      <colspec colwidth="33*"/>
+                      <colspec colwidth="34*"/>
+                      <colspec colwidth="33*"/>
+                      <thead>
+                        <row>
+                          <entry>Attribute</entry>
+                          <entry>Type</entry>
+                          <entry>Description</entry>
+                        </row>
+                      </thead>
+                      <tbody>
+                        <row>
+                          <entry><literal>tableKeyParts</literal></entry>
+                          <entry><literal>const Key_part_ptr*</literal> (see
+                            <xref linkend="struct-key-part-ptr"/>)</entry>
+                          <entry>Pointer to the distribution key values for a table having native
+                            partitioning.</entry>
+                        </row>
+                        <row>
+                          <entry><literal>xfrmbuf</literal></entry>
+                          <entry><literal>void*</literal></entry>
+                          <entry>Pointer to a temporary buffer used for performing calculations.</entry>
+                        </row>
+                        <row>
+                          <entry><literal>xfrmbuflen</literal></entry>
+                          <entry><literal>Uint32</literal></entry>
+                          <entry>Length of the temporary buffer.</entry>
+                        </row>
+                      </tbody>
+                    </tgroup>
+                  </informaltable>
+                </para></entry>
+              <entry>For a table having native partitioning, an array the table&apos;s
+                distribution key values is used to identify the
+                partition.</entry>
+            </row>
+            <row>
+              <entry><literal>PS_DISTR_KEY_RECORD</literal> (MySQL Cluster NDB 7.0.4 and
+                later)</entry>
+              <entry><literal>3</literal></entry>
+              <entry><para>
+                  <literal>KeyRecord</literal> structure:
+
+                  <informaltable>
+                    <tgroup cols="3">
+                      <colspec colwidth="33*"/>
+                      <colspec colwidth="34*"/>
+                      <colspec colwidth="33*"/>
+                      <thead>
+                        <row>
+                          <entry>Attribute</entry>
+                          <entry>Type</entry>
+                          <entry>Description</entry>
+                        </row>
+                      </thead>
+                      <tbody>
+                        <row>
+                          <entry><literal>keyRecord</literal></entry>
+                          <entry><literal>const NdbRecord*</literal> (see
+                            <xref linkend="interface-ndbrecord"/>)</entry>
+                          <entry>A row in <literal>NdbRecord</literal> format, containing a table&apos;s
+                            distribution keys.</entry>
+                        </row>
+                        <row>
+                          <entry><literal>keyRow</literal></entry>
+                          <entry><literal>const char*</literal></entry>
+                          <entry>The distribution key data.</entry>
+                        </row>
+                        <row>
+                          <entry><literal>xfrmbuf</literal></entry>
+                          <entry><literal>void*</literal></entry>
+                          <entry>Pointer to a temporary buffer used for performing calculations.</entry>
+                        </row>
+                        <row>
+                          <entry><literal>xfrmbuflen</literal></entry>
+                          <entry><literal>Uint32</literal></entry>
+                          <entry>Length of the temporary buffer.</entry>
+                        </row>
+                      </tbody>
+                    </tgroup>
+                  </informaltable>
+                </para></entry>
+              <entry>The partition is identified using a natively partitioned table&apos;s
+                distribution key values, as contained in a row given in
+                <literal>NdbRecord</literal> format.</entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </informaltable>
+    </para>
+
+  </formalpara>
+
+  <formalpara>
+
+    <title>Definition</title>
+
+    <para>
+      Because this is a fairly complex structure, we here provide the
+      original source-code definition of
+      <literal>PartitionSpec</literal>, as given in
+      <filename>storage/ndb/include/ndbapi/Ndb.hpp</filename>:
+
+<programlisting>
+struct PartitionSpec
+{
+  enum SpecType
+  {
+    PS_NONE                = 0,
+    PS_USER_DEFINED        = 1,
+    PS_DISTR_KEY_PART_PTR  = 2,
+    PS_DISTR_KEY_RECORD    = 3
+  };
+
+  Uint32 type;
+  
+  union
+  {
+    struct {
+      Uint32 partitionId;
+    } UserDefined;
+    
+    struct {
+      const Key_part_ptr* tableKeyParts;
+      void* xfrmbuf;
+      Uint32 xfrmbuflen;
+    } KeyPartPtr;
+
+    struct {
+      const NdbRecord* keyRecord;
+      const char* keyRow;
+      void* xfrmbuf;
+      Uint32 xfrmbuflen;
+    } KeyRecord;
+  };
+};
+</programlisting>
+    </para>
+
+  </formalpara>
+
+</section>


Thread
svn commit - mysqldoc@docsrva: r14210 - in trunk/ndbapi: . images/published images/source/xmijon.stephens13 Mar