Author: jstephens
Date: 2006-07-01 20:42:44 +0200 (Sat, 01 Jul 2006)
New Revision: 2576
Log:
Added NdbIndexScanOperation class/member descriptions
Updated Makefile
Modified:
trunk/ndbapi/Makefile
trunk/ndbapi/ndb-classes.xml
Modified: trunk/ndbapi/Makefile
===================================================================
--- trunk/ndbapi/Makefile 2006-07-01 18:41:49 UTC (rev 2575)
+++ trunk/ndbapi/Makefile 2006-07-01 18:42:44 UTC (rev 2576)
@@ -31,7 +31,7 @@
NDBAPI_SRCS_EXTRA = ndb.en.ent
-NDBAPI_SRCS = $(NDBAPI_SRCS_EXTRA) ndbapi.xml overview.xml getting-started.xml mgm-api.xml ndb-classes.xml images/Ndb-class.png images/Ndb-cluster-connection-class.png images/NdbBlob-class.png images/NdbDictionary-classes.png images/NdbDictionary-Dictionary-class.png images/NdbDictionary-Column-class.png images/NdbDictionary-Object-class.png images/NdbDictionary-Object-Datafile-class.png images/NdbDictionary-Object-Event-class.png images/NdbDictionary-Object-Index-class.png images/NdbDictionary-Object-LogfileGroup-class.png images/NdbDictionary-Object-Table-class.png images/NdbDictionary-Object-Tablespace-class.png images/NdbDictionary-Object-Undofile-class.png images/NdbDictionary-AutoGrowSpecification-struct.png images/NdbEventOperation-class.png images/NdbOperation-subclasses.png images/NdbOperation-class.png images/NdbOperation-class.png images/NdbScanOperation-class.png errors.xml examples.xml
+NDBAPI_SRCS = $(NDBAPI_SRCS_EXTRA) ndbapi.xml overview.xml getting-started.xml mgm-api.xml ndb-classes.xml images/Ndb-class.png images/Ndb-cluster-connection-class.png images/NdbBlob-class.png images/NdbDictionary-classes.png images/NdbDictionary-Dictionary-class.png images/NdbDictionary-Column-class.png images/NdbDictionary-Object-class.png images/NdbDictionary-Object-Datafile-class.png images/NdbDictionary-Object-Event-class.png images/NdbDictionary-Object-Index-class.png images/NdbDictionary-Object-LogfileGroup-class.png images/NdbDictionary-Object-Table-class.png images/NdbDictionary-Object-Tablespace-class.png images/NdbDictionary-Object-Undofile-class.png images/NdbDictionary-AutoGrowSpecification-struct.png images/NdbEventOperation-class.png images/NdbOperation-subclasses.png images/NdbOperation-class.png images/NdbOperation-class.png images/NdbScanOperation-class.png images/NdbIndexScanOperation-class.png errors.xml examples.xml
ndbapi-prepped.xml: $(NDBAPI_SRCS)
Modified: trunk/ndbapi/ndb-classes.xml
===================================================================
--- trunk/ndbapi/ndb-classes.xml 2006-07-01 18:41:49 UTC (rev 2575)
+++ trunk/ndbapi/ndb-classes.xml 2006-07-01 18:42:44 UTC (rev 2576)
@@ -26974,12 +26974,795 @@
<title>The <literal>NdbIndexScanOperation</literal> Class</title>
-<!-- <abstract> -->
+ <abstract>
- <para/>
+ <para>
+ This section discusses the
+ <literal>NdbIndexScanOperation</literal> class and its
+ public members.
+ </para>
-<!-- </abstract> -->
+ </abstract>
+ <formalpara>
+
+ <title>Description</title>
+
+ <para>
+ The <literal>NdbIndexScanOperation</literal> class
+ represents a scan operation using an ordered index. This
+ class inherits from <literal>NdbScanOperation</literal> and
+ <literal>NdbOperation</literal>. See
+ <xref linkend="class-ndbscanoperation"/>, and
+ <xref linkend="class-ndboperation"/>, for more information
+ about these classes.
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Public Methods</title>
+
+ <para>
+ The following table lists the public methods of this class
+ and the purpose or use of each method:
+ </para>
+
+ </formalpara>
+
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colwidth="35*"/>
+ <colspec colwidth="65*"/>
+ <thead>
+ <row>
+ <entry>Method</entry>
+ <entry>Purpose / Use</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>get_range_no()</literal></entry>
+ <entry>Gets the rnage number for the current row</entry>
+ </row>
+ <row>
+ <entry><literal>getSorted()</literal></entry>
+ <entry>Checks whether the current scan is sorted</entry>
+ </row>
+ <row>
+ <entry><literal>getDescending()</literal></entry>
+ <entry>Checks whether the current scan is sorted</entry>
+ </row>
+ <row>
+ <entry><literal>readTuples()</literal></entry>
+ <entry>Readstuples using an ordered index</entry>
+ </row>
+ <row>
+ <entry><literal>setBound()</literal></entry>
+ <entry>Defines a bound on the index key for a range scan</entry>
+ </row>
+ <row>
+ <entry><literal>reset_bounds()</literal></entry>
+ <entry>Resets bounds, puts the operation in the send queue</entry>
+ </row>
+ <row>
+ <entry><literal>end_of_bound()</literal></entry>
+ <entry>Markes the end of a bound</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>
+ For detailed descriptions, signatures, and examples of use for
+ each of these methods, see
+ <xref linkend="class-ndbindexscanoperation-members"/>.
+ </para>
+
+ <formalpara>
+
+ <title>Public Types</title>
+
+ <para>
+ The <literal>NdbIndexScanOperation</literal> class defines
+ one public type. See
+ <xref linkend="class-ndbindexscanoperation-boundtype"/>.
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Class Diagram</title>
+
+ <para>
+ This diagram shows all the available methods and enumerated
+ types of the <literal>...</literal> class:
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/NdbIndexScanOperation-class.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase lang="en">Public members of the
+ <literal>NdbIndexScanOperation</literal> class.</phrase>
+ </textobject>
+ </mediaobject>
+ </para>
+
+ </formalpara>
+
+ <section id="class-ndbindexscanoperation-boundtype">
+
+ <title>The <literal>NdbIndexScanOperation::BoundType</literal> Type</title>
+
+ <formalpara>
+
+ <title>Description</title>
+
+ <para>
+ This type is used to describe an ordered key bound.
+ </para>
+
+ </formalpara>
+
+ <tip>
+ <para>
+ The numeric values are fixed in the API and can be used
+ explicitly — in other words, it is
+ <quote>safe</quote> to calculate the values and use them.
+ </para>
+ </tip>
+
+ <formalpara>
+
+ <title>Enumeration Values</title>
+
+ <para>
+ <informaltable>
+ <tgroup cols="3">
+ <colspec colwidth="30*"/>
+ <colspec colwidth="30*"/>
+ <colspec colwidth="40*"/>
+ <thead>
+ <row>
+ <entry>Value</entry>
+ <entry>Numeric Value</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>BoundLE</literal></entry>
+ <entry><literal>0</literal></entry>
+ <entry>Lower bound</entry>
+ </row>
+ <row>
+ <entry><literal>BoundLT</literal></entry>
+ <entry><literal>1</literal></entry>
+ <entry>Strict lower bound</entry>
+ </row>
+ <row>
+ <entry><literal>BoundGE</literal></entry>
+ <entry><literal>2</literal></entry>
+ <entry>Upper bound</entry>
+ </row>
+ <row>
+ <entry><literal>BoundGT</literal></entry>
+ <entry><literal>3</literal></entry>
+ <entry>Strict upper bound</entry>
+ </row>
+ <row>
+ <entry><literal>BoundEQ</literal></entry>
+ <entry><literal>4</literal></entry>
+ <entry>Equality</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+
+ </formalpara>
+
+ </section>
+
+ <section id="class-ndbindexscanoperation-members">
+
+ <title><literal>NdbIndexScanOperation</literal> Class Members</title>
+
+ <abstract>
+
+ <para>
+ This section lists and describes the public methods of the
+ <literal>NdbIndexScanOperation</literal> class.
+ </para>
+
+ </abstract>
+
+ <section id="class-ndbindexscanoperation-get-range-no">
+
+ <title><literal>NdbIndexScanOperation::get_range_no()</literal></title>
+
+ <formalpara>
+
+ <title>Description</title>
+
+ <para>
+ This method returns the range number for the current
+ row.
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Signature</title>
+
+ <para>
+<programlisting>
+int get_range_no
+ (
+ void
+ )
+</programlisting>
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Parameters</title>
+
+ <para>
+ <emphasis>None</emphasis>.
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Return Value</title>
+
+ <para>
+ The range number (an integer).
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Example</title>
+
+ <para>
+<programlisting>
+[<emphasis>To be supplied...</emphasis>]
+</programlisting>
+ </para>
+
+ </formalpara>
+
+ </section>
+
+ <section id="class-ndbindexscanoperation-getsorted">
+
+ <title><literal>NdbIndexScanOperation::getSorted()</literal></title>
+
+ <formalpara>
+
+ <title>Description</title>
+
+ <para>
+ This method is used to check whether the scan is sorted.
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Signature</title>
+
+ <para>
+<programlisting>
+bool getSorted
+ (
+ void
+ ) const
+</programlisting>
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Parameters</title>
+
+ <para>
+ <emphasis>None</emphasis>.
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Return Value</title>
+
+ <para>
+ <literal>true</literal> if the scan is sorted, otherwise
+ <literal>false</literal>.
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Example</title>
+
+ <para>
+<programlisting>
+[<emphasis>To be supplied...</emphasis>]
+</programlisting>
+ </para>
+
+ </formalpara>
+
+ </section>
+
+ <section id="class-ndbindexscanoperation-getdescending">
+
+ <title><literal>NdbIndexScanOperation::getDescending()</literal></title>
+
+ <formalpara>
+
+ <title>Description</title>
+
+ <para>
+ This method is used to check whether the scan is
+ descending.
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Signature</title>
+
+ <para>
+<programlisting>
+bool getDescending
+ (
+ void
+ ) const
+</programlisting>
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Parameters</title>
+
+ <para>
+ <emphasis>None</emphasis>.
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Return Value</title>
+
+ <para>
+ This method returns <literal>true</literal> if the scan
+ is osrted in descending order; otherwise, it returns
+ <literal>false</literal>.
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Example</title>
+
+ <para>
+<programlisting>
+[<emphasis>To be supplied...</emphasis>]
+</programlisting>
+ </para>
+
+ </formalpara>
+
+ </section>
+
+ <section id="class-ndbindexscanoperation-readtuples">
+
+ <title><literal>NdbIndexScanOperation::readTuples()</literal></title>
+
+ <formalpara>
+
+ <title>Description</title>
+
+ <para>
+ This method is used to read tuples, using an ordered
+ index.
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Signature</title>
+
+ <para>
+<programlisting>
+virtual int readTuples
+ (
+ LockMode <replaceable>mode</replaceable> = LM_Read,
+ Uint32 <replaceable>flags</replaceable> = 0,
+ Uint32 <replaceable>parallel</replaceable> = 0
+ )
+</programlisting>
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Parameters</title>
+
+ <para>
+ The <literal>readTuples()</literal> method takes 3
+ parameters, as listed here:
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ The lock <replaceable>mode</replaceable> used for
+ the scan. This is a <literal>LockMode</literal>
+ value; see
+ <xref linkend="class-ndboperation-lockmode"/> for
+ more information, including permitted values.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ One or more scan flags; multiple
+ <replaceable>flags</replaceable> are
+ <literal>OR</literal>'ed together as they are when
+ used with
+ <literal>NdbScanOperation::readTuples()</literal>.
+ See
+ <xref linkend="class-ndbscanoperation-scanflag"/>
+ for possible values.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The number of fragments to scan in
+ <replaceable>parallel</replaceable>; use
+ <literal>0</literal> to specify the maximum
+ automatically.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Return Value</title>
+
+ <para>
+ An integer: <literal>0</literal> indicates success;
+ <literal>-1</literal> indicates failure.
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Example</title>
+
+ <para>
+<programlisting>
+[<emphasis>To be supplied...</emphasis>]
+</programlisting>
+ </para>
+
+ </formalpara>
+
+ </section>
+
+ <section id="class-ndbindexscanoperation-setbound">
+
+ <title><literal>NdbIndexScanOperation::setBound</literal></title>
+
+ <formalpara>
+
+ <title>Description</title>
+
+ <para>
+ This method defines a bound on an index key used in a
+ range scan.
+ </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>
+
+ <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 example, that <quote>a >= 2 AND b >
+ 3</quote> is permissible, but <quote>a > 2 AND b >=
+ 3</quote> is not.
+ </para>
+
+ <para>
+ The scan may currently return tuples for which the bounds
+ are not satisfied. For example, a <literal><= 2
+ && b <= 3</literal> not only scans the index up
+ to <literal>(a=2, b=3)</literal>, but also returns any
+ <literal>(a=1, b=4)</literal> as well.
+ </para>
+
+ <para>
+ When setting bounds based on equality, it is better to use
+ <literal>BoundEQ</literal> instead of the equivalent pair
+ <literal>BoundLE</literal> and <literal>BoundGE</literal>.
+ This is especially true when the table partition key is a
+ prefix of the index key.
+ </para>
+
+ <para>
+ <literal>NULL</literal> is considered less than any
+ non-<literal>NULL</literal> value and equal to another
+ <literal>NULL</literal> value. To perform comparisons with
+ <literal>NULL</literal>, use <literal>setBound()</literal>
+ with a null pointer (<literal>0</literal>).
+ </para>
+
+ <para>
+ An index also stores all-<literal>NULL</literal> keys as
+ well, and performing an index scan with an empty bound set
+ returns all tuples from the table.
+ </para>
+
+ <formalpara>
+
+ <title>Signature</title>
+
+ <para>
+<programlisting>
+int setBound
+ (
+ const char* <replaceable>name</replaceable>,
+ int <replaceable>type</replaceable>,
+ const void* <replaceable>value</replaceable>
+ )
+</programlisting>
+
+ or
+
+<programlisting>
+int setBound
+ (
+ Uint32 <replaceable>id</replaceable>,
+ int <replaceable>type</replaceable>,
+ const void* <replaceable>value</replaceable>
+ )
+</programlisting>
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Parameters</title>
+
+ <para>
+ This method takes 3 parameters:
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Either the <replaceable>name</replaceable> or the
+ <replaceable>id</replaceable> of the attribute on
+ which the bound is to be set.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The bound <literal>type</literal> — see
+ <xref linkend="class-ndbindexscanoperation-boundtype"/>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ A pointer to the bound
+ <replaceable>value</replaceable> (use
+ <literal>0</literal> for <literal>NULL</literal>).
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Return Value</title>
+
+ <para>
+ Returns <literal>0</literal> on success,
+ <literal>-1</literal> on failure.
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Example</title>
+
+ <para>
+<programlisting>
+[<emphasis>To be supplied...</emphasis>]
+</programlisting>
+ </para>
+
+ </formalpara>
+
+ </section>
+
+ <section id="class-ndbindexscanoperation-reset-bounds">
+
+ <title><literal>NdbIndexScanOperation::reset_bounds()</literal></title>
+
+ <formalpara>
+
+ <title>Description</title>
+
+ <para>
+ Reset the bounds, and put the operation into the list
+ that will be sent on the next
+ <literal>NdbTransaction::execute()</literal> call.
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Signature</title>
+
+ <para>
+<programlisting>
+int reset_bounds
+ (
+ bool <literal>forceSend</literal> = false
+ )
+</programlisting>
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Parameters</title>
+
+ <para>
+ Set <literal>forceSend</literal> to true in order to
+ force the operation to be sent immediately.
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Return Value</title>
+
+ <para>
+ <literal>0</literal> on success, <literal>-1</literal>
+ on failure.
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Example</title>
+
+ <para>
+<programlisting>
+[<emphasis>To be supplied...</emphasis>]
+</programlisting>
+ </para>
+
+ </formalpara>
+
+ </section>
+
+ <section id="class-ndbindexscanoperation-end-of-bound">
+
+ <title><literal>NdbIndexScanOperation::end_of_bound()</literal></title>
+
+ <formalpara>
+
+ <title>Description</title>
+
+ <para>
+ This method is used to mark the end of a bound; used
+ when batching index reads (that is, when employing
+ multiple ranges).
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Signature</title>
+
+ <para>
+<programlisting>
+int end_of_bound
+ (
+ Uint32 <replaceable>range_no</replaceable>
+ )
+</programlisting>
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Parameters</title>
+
+ <para>
+ The number of the range on which the bound occurs.
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Return Value</title>
+
+ <para>
+ <literal>0</literal> indicates success;
+ <literal>-1</literal> indicates failure.
+ </para>
+
+ </formalpara>
+
+ <formalpara>
+
+ <title>Example</title>
+
+ <para>
+<programlisting>
+[<emphasis>To be supplied...</emphasis>]
+</programlisting>
+ </para>
+
+ </formalpara>
+
+ </section>
+
+ </section>
+
</section>
</section>
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r2576 - trunk/ndbapi | jon | 1 Jul |
