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

[eherman]

Author: eherman
Date: 2005-10-21 22:17:04 +0200 (Fri, 21 Oct 2005)
New Revision: 134

Log:
tiny additions.

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 18:36:31 UTC (rev 133)
+++ branches/MikePluggable/trunk/refman-5.1/custom-engine.xml	2005-10-21 20:17:04 UTC (rev 134)
@@ -1076,6 +1076,14 @@
        <title>Description</title>
 
     <para>This is the <function>close</function> method.</para>
+        <para>Closes a table. A good time to free any resources
+          that we have allocated.
+          </para><para>
+          Called from sql_base.cc, sql_select.cc, and table.cc.
+          In sql_select.cc it is only used to close up temporary tables or during
+          the process where a temporary table is converted over to being a
+          myisam table.
+          For sql_base.cc look at close_data_tables().</para>
       </refsection>
 
       <refsection>
@@ -1626,6 +1634,17 @@
        <title>Description</title>
 
     <para>This is the <function>delete_row</function> method.</para>
+        <para>buf will contain a copy of the row to be deleted.
+          The server will call this right after the current row has been called (from
+          either a previous rnd_nexT() or index call).
+          If you keep a pointer to the last row or can access a primary key it will
+          make doing the deletion quite a bit easier.
+          Keep in mind that the server does no guarentee consecutive deletions. ORDER BY
+          clauses can be used.
+          </para><para>
+          Called in sql_acl.cc and sql_udf.cc to manage internal table information.
+          Called in sql_delete.cc, sql_insert.cc, and sql_select.cc. In sql_select it is
+          used for removing duplicates while in insert it is used for REPLACE calls.</para>
       </refsection>
 
       <refsection>
@@ -5938,6 +5957,7 @@
        <title>Description</title>
 
     <para>This is the <function>index_next</function> method.</para>
+        <para>Used to read forward through the index.</para>
       </refsection>
 
       <refsection>
@@ -6138,6 +6158,9 @@
        <title>Description</title>
 
     <para>This is the <function>index_read</function> method.</para>
+        <para>Positions an index cursor to the index specified in the handle. Fetches the
+          row if available. If the key value is null, begin at the first key of the
+          index.</para>
       </refsection>
 
       <refsection>
@@ -6212,6 +6235,8 @@
        <title>Description</title>
 
     <para>This is the <function>index_read_idx</function> method.</para>
+        <para>Positions an index cursor to the index specified in key. Fetches the
+          row if any.  This is only used to read whole keys.</para>
       </refsection>
 
       <refsection>
@@ -7765,6 +7790,13 @@
        <title>Description</title>
 
     <para>This is the <function>open</function> method.</para>
+        <para>Used for opening tables. The name will be the name of the file.
+          A table is opened when it needs to be opened. For instance
+          when a request comes in for a select on the table (tables are not
+          open and closed for each request, they are cached).
+          </para><para>
+          Called from handler.cc by handler::ha_open(). The server opens all tables by
+          calling ha_open() which then calls the handler specific open().</para>
       </refsection>
 
       <refsection>
@@ -10507,6 +10539,20 @@
        <title>Description</title>
 
     <para>This is the <function>update_row</function> method.</para>
+        <para>old_data will have
+          the previous row record in it, while new_data will have the newest data in
+          it.</para><para>
+          The server can do updates based on ordering if an ORDER BY
+          clause was used. Consecutive ordering is not guarenteed.
+          </para><para>
+          Currently new_data will not have an updated auto_increament record, or
+          and updated timestamp field. You can do these for example by doing these:
+          if (table->timestamp_field_type &amp; TIMESTAMP_AUTO_SET_ON_UPDATE)
+          table->timestamp_field->set_time();
+          if (table->next_number_field &amp;&amp; record == table->record[0])
+          update_auto_increment();
+          </para><para>
+          Called from sql_select.cc, sql_acl.cc, sql_update.cc, and sql_insert.cc.</para>
       </refsection>
 
       <refsection>
@@ -10642,13 +10688,47 @@
        <title>Description</title>
 
     <para>This is the <function>write_row</function> method.</para>
+        <para>write_row() inserts a row. No extra() hint is given currently if a bulk load
+          is happeneding. 
+          buf is a byte array of data with a size of table->s->reclength
+          </para><para>
+          You can use the field information to extract the data from the native byte 
+          array type.
+          Example of this would be:
+          for (Field **field=table->field ; *field ; field++)
+          {
+          ...
+          }
+          </para><para>
+          BLOBs must be handled specially:
+            
+            
+            for (ptr= table->s->blob_field, end= ptr + table->s->blob_fields ;
+            ptr != end ;
+            ptr++)
+            {
+              char *data_ptr;
+              uint32 size= ((Field_blob*) table->field[*ptr])->get_length();
+              ((Field_blob*) table->field[*ptr])->get_ptr(&amp;data_ptr);
+              ...            
+            }
+          </para><para>
+          See ha_tina.cc for an example of extracting all of the data as strings.
+          ha_berekly.cc has an example of how to store it intact by "packing" it
+          for ha_berkeley's own native storage type.
+          </para><para>
+          See the note for update_row() on auto_increments and timestamps. This
+          case also applied to write_row().
+          </para><para>
+          Called from item_sum.cc, item_sum.cc, sql_acl.cc, sql_insert.cc,
+          sql_insert.cc, sql_select.cc, sql_table.cc, sql_udf.cc, and sql_update.cc.</para>
       </refsection>
 
       <refsection>
         <title>Parameters</title>
 
         <itemizedlist>
-          <listitem><para><literal>buf</literal></para></listitem>
+          <listitem><para><literal>buf</literal> byte array of data</para></listitem>
         </itemizedlist>
 
       </refsection>