svn commit - mysqldoc@docsrva: r133 - branches/MikePluggable/trunk/refman-5.1

[eherman]

Author: eherman
Date: 2005-10-21 20:36:31 +0200 (Fri, 21 Oct 2005)
New Revision: 133

Log:
added comments taken from ha_example.h

Modified:
   branches/MikePluggable/trunk/refman-5.1/custom-engine.xml

Modified: branches/MikePluggable/trunk/refman-5.1/custom-engine.xml
===================================================================
--- branches/MikePluggable/trunk/refman-5.1/custom-engine.xml	2005-10-21 17:49:12 UTC (rev
132)
+++ branches/MikePluggable/trunk/refman-5.1/custom-engine.xml	2005-10-21 18:36:31 UTC (rev
133)
@@ -1187,7 +1187,7 @@
 
       <refnamediv>
         <refname>compare_key</refname>
-        <refpurpose></refpurpose>
+        <refpurpose>Compare if found key (in row) is over
max-value</refpurpose>
       </refnamediv>
 
       <refsynopsisdiv>
@@ -1204,13 +1204,14 @@
        <title>Description</title>
 
     <para>This is the <function>compare_key</function>
method.</para>
+        <para>See key.cc::key_cmp() for details</para>
       </refsection>
 
       <refsection>
         <title>Parameters</title>
 
         <itemizedlist>
-         
<listitem><para><literal>range</literal></para></listitem>
+          <listitem><para><literal>range</literal> range to
compare to row. May be 0 for no range</para></listitem>
         </itemizedlist>
 
       </refsection>
@@ -1219,11 +1220,21 @@
         <title>Return Values</title>
 
        <itemizedlist>
-          <listitem>
+         <listitem>
            <para>
-             <literal></literal>
+             <literal>0</literal> Key is equal to range or 'range' == 0 (no
range)
            </para>
          </listitem>
+         <listitem>
+           <para>
+             <literal>1</literal> Key is less than range
+           </para>
+         </listitem>
+         <listitem>
+           <para>
+             <literal>-1</literal> Key is larger than range
+           </para>
+         </listitem>
        </itemizedlist>
 
       </refsection>
@@ -5714,6 +5725,14 @@
        <title>Description</title>
 
     <para>This is the <function>index_flags</function>
method.</para>
+        <para>This is a bitmap of flags that says how the storage engine
+          implements indexes. The current index flags are documented in
+          handler.h. If you do not implement indexes, just return zero
+          here.
+          </para><para>
+          part is the key part to check. First key part is 0
+          If all_parts it's set, MySQL want to know the flags for the combined
+          index up to and including 'part'.</para>
       </refsection>
 
       <refsection>
@@ -6310,7 +6329,7 @@
 
       <refnamediv>
         <refname>index_type</refname>
-        <refpurpose></refpurpose>
+        <refpurpose>The name of the index type that will be used for
display</refpurpose>
       </refnamediv>
 
       <refsynopsisdiv>
@@ -6327,6 +6346,7 @@
        <title>Description</title>
 
     <para>This is the <function>index_type</function>
method.</para>
+        <para>don't implement this method unless you really have
indexes</para>
       </refsection>
 
       <refsection>
@@ -7534,6 +7554,14 @@
        <title>Description</title>
 
     <para>This is the <function>max_supported_record_length</function>
method.</para>
+        <para>unireg.cc will call the following to make sure that the storage
engine can
+          handle the data it is about to send.
+          </para><para>
+          Return *real* limits of your storage engine here. MySQL will do
+          min(your_limits, MySQL_limits) automatically
+          </para><para>
+          There is no need to implement ..._key_... methods if you don't suport
+          indexes.</para>
       </refsection>
 
       <refsection>
@@ -8332,7 +8360,7 @@
 
       <refnamediv>
         <refname>read_multi_range_next</refname>
-        <refpurpose></refpurpose>
+        <refpurpose>Read the next row of a multi-range set.</refpurpose>
       </refnamediv>
 
       <refsynopsisdiv>
@@ -8349,13 +8377,17 @@
        <title>Description</title>
 
     <para>This is the <function>read_multi_range_next</function>
method.</para>
+        <para>Record is read into table->record[0].
+          *found_range_p returns a valid value only if read_multi_range_next()
+          returns 0.</para>
       </refsection>
 
       <refsection>
         <title>Parameters</title>
 
         <itemizedlist>
-         
<listitem><para><literal>found_range_p</literal></para></listitem>
+          <listitem><para><literal>found_range_p</literal>
Returns a pointer to the element in 'ranges' that
+            corresponds to the returned row.</para></listitem>
         </itemizedlist>
 
       </refsection>
@@ -8364,11 +8396,21 @@
         <title>Return Values</title>
 
        <itemizedlist>
-          <listitem>
+         <listitem>
            <para>
-             <literal></literal>
+             <literal>0</literal> OK, found a row
            </para>
          </listitem>
+         <listitem>
+           <para>
+             <literal>HA_ERR_END_OF_FILE</literal> No (more) rows in range
+           </para>
+         </listitem>
+         <listitem>
+           <para>
+             <literal>#</literal> Error code
+           </para>
+         </listitem>
        </itemizedlist>
 
       </refsection>
@@ -8391,7 +8433,7 @@
 
       <refnamediv>
         <refname>read_range_first</refname>
-        <refpurpose></refpurpose>
+        <refpurpose>Read first row between two ranges.</refpurpose>
       </refnamediv>
 
       <refsynopsisdiv>
@@ -8411,16 +8453,18 @@
        <title>Description</title>
 
     <para>This is the <function>read_range_first</function>
method.</para>
+        <para>Store ranges for future calls to read_range_next</para>
+        <para>Record is read into table->record[0]</para>
       </refsection>
 
       <refsection>
         <title>Parameters</title>
 
         <itemizedlist>
-         
<listitem><para><literal>start_key</literal></para></listitem>
-         
<listitem><para><literal>end_key</literal></para></listitem>
-         
<listitem><para><literal>eq_range</literal></para></listitem>
-         
<listitem><para><literal>sorted</literal></para></listitem>
+          <listitem><para><literal>start_key</literal> Start key.
Is 0 if no min range</para></listitem>
+          <listitem><para><literal>end_key</literal> End key.  Is
0 if no max range</para></listitem>
+          <listitem><para><literal>eq_range</literal> Set to 1 if
start_key == end_key</para></listitem>
+          <listitem><para><literal>sorted</literal> Set to 1 if
result should be sorted per key</para></listitem>
         </itemizedlist>
 
       </refsection>
@@ -8429,11 +8473,21 @@
         <title>Return Values</title>
 
        <itemizedlist>
-          <listitem>
+         <listitem>
            <para>
-             <literal></literal>
+             <literal>0</literal> OK, found a row
            </para>
          </listitem>
+         <listitem>
+           <para>
+             <literal>HA_ERR_END_OF_FILE</literal> No rows in range
+           </para>
+         </listitem>
+         <listitem>
+           <para>
+             <literal>#</literal> Error code
+           </para>
+         </listitem>
        </itemizedlist>
 
       </refsection>
@@ -8456,7 +8510,7 @@
 
       <refnamediv>
         <refname>read_range_next</refname>
-        <refpurpose></refpurpose>
+        <refpurpose>Read next row between two ranges.</refpurpose>
       </refnamediv>
 
       <refsynopsisdiv>
@@ -8473,6 +8527,7 @@
        <title>Description</title>
 
     <para>This is the <function>read_range_next</function>
method.</para>
+        <para>Record is read into table->record[0]</para>
       </refsection>
 
       <refsection>
@@ -8488,11 +8543,21 @@
         <title>Return Values</title>
 
        <itemizedlist>
-          <listitem>
+         <listitem>
            <para>
-             <literal></literal>
+             <literal>0</literal> OK, found a row
            </para>
          </listitem>
+         <listitem>
+           <para>
+             <literal>HA_ERR_END_OF_FILE</literal> No rows in range
+           </para>
+         </listitem>
+         <listitem>
+           <para>
+             <literal>#</literal> Error code
+           </para>
+         </listitem>
        </itemizedlist>
 
       </refsection>
@@ -8534,6 +8599,7 @@
        <title>Description</title>
 
     <para>This is the <function>read_time</function>
method.</para>
+        <para>This will never be called if you do not implement
indexes.</para>
       </refsection>
 
       <refsection>
@@ -9359,6 +9425,12 @@
        <title>Description</title>
 
     <para>This is the <function>rnd_init</function>
method.</para>
+        <para>unlike index_init(), rnd_init() can be called two times
+          without rnd_end() in between (it only makes sense if scan=1).
+          then the second call should prepare for the new table scan
+          (e.g if rnd_init allocates the cursor, second call should
+          position it to the start of the table, no need to deallocate
+          and allocate it again</para>
       </refsection>
 
       <refsection>
@@ -9607,6 +9679,7 @@
        <title>Description</title>
 
     <para>This is the <function>scan_time</function>
method.</para>
+        <para>Called in test_quick_select to determine if indexes should be
used.</para>
       </refsection>
 
       <refsection>
@@ -10077,6 +10150,9 @@
        <title>Description</title>
 
     <para>This is the <function>table_flags</function>
method.</para>
+        <para>This is a list of flags that says what the storage engine
+          implements. The current table flags are documented in
+          handler.h</para>
       </refsection>
 
       <refsection>
@@ -10127,7 +10203,7 @@
 
       <refnamediv>
         <refname>table_type</refname>
-        <refpurpose></refpurpose>
+        <refpurpose>The name that will be used for display
purposes</refpurpose>
       </refnamediv>
 
       <refsynopsisdiv>