List:Commits« Previous MessageNext Message »
From:jon Date:January 31 2006 2:12pm
Subject:bk commit into 5.1 tree (jon:1.2103)
View as plain text  
Below is the list of changes that have just been committed into a local
5.1 repository of jon. When jon does a push these changes will
be propagated to the main repository and, within 24 hours after the
push, to the public repository.
For information on how to access the public repository
see http://dev.mysql.com/doc/mysql/en/installing-source-tree.html

ChangeSet
  1.2103 06/02/01 00:11:52 jon@stripped +3 -0
  More fixes/edits for NDB API docs.

  storage/ndb/include/ndbapi/NdbRecAttr.hpp
    1.19 06/02/01 00:11:43 jon@stripped +63 -63
    Fixes/edits for NDB API docs.

  storage/ndb/include/ndbapi/NdbOperation.hpp
    1.35 06/02/01 00:11:43 jon@stripped +433 -396
    Fixes/edits for NDB API docs.

  storage/ndb/include/ndbapi/NdbIndexStat.hpp
    1.3 06/02/01 00:11:43 jon@stripped +48 -40
    Fixes/edits for NDB API docs.

# This is a BitKeeper patch.  What follows are the unified diffs for the
# set of deltas contained in the patch.  The rest of the patch, the part
# that BitKeeper cares about, is below these diffs.
# User:	jon
# Host:	gigan.site
# Root:	/home/jon/bk/mysql-5.1-ndbapi-working

--- 1.34/storage/ndb/include/ndbapi/NdbOperation.hpp	2005-11-07 21:19:05 +10:00
+++ 1.35/storage/ndb/include/ndbapi/NdbOperation.hpp	2006-02-01 00:11:43 +10:00
@@ -56,19 +56,20 @@
    */
 
   /**
-   * Lock when performing read
+   * Lock when performing read.
    */
   
   enum LockMode {
-    LM_Read                 ///< Read with shared lock
+    LM_Read                 ///< Read with shared lock.
 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
     = 0
 #endif
-    ,LM_Exclusive           ///< Read with exclusive lock
+    ,LM_Exclusive           ///< Read with exclusive lock.
 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
     = 1
 #endif
-    ,LM_CommittedRead       ///< Ignore locks, read last committed value
+    ,LM_CommittedRead       ///< Ignore locks; read the last 
+                                         ///< committed value.
 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
     = 2,
     LM_Dirty = 2
@@ -76,138 +77,139 @@
   };
 
   /**
-   * Define the NdbOperation to be a standard operation of type insertTuple.
-   * When calling NdbTransaction::execute, this operation 
-   * adds a new tuple to the table.
-   *
-   * @return 0 if successful otherwise -1.
-   */		
-  virtual int 			insertTuple();
-		
-  /**
-   * Define the NdbOperation to be a standard operation of type updateTuple.
-   * When calling NdbTransaction::execute, this operation 
-   * updates a tuple in the table.
+   * Defines the NdbOperation as a standard operation of type 
+   * <code>insertTuple</code>. When calling NdbTransaction::execute(), 
+   * this operation adds a new tuple to the table.
+   *
+   * @return 0 on success, otherwise -1.
+   */   
+  virtual int       insertTuple();
+    
+  /**
+   * Define the NdbOperation as a standard operation of type 
+   * <code>updateTuple</code>. When calling NdbTransaction::execute(), 
+   * this operation updates a tuple in the table.
    *
-   * @return 0 if successful otherwise -1.
+   * @return 0 on success, otherwise -1.
    */  
-  virtual int 			updateTuple();
+  virtual int       updateTuple();
 
   /**
-   * Define the NdbOperation to be a standard operation of type writeTuple.
-   * When calling NdbTransaction::execute, this operation 
-   * writes a tuple to the table.
-   * If the tuple exists, it updates it, otherwise an insert takes place.
+   * Defines the NdbOperation as a standard operation of type 
+   * <code>writeTuple</code>. When calling NdbTransaction::execute(), 
+   * this operation writes a tuple to the table. If the tuple exists, it 
+   * is updated; otherwise, a new tuple is inserted.
    *
-   * @return 0 if successful otherwise -1.
+   * @return 0 on success, otherwise -1.
    */  
-  virtual int 			writeTuple();
+  virtual int       writeTuple();
 
   /**
-   * Define the NdbOperation to be a standard operation of type deleteTuple.
-   * When calling NdbTransaction::execute, this operation 
-   * delete a tuple.
+   * Defines the NdbOperation as a standard operation of type 
+   * <code>deleteTuple</code>. When calling NdbTransaction::execute(), 
+   * this operation deletes a tuple.
    *
-   * @return 0 if successful otherwise -1.
+   * @return 0 on success, otherwise -1.
    */
-  virtual int 			deleteTuple();
-		
+  virtual int       deleteTuple();
+    
   /**
-   * Define the NdbOperation to be a standard operation of type readTuple.
-   * When calling NdbTransaction::execute, this operation 
-   * reads a tuple.
+   * Defines the NdbOperation as a standard operation of type 
+   * <code>readTuple</code>. When calling NdbTransaction::execute(), 
+   * this operation reads a tuple.
    *
-   * @return 0 if successful otherwise -1.
+   * @return 0 on success, otherwise -1.
    */
-  virtual int 			readTuple(LockMode);
+  virtual int       readTuple(LockMode);
 
 #ifndef DOXYGEN_SHOULD_SKIP_DEPRECATED
   /**
-   * Define the NdbOperation to be a standard operation of type readTuple.
-   * When calling NdbTransaction::execute, this operation 
-   * reads a tuple.
+   * Defines the NdbOperation as a standard operation of type 
+   * <code>readTuple</code>. When calling NdbTransaction::execute(), 
+   * this operation reads a tuple.
    *
-   * @return 0 if successful otherwise -1.
+   * @return 0 on success, otherwise -1.
    */  
-  virtual int 			readTuple();				
+  virtual int       readTuple();        
 
   /**
-   * Define the NdbOperation to be a standard operation of type 
-   * readTupleExclusive.
-   * When calling NdbTransaction::execute, this operation 
-   * read a tuple using an exclusive lock.
+   * Defines the NdbOperation as a standard operation of type 
+   * <code>readTupleExclusive</code>. When calling 
+   * NdbTransaction::execute(), this operation reads a tuple using an 
+   * exclusive lock.
    *
-   * @return 0 if successful otherwise -1.
+   * @return 0 on success, otherwise -1.
    */
-  virtual int 			readTupleExclusive();
+  virtual int       readTupleExclusive();
 
   /**
-   * Define the NdbOperation to be a standard operation of type 
-   * simpleRead.
-   * When calling NdbTransaction::execute, this operation 
-   * reads an existing tuple (using shared read lock), 
-   * but releases lock immediately after read.
+   * Defines the NdbOperation as a standard operation of type 
+   * <code>simpleRead</code>. When calling NdbTransaction::execute(), 
+   * this operation reads an existing tuple using a shared read lock, 
+   * and releases the lock immediately following the read.
    *
-   * @note  Using this operation twice in the same transaction
-   *        may produce different results (e.g. if there is another
-   *        transaction which updates the value between the
-   *        simple reads).
+   * @note  Using this operation twice within the same transaction
+   *        may produce different results. This is likely to occur if 
+   *        another transaction updates the value between reads.
    *
-   * Note that simpleRead can read the value from any database node while
-   * standard read always read the value on the database node which is 
-   * primary for the record.
+   * Note that <code>simpleRead</code> can read the value from any 
+   * storage node while a standard read always reads the value on the 
+   * storage node which is primary for the record.
    *
-   * @return 0 if successful otherwise -1.
+   * @return 0 on success, otherwise -1.
    */
-  virtual int			simpleRead();
+  virtual int     simpleRead();
 
   /**
-   * Define the NdbOperation to be a standard operation of type committedRead.
-   * When calling NdbTransaction::execute, this operation 
-   * read latest committed value of the record.
+   * Defines the NdbOperation as a standard operation of type 
+   * <code>committedRead</code>. When calling NdbTransaction::execute(), 
+   * this operation reads the latest committed value of the record.
    *
-   * This means that if another transaction is updating the 
-   * record, then the current transaction will not wait.  
-   * It will instead use the latest committed value of the 
+   * This means that if another transaction is updating the record, then 
+   * the current transaction will not wait for the other transaction to 
+   * be completed. It will instead use the latest committed value of the 
    * record.
-   * dirtyRead is a deprecated name for committedRead
    *
-   * @return 0 if successful otherwise -1.
-   * @depricated
+   * @note  <code>dirtyRead</code> is a deprecated name for 
+   *        <code>committedRead</code>
+   *
+   * @return 0 on success, otherwise -1.
+   * @deprecated
    */
-  virtual int			dirtyRead();
+  virtual int     dirtyRead();
 
   /**
-   * Define the NdbOperation to be a standard operation of type committedRead.
-   * When calling NdbTransaction::execute, this operation 
-   * read latest committed value of the record.
+   * Defines the NdbOperation as a standard operation of type 
+   * <code>committedRead</code>. When calling NdbTransaction::execute(), 
+   * this operation reads the latest committed value of the record.
    *
-   * This means that if another transaction is updating the 
-   * record, then the current transaction will not wait.  
-   * It will instead use the latest committed value of the 
+   * This means that if another transaction is updating the record, then 
+   * the current transaction will not wait for the other transaction to 
+   * be completed. It will instead use the latest committed value of the 
    * record.
    *
-   * @return 0 if successful otherwise -1.
+   * @return 0 on success, otherwise -1.
    */
-  virtual int			committedRead();
+  virtual int     committedRead();
 
   /**
-   * Define the NdbOperation to be a standard operation of type dirtyUpdate.
-   * When calling NdbTransaction::execute, this operation 
-   * updates without two-phase commit.
+   * Defines the NdbOperation as a standard operation of type 
+   * <code>dirtyUpdate</code>. When calling NdbTransaction::execute(), 
+   * this operation updates without performing a two-phase commit.
    *
-   * @return 0 if successful otherwise -1.
+   * @return 0 on success, otherwise -1.
    */
-  virtual int			dirtyUpdate();
+  virtual int     dirtyUpdate();
 
   /**
-   * Define the NdbOperation to be a standard operation of type dirtyWrite.
-   * When calling NdbTransaction::execute, this operation 
-   * writes without two-phase commit.
+   * Defines the NdbOperation as a standard operation of type 
+   * <code>dirtyWrite</code>. When calling NdbTransaction::execute(), 
+   * this operation 
+   * writes without without performing a two-phase commit.
    *
-   * @return 0 if successful otherwise -1.
+   * @return 0 on success, otherwise -1.
    */
-  virtual int			dirtyWrite();
+  virtual int     dirtyWrite();
 #endif
 
 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
@@ -218,18 +220,18 @@
    */
 
   /**
-   * Update a tuple using an interpreted program.
+   * Updates a tuple using an interpreted program.
    *
-   * @return 0 if successful otherwise -1.
+   * @return 0 on success, otherwise -1.
    */  
-  virtual int			interpretedUpdateTuple();
-		
+  virtual int     interpretedUpdateTuple();
+    
   /**
-   * Delete a tuple using an interpreted program.
+   * Deletes a tuple using an interpreted program.
    *
-   * @return 0 if successful otherwise -1.
+   * @return 0 on success, otherwise -1.
    */
-  virtual int			interpretedDeleteTuple();
+  virtual int     interpretedDeleteTuple();
 #endif
 
   /** @} *********************************************************************/
@@ -239,44 +241,43 @@
    * @{
    */
   /**
-   * Define a search condition with equality.
-   * The condition is true if the attribute has the given value.
-   * To set search conditions on multiple attributes,
-   * use several equals (then all of them must be satisfied for the
-   * tuple to be selected).
+   * Defines a search condition that uses an equality. The condition is 
+   * true if the attribute has the given value. To set search conditions 
+   * on multiple attributes, use several equalities, in which case all 
+   * of them must be satisfied in order for the tuple to be selected.
    *
-   * @note For insertTuple() it is also allowed to define the
-   *       search key by using setValue().
+   * @note For insertTuple(), you may also define the search key by 
+   *       using setValue().
    *
    * @note There are 10 versions of equal() with
    *       slightly different parameters.
    *
-   * @note  If attribute has fixed size, value must include all bytes.
-   *        In particular a Char must be native-blank padded.
-   *        If attribute has variable size, value must start with
-   *        1 or 2 little-endian length bytes (2 if Long*).
+   * @note  If the attribute is of fixed size, the value must include 
+   *        all bytes. In particular, a CHAR must be native-blank 
+   *        padded. If the attribute is of variable size, the value must 
+   *        start with 1 or 2 little-endian length bytes (2 if Long*).
    * 
-   * @param   anAttrName   Attribute name 
+   * @param   anAttrName   Attribute name.
    * @param   aValue       Attribute value.
-   * @return               -1 if unsuccessful. 
+   * @return               -1 on failure. 
    */
 #ifndef DOXYGEN_SHOULD_SKIP_DEPRECATED
   int  equal(const char* anAttrName, const char* aValue, Uint32 len);
 #endif
   int  equal(const char* anAttrName, const char* aValue);
-  int  equal(const char* anAttrName, Int32 aValue);	
-  int  equal(const char* anAttrName, Uint32 aValue);	
-  int  equal(const char* anAttrName, Int64 aValue);	
+  int  equal(const char* anAttrName, Int32 aValue); 
+  int  equal(const char* anAttrName, Uint32 aValue);  
+  int  equal(const char* anAttrName, Int64 aValue); 
   int  equal(const char* anAttrName, Uint64 aValue);
 #ifndef DOXYGEN_SHOULD_SKIP_DEPRECATED
   int  equal(Uint32 anAttrId, const char* aValue, Uint32 len);
 #endif
   int  equal(Uint32 anAttrId, const char* aValue);
-  int  equal(Uint32 anAttrId, Int32 aValue);	
-  int  equal(Uint32 anAttrId, Uint32 aValue);	
-  int  equal(Uint32 anAttrId, Int64 aValue);	
+  int  equal(Uint32 anAttrId, Int32 aValue);  
+  int  equal(Uint32 anAttrId, Uint32 aValue); 
+  int  equal(Uint32 anAttrId, Int64 aValue);  
   int  equal(Uint32 anAttrId, Uint64 aValue);
-	
+  
   /** @} *********************************************************************/
   /** 
    * @name Specify Attribute Actions for Operations
@@ -284,76 +285,78 @@
    */
 
   /**
-   * Defines a retrieval operation of an attribute value.
-   * The NDB API allocate memory for the NdbRecAttr object that
-   * will hold the returned attribute value. 
-   *
-   * @note Note that it is the applications responsibility
-   *       to allocate enough memory for aValue (if non-NULL).
-   *       The buffer aValue supplied by the application must be
-   *       aligned appropriately.  The buffer is used directly
-   *       (avoiding a copy penalty) only if it is aligned on a
-   *       4-byte boundary and the attribute size in bytes
-   *       (i.e. NdbRecAttr::attrSize times NdbRecAttr::arraySize is
-   *       a multiple of 4).
+   * Defines a retrieval operation for an attribute value. The NDB API 
+   * allocates memory for the NdbRecAttr object that is to hold the 
+   * returned attribute value. 
+   *
+   * @note It is the application's responsibility to allocate sufficient 
+   *       memory for <code>aValue</code> (if non-<code>NULL</code>).
+   *       The buffer supplied by the application must be aligned 
+   *       appropriately.  The buffer is used directly (thus avoiding a 
+   *       copy penalty) only if it is aligned on a 4-byte boundary and 
+   *       the attribute size in bytes 
+   *       (<b><code>NdbRecAttr::attrSize</code> times 
+   *       <code>NdbRecAttr::arraySize</code></b> is an even multiple of 
+   *       4).
    *
-   * @note There are two versions of NdbOperation::getValue with
+   * @note There are two versions of NdbOperation::getValue() with
    *       slightly different parameters.
    *
-   * @note This method does not fetch the attribute value from 
-   *       the database!  The NdbRecAttr object returned by this method 
-   *       is <em>not</em> readable/printable before the 
-   *       transaction has been executed with NdbTransaction::execute.
-   *
-   * @param anAttrName  Attribute name 
-   * @param aValue      If this is non-NULL, then the attribute value 
-   *                    will be returned in this parameter.<br>
-   *                    If NULL, then the attribute value will only 
-   *                    be stored in the returned NdbRecAttr object.
+   * @note This method does <em>not</em> fetch the attribute value from 
+   *       the database. The NdbRecAttr object returned by this method 
+   *       cannot be read or printed before the transaction has been 
+   *       executed using NdbTransaction::execute().
+   *
+   * @param anAttrName  Attribute name. 
+   * @param aValue      If this is non-<code>NULL</code>, then the 
+   *                    attribute value will be returned in this 
+   *                    parameter.<br>
+   *                    If it is <code>NULL</code>, then the attribute 
+   *                    value will merely be stored in the returned 
+   *                    NdbRecAttr object.
    * @return            An NdbRecAttr object to hold the value of 
-   *                    the attribute, or a NULL pointer 
-   *                    (indicating error).
+   *                    the attribute, or a <code>NULL</code> pointer 
+   *                    (indicating an error).
    */
   NdbRecAttr* getValue(const char* anAttrName, char* aValue = 0);
   NdbRecAttr* getValue(Uint32 anAttrId, char* aValue = 0);
   NdbRecAttr* getValue(const NdbDictionary::Column*, char* val = 0);
   
   /**
-   * Define an attribute to set or update in query.
+   * Defines an attribute to be set or updated in a query.
    *
-   * To set a NULL value, use the following construct:
+   * To set a <code>NULL</code> value, use the following construct:
    * @code
    *   setValue("ATTR_NAME", (char*)NULL);
    * @endcode
    * 
-   * There are a number of NdbOperation::setValue methods that 
-   * take a certain type as input
-   * (pass by value rather than passing a pointer). 
-   * As the interface is currently implemented it is the responsibility 
-   * of the application programmer to use the correct types.
-   *
-   * The NDB API will however check that the application sends
-   * a correct length to the interface as given in the length parameter.  
-   * The passing of char* as the value can contain any type or 
-   * any type of array. 
-   * If length is not provided or set to zero, 
-   * then the API will assume that the pointer
-   * is correct and not bother with checking it.
-   *
-   * @note For insertTuple() the NDB API will automatically detect that 
-   *       it is supposed to use equal() instead. 
+   * There are a number of NdbOperation::setValue() methods that take a 
+   * specified type as input. ou should pass this by value rather than 
+   * pass a pointer. As the interface is currently implemented, it is 
+   * the responsibility of the application programmer to use the correct 
+   * type with each of these methods.
+   *
+   * The NDB API does check that the application sends a correct length 
+   * to the interface as given in the length parameter. Passing
+   * <code>char*</code> as the value lets it contain any type or any 
+   * type of array. However, if the length is not provided or is set to 
+   * zero, then the NDB API assumes that the pointer is correct and does 
+   * not check it.
+   *
+   * @note For insertTuple(): 
+   *        - The NDB API automatically detects that it should use 
+   *        equal() instead.
+   *        - it is not necessary to use setValue() on key attributes 
+   *        before other attributes.
    *
-   * @note For insertTuple() it is not necessary to use
-   *       setValue() on key attributes before other attributes.
-   *
-   * @note There are 14 versions of NdbOperation::setValue with
+   * @note There are 14 versions of NdbOperation::setValue(), each with
    *       slightly different parameters.
    *
-   * @note See note under equal() about value format and length.
+   * @note See the note under equal() about value format and length.
    * 
    * @param anAttrName     Name (or Id) of attribute.
    * @param aValue         Attribute value to set.
-   * @return               -1 if unsuccessful.
+   * @return               -1 on failure.
    */
 #ifndef DOXYGEN_SHOULD_SKIP_DEPRECATED
   int  setValue(const char* anAttrName, const char* aValue, Uint32 len);
@@ -378,12 +381,12 @@
   int  setValue(Uint32 anAttrId, double aValue);
 
   /**
-   * This method replaces getValue/setValue for blobs.  It creates
-   * a blob handle NdbBlob.  A second call with same argument returns
-   * the previously created handle.  The handle is linked to the
+   * This method replaces getValue() or setValue() for blobs.  It 
+   * creates a blob handle NdbBlob. A second call with the same argument 
+   * returns the previously created handle.  The handle is linked to the
    * operation and is maintained automatically.
    *
-   * See NdbBlob for details.
+   * See @ref NdbBlob for details.
    */
   virtual NdbBlob* getBlobHandle(const char* anAttrName);
   virtual NdbBlob* getBlobHandle(Uint32 anAttrId);
@@ -396,17 +399,17 @@
    */
 
   /**
-   * Interpreted program instruction: Add a value to an attribute.
+   * Interpreted program instruction: Adds a value to an attribute.
    *
-   * @note Destroys the contents of registers 6 and 7.
-   *       (The instruction uses these registers for its operation.)
+   * @note Calling this method destroys the contents of registers 6 and 
+   *       7, which it uses for its operations.
    *
-   * @note There are four versions of NdbOperation::incValue with
-   *       slightly different parameters.
+   * @note There are four versions of NdbOperation::incValue(), each 
+   *       with slightly different parameters.
    *
    * @param anAttrName     Attribute name.
    * @param aValue         Value to add.
-   * @return               -1 if unsuccessful.
+   * @return               -1 on failure.
    */
   int   incValue(const char* anAttrName, Uint32 aValue);
   int   incValue(const char* anAttrName, Uint64 aValue);
@@ -415,17 +418,17 @@
 
   /**
    * Interpreted program instruction:
-   * Subtract a value from an attribute in an interpreted operation.
+   * Subtracts a value from an attribute in an interpreted operation.
    *
    * @note Destroys the contents of registers 6 and 7.
    *       (The instruction uses these registers for its operation.)
    *
-   * @note There are four versions of NdbOperation::subValue with
-   *       slightly different parameters.
+   * @note Calling this method destroys the contents of registers 6 and 
+   *       7, which it uses for its operations.
    *
    * @param anAttrName    Attribute name.
    * @param aValue        Value to subtract.
-   * @return              -1 if unsuccessful.
+   * @return              -1 on failure.
    */
   int   subValue(const char* anAttrName, Uint32 aValue);
   int   subValue(const char* anAttrName, Uint64 aValue);
@@ -434,118 +437,119 @@
 
   /**
    * Interpreted program instruction:
-   * Define a jump label in an interpreted operation.
+   * Defines a jump label in an interpreted operation.
    *
-   * @note The labels are automatically numbered starting with 0.  
-   *       The parameter used by NdbOperation::def_label should 
-   *       match the automatic numbering to make it easier to 
-   *       debug the interpreted program.
+   * @note The labels are automatically numbered starting with 0. The 
+   *       parameter used by NdbOperation::def_label() should match the 
+   *       automatic numbering in order to faciliate debugging.
    * 
    * @param labelNumber   Label number.
-   * @return              -1 if unsuccessful.
+   * @return              -1 on failure.
    */
   int   def_label(int labelNumber);
 
   /**
    * Interpreted program instruction:
-   * Add two registers into a third.
+   * Adds two registers into a third.
    *
    * @param RegSource1   First register.
    * @param RegSource2   Second register.
-   * @param RegDest      Destination register where the result will be stored.
-   * @return -1 if unsuccessful.
+   * @param RegDest      Destination register (where the result should 
+   *                     be stored).
+   * @return -1 on failure.
    */
   int   add_reg(Uint32 RegSource1, Uint32 RegSource2, Uint32 RegDest);
 
   /**
    * Interpreted program instruction:
-   * Substract RegSource1 from RegSource2 and put the result in RegDest.
+   * Substracts <var>RegSource1</var> from <var>RegSource2</var>, and 
+   ) places the result in <var>RegDest</var>.
    *
    * @param RegSource1   First register.
    * @param RegSource2   Second register.
-   * @param RegDest      Destination register where the result will be stored.
-   * @return             -1 if unsuccessful.
+   * @param RegDest      Destination register (where the result should 
+   *                     be stored).
    */
   int   sub_reg(Uint32 RegSource1, Uint32 RegSource2, Uint32 RegDest);
 
   /**
    * Interpreted program instruction:
-   * Load a constant into a register.
+   * Loads a constant into a register.
    *
    * @param RegDest      Destination register.
    * @param Constant     Value to load.
-   * @return             -1 if unsuccessful.
+   * @return             -1 on failure.
    */
   int   load_const_u32(Uint32 RegDest, Uint32 Constant);
   int   load_const_u64(Uint32 RegDest, Uint64 Constant);
 
   /**
    * Interpreted program instruction:
-   * Load NULL value into a register.
+   * Loads a <code>NULL</code> value into a register.
    *
    * @param RegDest      Destination register.
-   * @return             -1 if unsuccessful.
+   * @return             -1 on failure.
    */ 
   int   load_const_null(Uint32 RegDest);
 
   /**
    * Interpreted program instruction:
-   * Read an attribute into a register.
+   * Reads an attribute into a register.
    *
    * @param anAttrName   Attribute name.
    * @param RegDest      Destination register.
-   * @return             -1 if unsuccessful.
+   * @return             -1 on failure.
    */
   int   read_attr(const char* anAttrName, Uint32 RegDest);
 
   /**
    * Interpreted program instruction:
-   * Write an attribute from a register. 
+   * Writes an attribute from a register. 
    *
    * @param anAttrName   Attribute name.
    * @param RegSource    Source register.
-   * @return             -1 if unsuccessful.
+   * @return             -1 on failure.
    */
   int   write_attr(const char* anAttrName, Uint32 RegSource);
 
   /**
    * Interpreted program instruction:
-   * Read an attribute into a register.
+   * Reads an attribute into a register.
    *
-   * @param anAttrId the attribute id.
-   * @param RegDest the destination register.
-   * @return -1 if unsuccessful.
+   * @param anAttrId  The attribute ID.
+   * @param RegDest   The destination register.
+   * @return          -1 on failure.
    */
   int   read_attr(Uint32 anAttrId, Uint32 RegDest);
 
   /**
    * Interpreted program instruction:
-   * Write an attribute from a register. 
+   * Writes an attribute from a register. 
    *
-   * @param anAttrId the attribute id.
-   * @param RegSource the source register.
-   * @return -1 if unsuccessful.
+   * @param anAttrId  The attribute ID.
+   * @param RegDest   The destination register.
+   * @return          -1 on failure.
    */
   int   write_attr(Uint32 anAttrId, Uint32 RegSource);
 
   /**
    * Interpreted program instruction:
-   * Define a search condition. Last two letters in the function name 
-   * describes the search condition.
-   * The condition compares RegR with RegL and therefore appears
-   * to be reversed.
+   * Defines a search condition. Note that the last two letters of the 
+   * function name describe the search condition.
+   * The condition compares <var>RegR</var> with <var>RegL</var> and 
+   * therefore appears to be reversed.
    *
    * - ge RegR >= RegL
    * - gt RegR >  RegL
    * - le RegR <= RegL
    * - lt RegR <  RegL
-   * - eq RegR =  RegL
+   * - eq RegR ==  RegL
    * - ne RegR <> RegL
    *
-   * @param RegLvalue left value. 
-   * @param RegRvalue right value.
-   * @param Label the label to jump to.
-   * @return -1 if unsuccessful.
+   * @param RegLvalue Left value. 
+   * @param RegRvalue Right value.
+   * @param Label     The label to jump to.
+   * @return          -1 on failure.
    */
   int   branch_ge(Uint32 RegLvalue, Uint32 RegRvalue, Uint32 Label);
   int   branch_gt(Uint32 RegLvalue, Uint32 RegRvalue, Uint32 Label);
@@ -556,50 +560,54 @@
 
   /**
    * Interpreted program instruction:
-   * Jump to Label if RegLvalue is not NULL.
+   * Jumps to <var>Label</var> if <var>RegLvalue</var> is not 
+   * <code>NULL</code>.
    *
-   * @param RegLvalue the value to check.
-   * @param Label the label to jump to.
-   * @return -1 if unsuccessful. 
+   * @param RegLvalue The value to check.
+   * @param Label     The label to jump to.
+   * @return          -1 on failure. 
    */
   int   branch_ne_null(Uint32 RegLvalue, Uint32 Label);
 
   /**
    * Interpreted program instruction:
-   * Jump to Label if RegLvalue is equal to NULL.
+   * Jumps to <var>Label</var> if <var>RegLvalue</var> is 
+   * <code>NULL</code>.
    *
    * @param  RegLvalue  Value to check.
    * @param  Label      Label to jump to.
-   * @return -1 if unsuccessful. 
+   * @return            -1 on failure. 
    */
   int   branch_eq_null(Uint32 RegLvalue, Uint32 Label);
 
   /**
    * Interpreted program instruction:
-   * Jump to Label.
+   * Jumps to <var>Label</var>.
    *
    * @param  Label  Label to jump to.
-   * @return -1 if unsuccessful.
+   * @return -1 on failure.
    */
   int   branch_label(Uint32 Label);
 
   /**
-   * Interpreted program instruction:  branch after memcmp
-   * @param  ColId   Column to check
-   * @param  Label   Label to jump to
-   * @return -1 if unsuccessful
+   * Interpreted program instruction: 
+   * Branches after <code>memcmp</code>.
+   * @param  ColId  Column to check.
+   * @param  Label  Label to jump to.
+   * @return        -1 on failure.
    */
   int branch_col_eq_null(Uint32 ColId, Uint32 Label);
   int branch_col_ne_null(Uint32 ColId, Uint32 Label);
 
   /**
-   * Interpreted program instruction:  branch after memcmp
-   * @param  ColId   column to check
-   * @param  val     search value
-   * @param  len     length of search value   
-   * @param  nopad   force non-padded comparison for a Char column
-   * @param  Label   label to jump to
-   * @return -1 if unsuccessful
+   * Interpreted program instruction: 
+   * Branches after <code>memcmp</code>.
+   * @param  ColId   Column to check.
+   * @param  val     Search value.
+   * @param  len     Length of search value.
+   * @param  nopad   Forces non-padded comparison for a CHAR column.
+   * @param  Label   Label to jump to.
+   * @return         -1 on failure.
    */
   int branch_col_eq(Uint32 ColId, const void * val, Uint32 len, 
 		    bool nopad, Uint32 Label);
@@ -619,31 +627,35 @@
 			 bool nopad, Uint32 Label);
   
   /**
-   * Interpreted program instruction: Exit with Ok
+   * Interpreted program instruction: 
+   * Exits with OK.
    *
-   * For scanning transactions,
-   * end interpreted operation and return the row to the application.
+   * For scanning transactions: 
+   * Ends interpreted operations and returns the row to the application.
    *
-   * For non-scanning transactions,
-   * exit interpreted program.
+   * For non-scanning transactions: 
+   * Exits the interpreted program.
    *
-   * @return -1 if unsuccessful.
+   * @return -1 on failure.
    */
-  int	interpret_exit_ok();
+  int interpret_exit_ok();
 
   /**
-   * Interpreted program instruction: Exit with Not Ok
+   * Interpreted program instruction: 
+   * Exits signalling failure.
    *
-   * For scanning transactions, 
-   * continue with the next row without returning the current row.
+   * For scanning transactions: 
+   * Continues with the next row without returning the current row.
    *
-   * For non-scanning transactions,
-   * abort the whole transaction.
+   * For non-scanning transactions:
+   * Aborts the entire transaction.
    *
-   * @note A method also exists without the error parameter.
+   * @note  There is also a similar method, but without the error 
+   *        parameter.
    * 
-   * @param ErrorCode   An error code given by the application programmer.
-   * @return            -1 if unsuccessful.
+   * @param ErrorCode     An error code supplied by the application 
+   *                      programmer.
+   * @return              -1 on failure.
    */
   int   interpret_exit_nok(Uint32 ErrorCode);
   int   interpret_exit_nok();
@@ -652,39 +664,40 @@
   /**
    * Interpreted program instruction:
    *
-   * For scanning transactions, 
-   * return this row, but no more from this fragment
+   * For scanning transactions: 
+   * Returns the current row, but returns no additional rows from the 
+   * current fragment.
    *
-   * For non-scanning transactions,
-   * abort the whole transaction.
+   * For non-scanning transactions:
+   * Aborts the entire transaction.
    *
-   * @return            -1 if unsuccessful.
+   * @return    -1 on failure.
    */
   int interpret_exit_last_row();
   
   /**
    * Interpreted program instruction:
-   * Define a subroutine in an interpreted operation.
+   * Defines a subroutine in an interpreted operation.
    *
-   * @param SubroutineNumber the subroutine number.
-   * @return -1 if unsuccessful.
+   * @param SubroutineNumber  The subroutine number.
+   * @return                  -1 on failure.
    */
   int   def_subroutine(int SubroutineNumber);
 
   /**
    * Interpreted program instruction:
-   * Call a subroutine.
+   * Calls a subroutine.
    *
-   * @param Subroutine the subroutine to call.
-   * @return -1 if unsuccessful. 
+   * @param Subroutine  The subroutine to call.
+   * @return            -1 on failure. 
    */
   int   call_sub(Uint32 Subroutine);
 
   /**
    * Interpreted program instruction:
-   * End a subroutine.
+   * Ends a subroutine.
    *
-   * @return -1 if unsuccessful. 
+   * @return    -1 on failure. 
    */
   int   ret_sub();
 #endif
@@ -697,26 +710,26 @@
    */
 
   /**
-   * Get the latest error code.
+   * Gets the latest error code.
    *
-   * @return error code.
+   * @return Error code.
    */
   const NdbError & getNdbError() const;
 
   /**
-   * Get the method number where the error occured.
+   * Gets the number of the method in which the error occured.
    * 
-   * @return method number where the error occured.
+   * @return Method number.
    */
   int getNdbErrorLine();
 
   /**
-   * Get table name of this operation.
+   * Gets the table name for this operation.
    */
   const char* getTableName() const;
 
   /**
-   * Get table object for this operation
+   * Gets the table object for this operation
    */
   const NdbDictionary::Table * getTable() const;
 
@@ -727,21 +740,21 @@
    * Type of operation
    */
   enum OperationType { 
-    ReadRequest = 0,              ///< Read operation
-    UpdateRequest = 1,            ///< Update Operation
-    InsertRequest = 2,            ///< Insert Operation
-    DeleteRequest = 3,            ///< Delete Operation
-    WriteRequest = 4,             ///< Write Operation
-    ReadExclusive = 5,            ///< Read exclusive
-    OpenScanRequest,              ///< Scan Operation
-    OpenRangeScanRequest,         ///< Range scan operation
-    NotDefined2,                  ///< Internal for debugging
-    NotDefined                    ///< Internal for debugging
+    ReadRequest = 0,              ///< Read operation.
+    UpdateRequest = 1,            ///< Update operation.
+    InsertRequest = 2,            ///< Insert operation.
+    DeleteRequest = 3,            ///< Delete operation
+    WriteRequest = 4,             ///< Write operation.
+    ReadExclusive = 5,            ///< Exclusive read.
+    OpenScanRequest,              ///< Scan operation.
+    OpenRangeScanRequest,         ///< Range scan operation.
+    NotDefined2,                  ///< Internal (for debugging only).
+    NotDefined                    ///< Internal (for debugging only).
   };
 #endif
 
   /**
-   * Return lock mode for operation
+   * Returns the lock mode used for this operation.
    */
   LockMode getLockMode() const { return theLockMode; }
 
@@ -749,7 +762,7 @@
   void setAbortOption(Int8 ao) { m_abortOption = ao; }
   
   /**
-   * Set/get partition key
+   * Sets or gets the partition key.
    */
   void setPartitionId(Uint32 id);
   void setPartitionHash(Uint32 key);
@@ -760,7 +773,7 @@
   int handle_distribution_key(const Uint64 *, Uint32 len);
 protected:
 /******************************************************************************
- * These are the methods used to create and delete the NdbOperation objects.
+ * These are the methods used to create and delete NdbOperation objects.
  *****************************************************************************/
 
   bool                  needReply();
@@ -768,15 +781,15 @@
  * These methods are service routines used by the other NDB API classes.
  *****************************************************************************/
 //--------------------------------------------------------------
-// Initialise after allocating operation to a transaction		      
+// Initialises after allocating an operation to a transaction         .
 //--------------------------------------------------------------
   int init(const class NdbTableImpl*, NdbTransaction* aCon);
   void initInterpreter();
 
-  NdbOperation(Ndb* aNdb);	
+  NdbOperation(Ndb* aNdb);  
   virtual ~NdbOperation();
-  void	next(NdbOperation*);		// Set next pointer		      
-  NdbOperation*	    next();	        // Get next pointer		       
+  void  next(NdbOperation*);    // Set next pointer         
+  NdbOperation*     next();         // Get next pointer          
 public:
 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
   const NdbOperation* next() const;
@@ -802,42 +815,46 @@
     ReceiveFinished
   };
 
-  OperationStatus   Status();	         	// Read the status information
+  OperationStatus   Status();           // Reads the status information.
   
-  void		    Status(OperationStatus);    // Set the status information
+  void        Status(OperationStatus);  // Sets the status information.
 
-  void		    NdbCon(NdbTransaction*);	// Set reference to connection
-  						// object.
+  void        NdbCon(NdbTransaction*);  // Sets a reference to the 
+                                        // connection object.
 
-  virtual void	    release();			// Release all operations 
-                                                // connected to
-					      	// the operations object.      
-  void		    setStartIndicator();
-
-/******************************************************************************
- * The methods below is the execution part of the NdbOperation
- * class. This is where the NDB signals are sent and received. The
- * operation can send TC[KEY/INDX]REQ, [INDX]ATTRINFO. 
- * It can receive TC[KEY/INDX]CONF, TC[KEY/INDX]REF, [INDX]ATTRINFO. 
- * When an operation is received in its fulness or a refuse message 
- * was sent, then the connection object is told about this situation.
- *****************************************************************************/
+  virtual void      release();          // Release all operations 
+                                        // associated with the 
+                                        // operations object.
+  void        setStartIndicator();
+
+/***********************************************************************
+ * The methods below comprise the execution portion of the NdbOperation
+ * class. This is where NDB signals are sent and received. The operation 
+ * can send signals of type <code>TCREQ</code>, <code>TCKEYREQ</code>, 
+ * <code>TCINDXREQ</code>, <code>ATTRINFO</code> or 
+ * <code>INDXATTRINFO</code>. It can receive the signals 
+ * <code>TCCONF</code>, <code>TCKEYCONF</code>, <code>TCINDXCONF</code>, 
+ * <code>TCREF</code>, <code>TCKEYREF</code>, <code>TCINDXREF</code>, 
+ * <code>ATTRINFO</code>, or <code>INDXATTRINFO</code>. When either an 
+ * operation is received in its entireity or a rejection message is 
+ * sent, then the connection object is informed of this situation.
+ **********************************************************************/
 
   int    doSend(int ProcessorId, Uint32 lastFlag);
-  virtual int	 prepareSend(Uint32  TC_ConnectPtr,
+  virtual int  prepareSend(Uint32  TC_ConnectPtr,
                              Uint64  TransactionId);
   virtual void   setLastFlag(NdbApiSignal* signal, Uint32 lastFlag);
     
-  int	 prepareSendInterpreted();            // Help routine to prepare*
+  int  prepareSendInterpreted();        // Help routine to prepare*
    
-  int	 receiveTCKEYREF(NdbApiSignal*); 
+  int  receiveTCKEYREF(NdbApiSignal*); 
 
-  int	 checkMagicNumber(bool b = true); // Verify correct object
+  int  checkMagicNumber(bool b = true); // Verify correct object
 
   int    checkState_TransId(NdbApiSignal* aSignal);
 
 /******************************************************************************
- *	These are support methods only used locally in this class.
+ *  These are support methods used locally in this class only.
 ******************************************************************************/
 
   virtual int equal_impl(const NdbColumnImpl*,const char* aValue);
@@ -858,105 +875,124 @@
   int insertATTRINFO(Uint32 aData);
   int insertATTRINFOloop(const Uint32* aDataPtr, Uint32 aLength);
   
-  int insertKEYINFO(const char* aValue,	
-		    Uint32 aStartPosition,	
-		    Uint32 aKeyLenInByte);
+  int insertKEYINFO(const char* aValue, 
+                            Uint32 aStartPosition,  
+                            Uint32 aKeyLenInByte);
   void reorderKEYINFO();
   
   virtual void setErrorCode(int aErrorCode);
   virtual void setErrorCodeAbort(int aErrorCode);
 
-  void        handleFailedAI_ElemLen();	   // When not all attribute data
-                                           // were received
+  void      handleFailedAI_ElemLen(); // When not all of the attribute
+                                      // data have been received.
 
-  int	      incCheck(const NdbColumnImpl* anAttrObject);
-  int	      initial_interpreterCheck();
-  int	      intermediate_interpreterCheck();
-  int	      read_attrCheck(const NdbColumnImpl* anAttrObject);
-  int	      write_attrCheck(const NdbColumnImpl* anAttrObject);
-  int	      labelCheck();
-  int	      insertCall(Uint32 aCall);
-  int	      insertBranch(Uint32 aBranch);
+  int       incCheck(const NdbColumnImpl* anAttrObject);
+  int       initial_interpreterCheck();
+  int       intermediate_interpreterCheck();
+  int       read_attrCheck(const NdbColumnImpl* anAttrObject);
+  int       write_attrCheck(const NdbColumnImpl* anAttrObject);
+  int       labelCheck();
+  int       insertCall(Uint32 aCall);
+  int       insertBranch(Uint32 aBranch);
 
   Uint32 ptr2int() { return theReceiver.getId(); };
 
   // get table or index key from prepared signals
   int getKeyFromTCREQ(Uint32* data, unsigned size);
 
-/******************************************************************************
- * These are the private variables that are defined in the operation objects.
- *****************************************************************************/
+/***********************************************************************
+ * These are the private variables defined in the operation objects.
+ **********************************************************************/
 
   NdbReceiver theReceiver;
 
-  NdbError theError;			// Errorcode	       
-  int 	   theErrorLine;		// Error line       
+  NdbError theError;            // Error code.
+  int      theErrorLine;        // Error line.
 
-  Ndb*		   theNdb;	      	// Point back to the Ndb object.
-  NdbTransaction*   theNdbCon;	       	// Point back to the connection object.
-  NdbOperation*	   theNext;	       	// Next pointer to operation.
+  Ndb*       theNdb;            // Points back to the Ndb object.
+  NdbTransaction*   theNdbCon;  // Points back to the connection object.
+  NdbOperation*    theNext;     // Next pointer to an operation.
 
   union {
-    NdbApiSignal* theTCREQ;		// The TC[KEY/INDX]REQ signal object
+    NdbApiSignal* theTCREQ;     // The TC[KEY/INDX]REQ signal object.
     NdbApiSignal* theSCAN_TABREQ;
   };
 
-  NdbApiSignal*	   theFirstATTRINFO;	// The first ATTRINFO signal object 
-  NdbApiSignal*	   theCurrentATTRINFO;	// The current ATTRINFO signal object  
-  Uint32	   theTotalCurrAI_Len;	// The total number of attribute info
-  		      			// words currently defined    
-  Uint32	   theAI_LenInCurrAI;	// The number of words defined in the
-		      		     	// current ATTRINFO signal
-  NdbApiSignal*	   theLastKEYINFO;	// The first KEYINFO signal object 
-
-  class NdbLabel*	    theFirstLabel;
-  class NdbLabel*	    theLastLabel;
-  class NdbBranch*	    theFirstBranch;
-  class NdbBranch*	    theLastBranch;
-  class NdbCall*	    theFirstCall;
-  class NdbCall*	    theLastCall;
+  NdbApiSignal*    theFirstATTRINFO;    // The first ATTRINFO signal 
+                                        // object.
+  NdbApiSignal*    theCurrentATTRINFO;  // The current ATTRINFO signal 
+                                        // object.
+  Uint32     theTotalCurrAI_Len;        // The total number of attribute
+                                        // info words currently defined.
+  Uint32     theAI_LenInCurrAI;         // The number of words defined
+                                        // in the current ATTRINFO 
+                                        // signal.
+  NdbApiSignal*    theLastKEYINFO;      // The first KEYINFO signal 
+                                        // object 
+
+  class NdbLabel*     theFirstLabel;
+  class NdbLabel*     theLastLabel;
+  class NdbBranch*      theFirstBranch;
+  class NdbBranch*      theLastBranch;
+  class NdbCall*      theFirstCall;
+  class NdbCall*      theLastCall;
   class NdbSubroutine*    theFirstSubroutine;
   class NdbSubroutine*    theLastSubroutine;
-  Uint32	    theNoOfLabels;
-  Uint32	    theNoOfSubroutines;
+  Uint32      theNoOfLabels;
+  Uint32      theNoOfSubroutines;
 
-  Uint32*           theKEYINFOptr;       // Pointer to where to write KEYINFO
-  Uint32*           theATTRINFOptr;      // Pointer to where to write ATTRINFO
+  Uint32*           theKEYINFOptr;      // Pointer to where to write 
+                                        // KEYINFO
+  Uint32*           theATTRINFOptr;     // Pointer to where to write 
+                                        // ATTRINFO
 
   const class NdbTableImpl* m_currentTable; // The current table
-  const class NdbTableImpl* m_accessTable;  // Index table (== current for pk)
+  const class NdbTableImpl* m_accessTable;  // Index table (same as 
+                                            // current table for primary 
+                                            // key).
 
   // Set to TRUE when a tuple key attribute has been defined. 
-  Uint32	    theTupleKeyDefined[NDB_MAX_NO_OF_ATTRIBUTES_IN_KEY][3];
+  Uint32      theTupleKeyDefined[NDB_MAX_NO_OF_ATTRIBUTES_IN_KEY][3];
 
-  Uint32	    theTotalNrOfKeyWordInSignal;     // The total number of
-  						     // keyword in signal.
+  Uint32      theTotalNrOfKeyWordInSignal;    // The total number of
+                                              // keywords in the signal.
 
-  Uint32	    theTupKeyLen;	// Length of the tuple key in words
-		       		        // left until done
-  Uint8	theNoOfTupKeyLeft;  // The number of tuple key attributes
-  OperationType	theOperationType;        // Read Request, Update Req......   
+  Uint32      theTupKeyLen;       // Remaining length of the tuple key 
+                                  // (in words).
+  Uint8 theNoOfTupKeyLeft;        // The number of tuple key attributes.
+  OperationType theOperationType; // Read request, update request. etc.
   
-  LockMode        theLockMode;	   // Can be set to WRITE if read operation 
-  OperationStatus theStatus;	   // The status of the operation.	
+  LockMode        theLockMode;    // Can be set to WRITE if this is a 
+                                  // read operation.
+  OperationStatus theStatus;      // The status of the operation.  
   
-  Uint32         theMagicNumber;  // Magic number to verify that object 
-                                   // is correct
-  Uint32 theScanInfo;      	   // Scan info bits (take over flag etc)
-  Uint32 theDistributionKey;       // Distribution Key size if used
-
-  Uint32 theSubroutineSize;	   // Size of subroutines for interpretation
-  Uint32 theInitialReadSize;	   // Size of initial reads for interpretation
-  Uint32 theInterpretedSize;	   // Size of interpretation
-  Uint32 theFinalUpdateSize;	   // Size of final updates for interpretation
-  Uint32 theFinalReadSize;	   // Size of final reads for interpretation
-
-  Uint8  theStartIndicator;	 // Indicator of whether start operation
-  Uint8  theCommitIndicator;	 // Indicator of whether commit operation
-  Uint8  theSimpleIndicator;	 // Indicator of whether simple operation
-  Uint8  theDirtyIndicator;	 // Indicator of whether dirty operation
-  Uint8  theInterpretIndicator;  // Indicator of whether interpreted operation
-  Int8  theDistrKeyIndicator_;    // Indicates whether distr. key is used
+  Uint32         theMagicNumber;  // "Magic number" used to verify 
+                                  // whether the object is correct.
+  Uint32 theScanInfo;             // Scan info bits (takeover flag, etc.)
+  Uint32 theDistributionKey;      // Distribution Key size (if used).
+
+  Uint32 theSubroutineSize;       // Size of subroutines for
+                                  // interpretation.
+  Uint32 theInitialReadSize;      // Size of initial reads for
+                                  // interpretation.
+  Uint32 theInterpretedSize;      // Size of interpretation.
+  Uint32 theFinalUpdateSize;      // Size of final updates for 
+                                  // interpretation.
+  Uint32 theFinalReadSize;        // Size of final reads for 
+                                  // interpretation.
+
+  Uint8  theStartIndicator;       // Indicates whether to start the 
+                                  // operation
+  Uint8  theCommitIndicator;      // Indicates whether to commit the 
+                                  // operation
+  Uint8  theSimpleIndicator;      // Indicates whether this is a simple 
+                                  // operation.
+  Uint8  theDirtyIndicator;       // Indicates whether this is a dirty 
+                                  // operation.
+  Uint8  theInterpretIndicator;   // Indicates whether this is an 
+                                  // interpreted operation
+  Int8  theDistrKeyIndicator_;    // Indicates whether the distribution 
+                                  // key is used.
   Uint8  m_no_disk_flag;          
 
   Uint16 m_tcReqGSN;
@@ -967,10 +1003,11 @@
   NdbBlob* theBlobList;
 
   /*
-   * Abort option per operation, used by blobs.  Default -1.  If set,
-   * overrides abort option on connection level.  If set to IgnoreError,
-   * does not cause execute() to return failure.  This is different from
-   * IgnoreError on connection level.
+   * Abort option for each operation, used by blobs. The default is -1. 
+   * If set, this overrides any abort option set on the connection 
+   * level. If set to <code>IgnoreError</code>, then this causes 
+   * execute() not to return failure. Note that this is different from
+   * setting a connection-level <code>IgnoreError</code>.
    */
   Int8 m_abortOption;
 
@@ -1010,12 +1047,12 @@
   return theErrorLine;
 }
 
-/******************************************************************************
+/***********************************************************************
 void next(NdbOperation* aNdbOperation);
 
 Parameters:    aNdbOperation: Pointers to the NdbOperation object.
-Remark:        Set the next variable of the operation object.
-******************************************************************************/
+Remark:        Sets the next variable of the operation object.
+***********************************************************************/
 inline
 void
 NdbOperation::next(NdbOperation* aNdbOperation)
@@ -1023,12 +1060,12 @@
   theNext = aNdbOperation;
 }
 
-/******************************************************************************
+/**********************************************************************
 NdbOperation* next();
 
-Return Value:  	Return  next pointer to NdbOperation object.
-Remark:         Get the next variable of the operation object.
-******************************************************************************/
+Return Value:   Returns the next pointer to the NdbOperation object.
+Remark:         Gets the next variable of the operation object.
+***********************************************************************/
 inline
 NdbOperation*
 NdbOperation::next()
@@ -1050,29 +1087,28 @@
   return theReceiver.theFirstRecAttr;
 }
 
-/******************************************************************************
+/***********************************************************************
 OperationStatus  Status();
 
-Return Value    Return the OperationStatus.	
+Return Value    Returns the OperationStatus. 
 Parameters:     aStatus:  The status.
-Remark:         Sets Operation status. 
-******************************************************************************/
+Remark:         Sets operation status. 
+***********************************************************************/
 inline
-NdbOperation::OperationStatus			
+NdbOperation::OperationStatus     
 NdbOperation::Status()
 {
   return theStatus;
 }
 
-/******************************************************************************
+/***********************************************************************
 void  Status(OperationStatus aStatus);
 
 Parameters:     aStatus: The status.
-Remark:         Sets Operation
- status. 
-******************************************************************************/
+Remark:         Sets the operation status. 
+***********************************************************************/
 inline
-void			
+void      
 NdbOperation::Status( OperationStatus aStatus )
 {
   theStatus = aStatus;
@@ -1082,7 +1118,8 @@
 void NdbCon(NdbTransaction* aNdbCon);
 
 Parameters:    aNdbCon: Pointers to NdbTransaction object.
-Remark:        Set the reference to the connection in the operation object.
+Remark:        Sets the reference to the connection in the operation 
+               object.
 ******************************************************************************/
 inline
 void

--- 1.18/storage/ndb/include/ndbapi/NdbRecAttr.hpp	2005-11-07 21:19:05 +10:00
+++ 1.19/storage/ndb/include/ndbapi/NdbRecAttr.hpp	2006-02-01 00:11:43 +10:00
@@ -26,47 +26,47 @@
  * @class NdbRecAttr
  * @brief Contains value of an attribute.
  *
- * NdbRecAttr objects are used to store the attribute value 
- * after retrieving the value from the NDB Cluster using the method 
- * NdbOperation::getValue.  The objects are allocated by the NDB API.
- * An example application program follows:
+ * NdbRecAttr objects are used to store the attribute value after 
+ * retrieving the value from the NDB Cluster using the 
+ * NdbOperation::getValue() method. The objects are allocated by the NDB 
+ * API. An example application program follows:
  *
  * @code
- *   MyRecAttr = MyOperation->getValue("ATTR2", NULL);
- *   if (MyRecAttr == NULL) goto error;
+ *  MyRecAttr = MyOperation->getValue("ATTR2", NULL);
+ *  
+ *  if(MyRecAttr == NULL)
+ *      goto error;
  *
- *   if (MyTransaction->execute(Commit) == -1) goto error;
+ *  if(MyTransaction->execute(Commit) == -1)
+ *    goto error;
  *
- *   ndbout << MyRecAttr->u_32_value();
+ *  ndbout << MyRecAttr->u_32_value();
  * @endcode
- * For more examples, see 
- * @ref ndbapi_simple.cpp.
+ * For additional examples, see @ref ndbapi_simple.cpp.
  *
  * @note The NdbRecAttr object is instantiated with its value when 
- *       NdbTransaction::execute is called.  Before this, the value is 
- *       undefined.  (NdbRecAttr::isNULL can be used to check 
- *       if the value is defined or not.)
- *       This means that an NdbRecAttr object only has valid information
- *       between the time of calling NdbTransaction::execute and
- *       the time of Ndb::closeTransaction.
- *       The value of the null indicator is -1 until the
- *       NdbTransaction::execute method have been called.
+ *       NdbTransaction::execute() is called. Before this, the value is 
+ *       undefined. (You can use NdbRecAttr::isNULL() to determine
+ *       whether the value is defined.) This means that an NdbRecAttr 
+ *       object has valid information only between the times that 
+ *       NdbTransaction::execute() and Ndb::closeTransaction() are 
+ *       called. The value of the null indicator is -1 until 
+ *       NdbTransaction::execute() has been called.
  *
- * For simple types, there are methods which directly getting the value
+ * For simple types, there are methods for getting the value directly
  * from the NdbRecAttr object.
  *
- * To get a reference to the value, there are two methods:
- * NdbRecAttr::aRef (memory is released by NDB API) and 
- * NdbRecAttr::getAttributeObject (memory must be released 
- * by application program).
- * The two methods may return different pointers.
+ * To obtain a reference to the value, you can use either of two 
+ * methods: NdbRecAttr::aRef() (memory is released automatically by the 
+ * NDB API) and NdbRecAttr::getAttributeObject() (memory must be 
+ * released by the application). The two methods may return different 
+ * pointers.
  *
  * There are also methods to check attribute type, attribute size and
- * array size.  
- * The method NdbRecAttr::arraySize returns the number of elements in the
- * array (where each element is of size given by NdbRecAttr::attrSize). 
- * The NdbRecAttr::arraySize method is needed when reading variable-sized
- * attributes.
+ * array size. The NdbRecAttr::arraySize() method returns the number of 
+ * elements in the array, where the size of each element is given by 
+ * NdbRecAttr::attrSize(). The NdbRecAttr::arraySize() method is needed 
+ * when reading variable-sized attributes.
  *
  * @note Variable-sized attributes are not yet supported.
  */
@@ -83,41 +83,41 @@
 
 public:
   /** 
-   * @name Getting meta information
+   * @name Obtaining meta-information.
    * @{
    */
   const NdbDictionary::Column * getColumn() const;
 
   /**
-   * Get type of column
-   * @return Data type of the column
+   * Gets type of column.
+   * @return Data type of the column.
    */
   NdbDictionary::Column::Type getType() const;
   
   /**
-   * Get attribute (element) size in bytes. 
+   * Gets attribute (element) size in bytes. 
    * 
    */
   Uint32 get_size_in_bytes() const { return m_size_in_bytes; }
 
   /** @} *********************************************************************/
   /** 
-   * @name Getting stored value
+   * @name Obtaining stored values.
    * @{
    */
 
   /** 
-   * Check if attribute value is NULL.
+   * Checks whether the attribute value is <code>NULL</code>.
    *
    * @return -1 = Not defined (Failure or 
-   *              NdbTransaction::execute not yet called).<br>
+   *              NdbTransaction::execute() not yet called).<br>
    *          0 = Attribute value is defined, but not equal to NULL.<br>
    *          1 = Attribute value is defined and equal to NULL.
    */
   int isNULL() const; 
 
   /**
-   * Get value stored in NdbRecAttr object.
+   * Gets value stored in NdbRecAttr object.
    *
    * @return  64 bit long value.
    */
@@ -126,61 +126,61 @@
   /**
    * Get value stored in NdbRecAttr object.
    *
-   * @return  32 bit int value.
+   * @return  32-bit int value.
    */   
   Int32 int32_value() const;  
 
   /**
-   * Get value stored in NdbRecAttr object.
+   * Gets value stored in NdbRecAttr object.
    *
    * @return  Short value.
    */
   short short_value() const;
 
   /**
-   * Get value stored in NdbRecAttr object.
+   * Gets value stored in NdbRecAttr object.
    *
    * @return  Char value.
    */           
   char  char_value() const;           
 
   /**
-   * Get value stored in NdbRecAttr object.
+   * Gets value stored in NdbRecAttr object.
    *
-   * @return  64 bit unsigned value.
+   * @return  64-bit unsigned value.
    */
   Uint64 u_64_value() const;          
 
   /**
-   * Get value stored in NdbRecAttr object.
+   * Gets value stored in NdbRecAttr object.
    *
-   * @return  32 bit unsigned value.
+   * @return  32-bit unsigned value.
    */
   Uint32 u_32_value() const;          
 
   /**
-   * Get value stored in NdbRecAttr object.
+   * Gets value stored in NdbRecAttr object.
    * 
    * @return  Unsigned short value.
    */
   Uint16 u_short_value() const;
 
   /**
-   * Get value stored in NdbRecAttr object.
+   * Gets value stored in NdbRecAttr object.
    *
    * @return  Unsigned char value.
    */   
   Uint8 u_char_value() const;        
 
   /**
-   * Get value stored in NdbRecAttr object.
+   * Gets value stored in NdbRecAttr object.
    *
    * @return  Float value.
    */
   float float_value() const;         
 
   /**
-   * Get value stored in NdbRecAttr object.
+   * Gets value stored in NdbRecAttr object.
    *
    * @return  Double value.
    */
@@ -188,43 +188,43 @@
   
   /** @} *********************************************************************/
   /** 
-   * @name Getting reference to stored value
+   * @name Obtaining reference to stored values.
    * @{
    */
 
   /**
-   * Get reference to attribute value. 
+   * Gets a reference to an attribute value. 
    * 
-   * Returns a char*-pointer to the value.
-   * The pointer is aligned appropriately for the data type.  
-   * The memory is released when Ndb::closeTransaction is executed 
-   * for the transaction which read the value.
+   * This method returns a char*-pointer to the value. The pointer is 
+   * aligned appropriately for the data type. Memory is released when 
+   * Ndb::closeTransaction() is executed for the transaction which read 
+   * the value.
    *
-   * @note The memory is released by NDB API.
+   * @note Memory is released by NDB API.
    * 
    * @note The pointer to the attribute value stored in an NdbRecAttr
-   *       object (i.e. the pointer returned by aRef) is constant.  
+   *       object (the pointer returned by <var>aRef</var>) is constant.  
    *       This means that this method can be called anytime after 
-   *       NdbOperation::getValue has been called.
+   *       NdbOperation::getValue() has been called.
    * 
-   * @return Pointer to attribute value.         
+   * @return Pointer to the attribute value.         
    */
   char* aRef() const;                 
                                 
   /** @} *********************************************************************/
                              
   /**
-   * Make a copy of RecAttr object including all data.
+   * Makes a copy of a RecAttr object including all data.
    *
-   * @note  Copy needs to be deleted by application program.
+   * @note  The copy must be deleted by the application.
    */
   NdbRecAttr * clone() const;
   
   /**
    * Destructor
    *
-   * @note  You should only delete RecAttr-copies, 
-   *        i.e. objects that has been cloned.
+   * @note  You should only delete copies of RecAttr - that is, objects 
+   *        that have been cloned.
    */
   ~NdbRecAttr();    
 
@@ -234,7 +234,7 @@
 #endif
 private:
 
-  Uint32 attrId() const;        /* Get attribute id                     */
+  Uint32 attrId() const;        /* Get attribute ID                     */
   bool setNULL();               /* Set NULL indicator                   */
   void setUNDEFINED();          //
 

--- 1.2/storage/ndb/include/ndbapi/NdbIndexStat.hpp	2005-11-06 22:33:04 +10:00
+++ 1.3/storage/ndb/include/ndbapi/NdbIndexStat.hpp	2006-02-01 00:11:43 +10:00
@@ -12,7 +12,8 @@
 
    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
-   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */
+   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
+*/
 
 #ifndef NdbIndexStat_H
 #define NdbIndexStat_H
@@ -23,67 +24,74 @@
 class NdbIndexImpl;
 class NdbIndexScanOperation;
 
-/*
- * Statistics for an ordered index.
+/**
+ * @class NdbIndexStat
+ * @brief Statistics for an ordered index.
  */
 class NdbIndexStat {
 public:
   NdbIndexStat(const NdbDictionary::Index* index);
   ~NdbIndexStat();
-  /*
-   * Allocate memory for cache.  Argument is minimum number of stat
-   * entries and applies to lower and upper bounds separately.  More
-   * entries may fit (keys have variable size).  If not used, db is
-   * contacted always.
+  /**
+   * Allocates memory for the cache. The argument is the minimum number 
+   * of stat entries and applies to lower and upper bounds separately. 
+   * More entries may fit (keys have variable size). If not specified, 
+   * the database is always contacted.
    */
   int alloc_cache(Uint32 entries);
-  /*
+  /**
    * Flags for records_in_range.
    */
   enum {
-    RR_UseDb = 1,       // contact db
-    RR_NoUpdate = 2     // but do not update cache
+    RR_UseDb = 1,       // Contact the database.
+    RR_NoUpdate = 2     // The same, but do not update the cache.
   };
-  /*
-   * Estimate how many index records need to be scanned.  The scan
-   * operation must be prepared with lock mode LM_CommittedRead and must
-   * have the desired bounds set.  The routine may use local cache or
-   * may contact db by executing the operation.
-   *
-   * If returned count is zero then db was contacted and the count is
-   * exact.  Otherwise the count is approximate.  If cache is used then
-   * caller must provide estimated number of table rows.  It will be
-   * multiplied by a percentage obtained from the cache (result zero is
-   * returned as 1).
+  /**
+   * Estimates how many index records need to be scanned. The scan
+   * operation must be prepared with lock mode 
+   * <var>LM_CommittedRead</var> and must have the desired bounds set. 
+   * The routine may use the local cache or contact the database in the 
+   * course of executing the operation.
+   *
+   * If the returned count is zero then the database was contacted and 
+   * the count is exact. Otherwise the count is approximate. If the 
+   * cache is used then the caller must provide estimated number of 
+   * table rows, which is multiplied by a percentage obtained from the 
+   * cache. 
+   *
+   * @note A result of zero is returned as 1.
    */
   int records_in_range(NdbDictionary::Index* index,
                        NdbIndexScanOperation* op,
                        Uint64 table_rows,
                        Uint64* count,
                        int flags);
-  /*
-   * Get latest error.
+  /**
+   * Gets the most recent error.
    */
   const NdbError& getNdbError() const;
 
 private:
-  /*
-   * There are 2 areas: start keys and end keys.  An area has pointers
-   * at beginning and entries at end.  Pointers are sorted by key.
-   *
-   * A pointer contains entry offset and also entry timestamp.  An entry
-   * contains the key and percentage of rows _not_ satisfying the bound
-   * i.e. less than start key or greater than end key.
-   *
-   * A key is an array of index key bounds.  Each has type (0-4) in
-   * first word followed by data with AttributeHeader.
-   *
-   * Stat update comes as pair of start and end key and associated
-   * percentages.  Stat query takes best match of start and end key from
-   * each area separately.  Rows in range percentage is then computed by
-   * excluding the two i.e. as 100 - (start key pct + end key pct).
+  /**
+   * There are 2 areas: start keys and end keys. An area has pointers
+   * at its beginning and entries at its end. Pointers are sorted by 
+   * key.
+   *
+   * A pointer contains both an entry offset and an entry timestamp. An 
+   * entry contains the key and the percentage of rows <em>not</em> 
+   * satisfying the bound - that is, less than the start key or greater 
+   * than the end key.
+   *
+   * A key is an array of index key bounds. Each has a type (0-4) in the
+   * first word followed by data with an AttributeHeader.
+   *
+   * The stat update comes as pair of start and end keys and associated
+   * percentages. The stat query takes the best match of start and end 
+   * keys from each area separately. The rows-in-range percentage is 
+   * then computed by excluding the two as 
+   * <b>100 - (start key % + end key %)</b>.
    *
-   * TODO use more compact key format
+   * TODO: Use more a more compact key format.
    */
   struct Pointer;
   friend struct Pointer;
Thread
bk commit into 5.1 tree (jon:1.2103)jon31 Jan