Author: jstephens
Date: 2008-08-19 15:57:52 +0200 (Tue, 19 Aug 2008)
New Revision: 11575
Log:
NdbInterpretedCode column comparison and pattern matching methods
(Thanks, Frazer!)
Modified:
trunk/ndbapi/class-ndbinterpretedcode.xml
Modified: trunk/ndbapi/class-ndbinterpretedcode.xml
===================================================================
--- trunk/ndbapi/class-ndbinterpretedcode.xml 2008-08-19 08:57:10 UTC (rev 11574)
+++ trunk/ndbapi/class-ndbinterpretedcode.xml 2008-08-19 13:57:52 UTC (rev 11575)
Changed blocks: 45, Lines Added: 591, Lines Deleted: 43; 26960 bytes
@@ -11,7 +11,8 @@
<para>
This section discusses the <literal>NdbInterpretedCode</literal>
- class, which is used to prepare an NDB interpreted program.
+ class, which is used to prepare and execute an NDB interpreted
+ program.
</para>
</abstract>
@@ -368,7 +369,7 @@
<title>Description</title>
<para>
- This is the <emphasis>NdbInterpretedCode</emphasis> class
+ This is the <literal>NdbInterpretedCode</literal> class
constuctor.
</para>
@@ -1455,7 +1456,7 @@
<listitem>
<para>
- Comparison between two column values
+ Comparison between a column value and a given constant
</para>
</listitem>
@@ -2455,6 +2456,102 @@
<title>Column-Based <literal>NdbInterpretedCode</literal> Branch Operations</title>
+ <para>
+ The methods described in this section are used to perform
+ branching based on a comparison between a table column value and
+ a given constant value. Each of these methods expects the
+ attribute ID of the column whose value is to be tested rather
+ than a reference to a <literal>Column</literal> object.
+ </para>
+
+ <para>
+ These methods, with the exception of
+ <literal>branch_col_eq_null()</literal> and
+ <literal>branch_col_ne_null()</literal>, can be thought of as
+ performing the following logic:
+
+<programlisting>
+if(constant_value <replaceable>condition</replaceable> column_value)
+ goto <replaceable>Label</replaceable>
+</programlisting>
+
+ In each case (once again excepting
+ <literal>branch_col_eq_null()</literal> and
+ <literal>branch_col_ne_null()</literal>), the arbitrary constant
+ is the first parameter passed to the method.
+ </para>
+
+ <para>
+ The space requirements for each of these methods is shown in the
+ following table, where <replaceable>L</replaceable> represents
+ the length of the constant value:
+
+ <informaltable>
+ <tgroup cols="3">
+ <colspec colwidth="50*"/>
+ <colspec colwidth="25*"/>
+ <colspec colwidth="25*"/>
+ <thead>
+ <row>
+ <entry>Method</entry>
+ <entry>Buffer (words)</entry>
+ <entry>Request message (words)</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>branch_col_eq_null()</literal></entry>
+ <entry>2</entry>
+ <entry>2</entry>
+ </row>
+ <row>
+ <entry><literal>branch_col_ne_null()</literal></entry>
+ <entry>2</entry>
+ <entry>2</entry>
+ </row>
+ <row>
+ <entry><literal>branch_col_eq()</literal></entry>
+ <entry>2</entry>
+ <entry>2 + <literal>CEIL(<replaceable>L</replaceable> / 8)</literal></entry>
+ </row>
+ <row>
+ <entry><literal>branch_col_ne()</literal></entry>
+ <entry>2</entry>
+ <entry>2 + <literal>CEIL(<replaceable>L</replaceable> / 8)</literal></entry>
+ </row>
+ <row>
+ <entry><literal>branch_col_lt()</literal></entry>
+ <entry>2</entry>
+ <entry>2 + <literal>CEIL(<replaceable>L</replaceable> / 8)</literal></entry>
+ </row>
+ <row>
+ <entry><literal>branch_col_le()</literal></entry>
+ <entry>2</entry>
+ <entry>2 + <literal>CEIL(<replaceable>L</replaceable> / 8)</literal></entry>
+ </row>
+ <row>
+ <entry><literal>branch_col_gt()</literal></entry>
+ <entry>2</entry>
+ <entry>2 + <literal>CEIL(<replaceable>L</replaceable> / 8)</literal></entry>
+ </row>
+ <row>
+ <entry><literal>branch_col_ge()</literal></entry>
+ <entry>2</entry>
+ <entry>2 + <literal>CEIL(<replaceable>L</replaceable> / 8)</literal></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+
+ <note>
+ <para>
+ The expression <literal>CEIL(<replaceable>L</replaceable> /
+ 8)</literal> is the number of whole 8-byte words required to
+ hold the constant value to be compared.
+ </para>
+ </note>
+
<section id="class-ndbinterpretedcode-branch-col-eq">
<title><literal>NdbInterpretedCode::branch_col_eq()</literal></title>
@@ -2471,7 +2568,11 @@
<title>Description</title>
- <para></para>
+ <para>
+ This method compares a table column value with an arbitrary
+ constant and jumps to the specified program label if the
+ values are equal.
+ </para>
</formalpara>
@@ -2481,7 +2582,13 @@
<para>
<programlisting>
-
+int branch_col_eq
+ (
+ const void* <replaceable>val</replaceable>,
+ Uint32 <replaceable>len</replaceable>,
+ Uint32 <replaceable>attrId</replaceable>,
+ Uint32 <replaceable>Label</replaceable>
+ )
</programlisting>
</para>
@@ -2492,7 +2599,38 @@
<title>Parameters</title>
<para>
- <emphasis>None</emphasis>.
+ This method takes 4 parameters:
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ A constant value (<replaceable>val</replaceable>)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The length of the value (in bytes)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The attribute ID of the table column whose value is to
+ be compared with <replaceable>val</replaceable>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ A <replaceable>Label</replaceable> (previously defined
+ using <literal>def_label()</literal>) to jump to if
+ the compared values are equal
+ </para>
+ </listitem>
+
+ </itemizedlist>
</para>
</formalpara>
@@ -2502,7 +2640,8 @@
<title>Return Value</title>
<para>
- <emphasis>None</emphasis>.
+ <literal>0</literal> on success, <literal>-1</literal> on
+ failure.
</para>
</formalpara>
@@ -2539,7 +2678,11 @@
<title>Description</title>
- <para></para>
+ <para>
+ This method compares a table column value with an arbitrary
+ constant and jumps to the specified program label if the two
+ values are not equal.
+ </para>
</formalpara>
@@ -2549,7 +2692,13 @@
<para>
<programlisting>
-
+int branch_col_ne
+ (
+ const void* <replaceable>val</replaceable>,
+ Uint32 <replaceable>len</replaceable>,
+ Uint32 <replaceable>attrId</replaceable>,
+ Uint32 <replaceable>Label</replaceable>
+ )
</programlisting>
</para>
@@ -2560,7 +2709,38 @@
<title>Parameters</title>
<para>
- <emphasis>None</emphasis>.
+ This method takes 4 parameters:
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ A constant value (<replaceable>val</replaceable>)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The length of the value (in bytes)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The attribute ID of the table column whose value is to
+ be compared with <replaceable>val</replaceable>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ A <replaceable>Label</replaceable> (previously defined
+ using <literal>def_label()</literal>) to jump to if
+ the compared values are unequal
+ </para>
+ </listitem>
+
+ </itemizedlist>
</para>
</formalpara>
@@ -2570,7 +2750,8 @@
<title>Return Value</title>
<para>
- <emphasis>None</emphasis>.
+ <literal>0</literal> on success, <literal>-1</literal> on
+ failure.
</para>
</formalpara>
@@ -2607,7 +2788,11 @@
<title>Description</title>
- <para></para>
+ <para>
+ This method compares a table column value with an arbitrary
+ constant and jumps to the specified program label if the
+ constant is less than the column value.
+ </para>
</formalpara>
@@ -2617,7 +2802,13 @@
<para>
<programlisting>
-
+int branch_col_lt
+ (
+ const void* <replaceable>val</replaceable>,
+ Uint32 <replaceable>len</replaceable>,
+ Uint32 <replaceable>attrId</replaceable>,
+ Uint32 <replaceable>Label</replaceable>
+ )
</programlisting>
</para>
@@ -2628,7 +2819,38 @@
<title>Parameters</title>
<para>
- <emphasis>None</emphasis>.
+ This method takes 4 parameters:
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ A constant value (<replaceable>val</replaceable>)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The length of the value (in bytes)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The attribute ID of the table column whose value is to
+ be compared with <replaceable>val</replaceable>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ A <replaceable>Label</replaceable> (previously defined
+ using <literal>def_label()</literal>) to jump to if
+ the constant value is less than the column value
+ </para>
+ </listitem>
+
+ </itemizedlist>
</para>
</formalpara>
@@ -2638,7 +2860,8 @@
<title>Return Value</title>
<para>
- <emphasis>None</emphasis>.
+ <literal>0</literal> on success, <literal>-1</literal> on
+ failure.
</para>
</formalpara>
@@ -2675,7 +2898,11 @@
<title>Description</title>
- <para></para>
+ <para>
+ This method compares a table column value with an arbitrary
+ constant and jumps to the specified program label if the
+ constant is less than or equal to the column value.
+ </para>
</formalpara>
@@ -2685,7 +2912,13 @@
<para>
<programlisting>
-
+int branch_col_le
+ (
+ const void* <replaceable>val</replaceable>,
+ Uint32 <replaceable>len</replaceable>,
+ Uint32 <replaceable>attrId</replaceable>,
+ Uint32 <replaceable>Label</replaceable>
+ )
</programlisting>
</para>
@@ -2696,7 +2929,39 @@
<title>Parameters</title>
<para>
- <emphasis>None</emphasis>.
+ This method takes 4 parameters:
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ A constant value (<replaceable>val</replaceable>)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The length of the value (in bytes)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The attribute ID of the table column whose value is to
+ be compared with <replaceable>val</replaceable>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ A <replaceable>Label</replaceable> (previously defined
+ using <literal>def_label()</literal>) to jump to if
+ the constant value is less than or equal to the column
+ value
+ </para>
+ </listitem>
+
+ </itemizedlist>
</para>
</formalpara>
@@ -2706,7 +2971,8 @@
<title>Return Value</title>
<para>
- <emphasis>None</emphasis>.
+ <literal>0</literal> on success, <literal>-1</literal> on
+ failure.
</para>
</formalpara>
@@ -2743,7 +3009,11 @@
<title>Description</title>
- <para></para>
+ <para>
+ This method compares a table column value with an arbitrary
+ constant and jumps to the specified program label if the
+ constant is greater than the column value.
+ </para>
</formalpara>
@@ -2753,7 +3023,13 @@
<para>
<programlisting>
-
+int branch_col_gt
+ (
+ const void* <replaceable>val</replaceable>,
+ Uint32 <replaceable>len</replaceable>,
+ Uint32 <replaceable>attrId</replaceable>,
+ Uint32 <replaceable>Label</replaceable>
+ )
</programlisting>
</para>
@@ -2764,7 +3040,38 @@
<title>Parameters</title>
<para>
- <emphasis>None</emphasis>.
+ This method takes 4 parameters:
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ A constant value (<replaceable>val</replaceable>)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The length of the value (in bytes)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The attribute ID of the table column whose value is to
+ be compared with <replaceable>val</replaceable>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ A <replaceable>Label</replaceable> (previously defined
+ using <literal>def_label()</literal>) to jump to if
+ the constant value is greater than the column value
+ </para>
+ </listitem>
+
+ </itemizedlist>
</para>
</formalpara>
@@ -2774,7 +3081,8 @@
<title>Return Value</title>
<para>
- <emphasis>None</emphasis>.
+ <literal>0</literal> on success, <literal>-1</literal> on
+ failure.
</para>
</formalpara>
@@ -2811,7 +3119,11 @@
<title>Description</title>
- <para></para>
+ <para>
+ This method compares a table column value with an arbitrary
+ constant and jumps to the specified program label if the
+ constant is greater than or equal to the column value.
+ </para>
</formalpara>
@@ -2821,7 +3133,13 @@
<para>
<programlisting>
-
+int branch_col_ge
+ (
+ const void* <replaceable>val</replaceable>,
+ Uint32 <replaceable>len</replaceable>,
+ Uint32 <replaceable>attrId</replaceable>,
+ Uint32 <replaceable>Label</replaceable>
+ )
</programlisting>
</para>
@@ -2832,7 +3150,39 @@
<title>Parameters</title>
<para>
- <emphasis>None</emphasis>.
+ This method takes 4 parameters:
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ A constant value (<replaceable>val</replaceable>)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The length of the value (in bytes)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The attribute ID of the table column whose value is to
+ be compared with <replaceable>val</replaceable>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ A <replaceable>Label</replaceable> (previously defined
+ using <literal>def_label()</literal>) to jump to if
+ the constant value is greater than or equal to the
+ column value
+ </para>
+ </listitem>
+
+ </itemizedlist>
</para>
</formalpara>
@@ -2842,7 +3192,8 @@
<title>Return Value</title>
<para>
- <emphasis>None</emphasis>.
+ <literal>0</literal> on success, <literal>-1</literal> on
+ failure.
</para>
</formalpara>
@@ -2879,7 +3230,11 @@
<title>Description</title>
- <para></para>
+ <para>
+ This method tests the value of a table column and jumps to
+ the indicated program label if the column value is
+ <literal>NULL</literal>.
+ </para>
</formalpara>
@@ -2889,7 +3244,11 @@
<para>
<programlisting>
-
+int branch_col_eq_null
+ (
+ Uint32 <replaceable>attrId</replaceable>,
+ Uint32 <replaceable>Label</replaceable>
+ )
</programlisting>
</para>
@@ -2900,7 +3259,9 @@
<title>Parameters</title>
<para>
- <emphasis>None</emphasis>.
+ This method requires two parameters: the attribuite ID for
+ the table column, and the program label to jump to if the
+ column value is <literal>NULL</literal>.
</para>
</formalpara>
@@ -2910,7 +3271,8 @@
<title>Return Value</title>
<para>
- <emphasis>None</emphasis>.
+ <literal>0</literal> on success, <literal>-1</literal> on
+ failure.
</para>
</formalpara>
@@ -2947,7 +3309,11 @@
<title>Description</title>
- <para></para>
+ <para>
+ This method tests the value of a table column and jumps to
+ the indicated program label if the column value is not
+ <literal>NULL</literal>.
+ </para>
</formalpara>
@@ -2957,7 +3323,11 @@
<para>
<programlisting>
-
+int branch_col_ne_null
+ (
+ Uint32 <replaceable>attrId</replaceable>,
+ Uint32 <replaceable>Label</replaceable>
+ )
</programlisting>
</para>
@@ -2968,7 +3338,9 @@
<title>Parameters</title>
<para>
- <emphasis>None</emphasis>.
+ This method requires two parameters: the attribuite ID of
+ the table column, and the program label to jump to if the
+ column value is not <literal>NULL</literal>.
</para>
</formalpara>
@@ -2978,7 +3350,8 @@
<title>Return Value</title>
<para>
- <emphasis>None</emphasis>.
+ <literal>0</literal> on success, <literal>-1</literal> on
+ failure.
</para>
</formalpara>
@@ -3005,6 +3378,92 @@
<title>Pattern-Based <literal>NdbInterpretedCode</literal> Branch Operations</title>
+ <para>
+ The <literal>NdbInterpretedCode</literal> class provides two
+ methods which can be used to branch based on a comparison
+ between a column containing character data (that is, a
+ <literal>CHAR</literal>, <literal>VARCHAR</literal>,
+ <literal>BINARY</literal>, or <literal>VARBINARY</literal>
+ column) and a regular expression pattern.
+ </para>
+
+ <para>
+ The pattern syntax allowed in the regular expression is the same
+ as that supported by the MySQL Server's
+ <literal>LIKE</literal> and <literal>NOT LIKE</literal>
+ operators, including the <literal>_</literal> and
+ <literal>%</literal> metacharacters. For more information about
+ these, see <xref linkend="string-comparison-functions"/>.
+ </para>
+
+ <note>
+ <para>
+ This is also the same regular expression pattern syntax
+ supported by <literal>NdbScanFilter</literal>; see
+ <xref linkend="class-ndbscanfilter-cmp"/>, for more
+ information.
+ </para>
+ </note>
+
+ <para>
+ The table being operated upon must be supplied when the
+ <literal>NdbInterpretedCode</literal> object is instantiated.
+ The regular expression pattern should be in plain
+ <literal>CHAR</literal> format, even if the column is actually a
+ <literal>VARCHAR</literal> (in other words, there should be no
+ leading length bytes).
+ </para>
+
+ <para>
+ These functions behave as shown here:
+
+<programlisting>
+if (<replaceable>column_value</replaceable> [NOT] LIKE <replaceable>pattern</replaceable>)
+ goto <replaceable>Label</replaceable>;
+</programlisting>
+ </para>
+
+ <para>
+ The space requirements for these methods is shown in the
+ following table, where <replaceable>L</replaceable> represents
+ the length of the constant value:
+
+ <informaltable>
+ <tgroup cols="3">
+ <colspec colwidth="50*"/>
+ <colspec colwidth="25*"/>
+ <colspec colwidth="25*"/>
+ <thead>
+ <row>
+ <entry>Method</entry>
+ <entry>Buffer (words)</entry>
+ <entry>Request message (words)</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>branch_col_like()</literal></entry>
+ <entry>2</entry>
+ <entry>2 + <literal>CEIL(<replaceable>L</replaceable> / 8)</literal></entry>
+ </row>
+ <row>
+ <entry><literal>branch_col_notlike()</literal></entry>
+ <entry>2</entry>
+ <entry>2 + <literal>CEIL(<replaceable>L</replaceable> / 8)</literal></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+
+ <note>
+ <para>
+ The expression <literal>CEIL(<replaceable>L</replaceable> /
+ 8)</literal> is the number of whole 8-byte words required to
+ hold the constant value to be compared.
+ </para>
+ </note>
+
<section id="class-ndbinterpretedcode-branch-col-like">
<title><literal>NdbInterpretedCode::branch_col_like()</literal></title>
@@ -3021,7 +3480,11 @@
<title>Description</title>
- <para></para>
+ <para>
+ This method tests a table column value against a regular
+ expression pattern and jumps to the indicated program label
+ if they match.
+ </para>
</formalpara>
@@ -3031,7 +3494,13 @@
<para>
<programlisting>
-
+int branch_col_like
+ (
+ const void* <replaceable>val</replaceable>,
+ Uint32 <replaceable>len</replaceable>,
+ Uint32 <replaceable>attrId</replaceable>,
+ Uint32 <replaceable>Label</replaceable>
+ )
</programlisting>
</para>
@@ -3042,7 +3511,39 @@
<title>Parameters</title>
<para>
- <emphasis>None</emphasis>.
+ This method takes 4 parameters, which are listed here:
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ A regular expression pattern
+ (<replaceable>val</replaceable>); see
+ <xref linkend="class-ndbinterpretedcode-branch-patterns"/>,
+ for the syntax supported
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Length of the pattern (in bytes)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The attribute ID for the table column being tested
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The program label to jump to if the table column value
+ matches the pattern
+ </para>
+ </listitem>
+
+ </itemizedlist>
</para>
</formalpara>
@@ -3052,7 +3553,8 @@
<title>Return Value</title>
<para>
- <emphasis>None</emphasis>.
+ <literal>0</literal> on success, <literal>-1</literal> on
+ failure
</para>
</formalpara>
@@ -3089,7 +3591,14 @@
<title>Description</title>
- <para></para>
+ <para>
+ This method is similar to
+ <literal>branch_col_like()</literal> in that it tests a
+ table column value against a regular expression pattern;
+ however it jumps to the indicated program label only if the
+ pattern and the column value do <emphasis>not</emphasis>
+ match.
+ </para>
</formalpara>
@@ -3099,7 +3608,13 @@
<para>
<programlisting>
-
+int branch_col_notlike
+ (
+ const void* <replaceable>val</replaceable>,
+ Uint32 <replaceable>len</replaceable>,
+ Uint32 <replaceable>attrId</replaceable>,
+ Uint32 <replaceable>Label</replaceable>
+ )
</programlisting>
</para>
@@ -3110,7 +3625,39 @@
<title>Parameters</title>
<para>
- <emphasis>None</emphasis>.
+ This method takes 4 parameters as shown here:
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ A regular expression pattern
+ (<replaceable>val</replaceable>); see
+ <xref linkend="class-ndbinterpretedcode-branch-patterns"/>,
+ for the syntax supported
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Length of the pattern (in bytes)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The attribute ID for the table column being tested
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The program label to jump to if the table column value
+ does not match the pattern
+ </para>
+ </listitem>
+
+ </itemizedlist>
</para>
</formalpara>
@@ -3120,7 +3667,8 @@
<title>Return Value</title>
<para>
- <emphasis>None</emphasis>.
+ <literal>0</literal> on success, <literal>-1</literal> on
+ failure
</para>
</formalpara>
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r11575 - trunk/ndbapi | jon | 19 Aug |
