List:Commits« Previous MessageNext Message »
From:jon Date:January 31 2006 7:17am
Subject:bk commit into 5.1 tree (jon:1.2099)
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

  storage/ndb/include/ndbapi/Ndb.hpp
    1.47 06/02/01 16:46:24 jon@stripped +805 -830
    NDB API updates

ChangeSet
  1.2099 06/01/31 17:17:40 jon@stripped +1 -0
  NDB API updates

# 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:	ghidora.site
# Root:	/home/jon/bk/mysql-5.1-ndbapi-working

--- 1.46/storage/ndb/include/ndbapi/Ndb.hpp	2005-10-06 18:49:54 +10:00
+++ 1.47/storage/ndb/include/ndbapi/Ndb.hpp	2006-02-01 16:46:24 +10:00
@@ -14,106 +14,115 @@
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */
 
+
 /**
    @mainpage                            NDB API Programmers' Guide
 
-   This guide assumes a basic familiarity with MySQL Cluster concepts found
-   on http://dev.mysql.com/doc/mysql/en/NDBCluster.html .
-   Some of the fundamental ones are also described in section @ref secConcepts.
-
-   The NDB API is a MySQL Cluster application interface 
-   that implements transactions.
-   The NDB API consists of the following fundamental classes:
-   - Ndb_cluster_connection, representing a connection to a cluster, 
-   - Ndb is the main class, representing a connection to a database, 
-   - NdbTransaction represents a transaction, 
+   This guide assumes a basic familiarity with MySQL Cluster concepts as 
+   found on http://dev.mysql.com/doc/refman/5.1/en/ndbcluster.html.
+   Some fundamental concepts are also described in @ref secConcepts.
+
+   The NDB API is a MySQL Cluster application interface that implements 
+   transactions. It consists of the following fundamental classes:
+   - Ndb_cluster_connection represents a connection to a cluster. 
+   - Ndb is the main class, and represents a connection to a database. 
+   - NdbTransaction represents a transaction. 
    - NdbOperation represents an operation using a primary key,
-   - NdbScanOperation represents an operation performing a full table scan.
-   - NdbIndexOperation represents an operation using a unique hash index,
-   - NdbIndexScanOperation represents an operation performing a scan using
-     an ordered index,
-   - NdbRecAttr represents an attribute value
-   - NdbDictionary represents meta information about tables and attributes.
+   - NdbScanOperation represents an operation performing a full table 
+     scan.
+   - NdbIndexOperation represents an operation using a unique hash 
+     index,
+   - NdbIndexScanOperation represents an operation performing a scan 
+     using an ordered index.
+   - NdbRecAttr represents an attribute value.
+   - NdbDictionary represents meta information about tables and 
+     attributes.
      
-   In addition, the NDB API defines a structure NdbError, which contains the 
-   specification for an error.
+   In addition, the NDB API defines an NdbError structure, which 
+   contains the specification for an error.
 
-   It is also possible to receive "events" triggered when data in the database in changed.
-   This is done through the NdbEventOperation class.
+   It is also possible to receive events triggered when data in the 
+   database is changed. This is accomplished through the 
+   NdbEventOperation class.
 
-   There are also some auxiliary classes, which are listed in the class hierarchy.
+   There are also some auxiliary classes, which are listed in the class 
+   hierarchy.
      
    The main structure of an application program is as follows:
-   -# Connect to a cluster using the Ndb_cluster_connection
-      object.
-   -# Initiate a database connection by constructing and initialising one or more Ndb objects.
+   -# Connect to a cluster using the Ndb_cluster_connection object.
+   -# Initiate a database connection by constructing and initialising 
+      one or more Ndb objects.
    -# Define and execute transactions using the NdbTransaction class.
    -# Delete Ndb objects.
-   -# Terminate the connection to the cluster (terminate instance of Ndb_cluster_connection).
+   -# Terminate the connection to the cluster (terminate an instance of 
+      Ndb_cluster_connection).
 
    The procedure for using transactions is as follows:
    -# Start transaction (instantiate an NdbTransaction object)
-   -# Add and define operations associated with the transaction using instances of one or more of the
-      NdbOperation, NdbScanOperation, NdbIndexOperation, and NdbIndexScanOperation classes
+   -# Add and define operations associated with the transaction using 
+      instances of one or more of the NdbOperation, NdbScanOperation, 
+      NdbIndexOperation, and NdbIndexScanOperation classes
    -# Execute transaction (call NdbTransaction::execute())
 
-   The operation can be of two different types, 
-   <var>Commit</var> or <var>NoCommit</var>.
-   If the operation is of type <var>NoCommit</var>, 
-   then the application program executes the operation part of a transaction,
-   but without actually committing the transaction.
-   After executing a <var>NoCommit</var> operation, the program can continue 
-   to add and define more operations to the transaction
-   for later execution.
-
-   If the operation is of type <var>Commit</var>, then the transaction is
-   immediately committed. The transaction <em>must</em> be closed after it has been 
-   commited (event if commit fails), and no further addition or definition of 
-   operations for this transaction is allowed.
+   The operation can be of two different types - <code>Commit</code> or 
+   <code>NoCommit</code>. If the operation is of type <code>NoCommit</code>, 
+   then the application program executes the operation portion of a 
+   transaction, but without actually committing the transaction. After 
+   executing a <code>NoCommit</code> operation, the program can continue 
+   to define additional transaction operations for later execution.
+
+   If the operation is of type <code>Commit</code>, then the transaction 
+   is immediately committed. The transaction <em>must</em> be closed 
+   after it has been commited (even if the commit fails), and no further 
+   operations can be added to or defined for this transaction.
 
    @section secSync                     Synchronous Transactions
   
    Synchronous transactions are defined and executed as follows:
   
-    -# Start (create) the transaction, which is
-       referenced by an NdbTransaction object 
-       (typically created using Ndb::startTransaction()).
-       At this point, the transaction is only being defined,
-       and is not yet sent to the NDB kernel.
-    -# Define operations and add them to the transaction, using one or more of
+    -# Begin (create) the transaction, which is referenced by an 
+       NdbTransaction object typically created using 
+       Ndb::startTransaction(). At this point, the transaction is merely 
+       being defined; it is not yet sent to the NDB kernel.
+    -# Define operations and add them to the transaction, using one or 
+       more of the following:
        - NdbTransaction::getNdbOperation()
        - NdbTransaction::getNdbScanOperation()
        - NdbTransaction::getNdbIndexOperation()
        - NdbTransaction::getNdbIndexScanOperation()
-       along with the appropriate methods of the respective NdbOperation class 
-       (or one possiblt one or more of its subclasses).
-       Note that the transaction has still not yet been sent to the NDB kernel.
-    -# Execute the transaction, using the NdbTransaction::execute() method.
-    -# Close the transaction (call Ndb::closeTransaction()).
+       along with the appropriate methods of the respective NdbOperation 
+       class (or possibly one or more of its subclasses). Note that, at 
+       this point, the transaction has still not yet been sent to the 
+       NDB kernel.
+    -# Execute the transaction, using the NdbTransaction::execute() 
+       method.
+    -# Close the transaction by calling Ndb::closeTransaction().
   
    For an example of this process, see the program listing in 
    @ref ndbapi_simple.cpp.
 
-   To execute several parallel synchronous transactions, one can either 
-   use multiple Ndb objects in several threads, or start multiple 
+   To execute several synchronous transactions in parallel, you can 
+   either use multiple Ndb objects in several threads, or start multiple 
    application programs.  
 
    @section secNdbOperations            Operations
 
-   A NdbTransaction consists of a list of operations, each of which is represented 
-   by an instance of NdbOperation, NdbScanOperation, NdbIndexOperation, or
-   NdbIndexScanOperation.
+   An NdbTransaction consists of a list of operations, each of which is 
+   represented by an instance of NdbOperation, NdbScanOperation, 
+   NdbIndexOperation, or NdbIndexScanOperation.
 
    <h3>Single row operations</h3>
-   After the operation is created using NdbTransaction::getNdbOperation()
-   (or NdbTransaction::getNdbIndexOperation()), it is defined in the following 
-   three steps:
-   -# Define the standard operation type, using NdbOperation::readTuple()
-   -# Specify search conditions, using NdbOperation::equal()
-   -# Specify attribute actions, using NdbOperation::getValue()
+   After the operation is created using 
+   NdbTransaction::getNdbOperation() or 
+   NdbTransaction::getNdbIndexOperation(), it is defined in the 
+   following three steps:
+   -# Specify the standard operation type using 
+      NdbOperation::readTuple().
+   -# Specify search conditions using NdbOperation::equal().
+   -# Specify attribute actions using NdbOperation::getValue().
 
-   Here are two brief examples illustrating this process. For the sake of 
-   brevity, we omit error handling.
+   Here are two brief examples illustrating this process. For the sake 
+   of brevity, we omit error handling.
    
    This first example uses an NdbOperation:
    @code
@@ -154,57 +163,52 @@
    Another example of this second type can be found in 
    @ref ndbapi_simple_index.cpp.
 
-   We will now discuss in somewhat greater detail each step involved in the 
+   We now discuss in somewhat greater detail each step involved in the 
    creation and use of synchronous transactions.
 
    <h4>Step 1: Define single row operation type</h4>
    The following operation types are supported:
-    -# NdbOperation::insertTuple() : 
-       inserts a non-existing tuple
-    -# NdbOperation::writeTuple() : 
-       updates an existing tuple if is exists,
-       otherwise inserts a new tuple
-    -# NdbOperation::updateTuple() : 
-       updates an existing tuple
-    -# NdbOperation::deleteTuple() : 
-       deletes an existing tuple
-    -# NdbOperation::readTuple() : 
-       reads an existing tuple with specified lock mode
-
-   All of these operations operate on the unique tuple key.
-   (When NdbIndexOperation is used then all of these operations 
-   operate on a defined unique hash index.)
-
-   @note If you want to define multiple operations within the same transaction,
-         then you need to call NdbTransaction::getNdbOperation() or
-	 NdbTransaction::getNdbIndexOperation() for each operation.
+    -# NdbOperation::insertTuple(): Inserts a non-existing tuple.
+    -# NdbOperation::writeTuple(): Updates a tuple if one exists, 
+       otherwise inserts a new tuple.
+    -# NdbOperation::updateTuple(): Updates an existing tuple.
+    -# NdbOperation::deleteTuple(): Deletes an existing tuple.
+    -# NdbOperation::readTuple(): Reads an existing tuple using the 
+       specified lock mode.
+
+   All of these operations operate on the unique tuple key. When 
+   NdbIndexOperation is used, then each of these operations operates on 
+   a defined unique hash index.
+
+   @note If you want to define multiple operations within the same 
+         transaction, then you need to call 
+         NdbTransaction::getNdbOperation() or
+         NdbTransaction::getNdbIndexOperation() for each operation.
 
    <h4>Step 2: Specify Search Conditions</h4>
-   The search condition is used to select tuples. Search conditions are set using NdbOperation::equal().
+   The search condition is used to select tuples. Search conditions are 
+   set using NdbOperation::equal().
 
    <h4>Step 3: Specify Attribute Actions</h4>
-   Next, it is necessary to determine which attributes should be read or updated.
-   It is important to remember that: 
-   - Deletes can neither read nor set values, but only delete them
-   - Reads can only read values
-   - Updates can only set values
-   Normally the attribute is identified by name, but it is
-   also possible to use the attribute's identity to determine the
-   attribute.
-
-   NdbOperation::getValue() returns an NdbRecAttr object
-   containing the read value.
-   To obtain the actual value, one of two methods can be used;
-   the application can either
+   Next, it is necessary to determine which attributes should be read or 
+   updated. It is important to remember that: 
+   - Deletes can neither read nor set values, but only delete them.
+   - Reads can only read values.
+   - Updates can only set values.
+   Normally the attribute is identified by name, but it is also possible 
+   to use the attribute's identity to determine the attribute.
+
+   NdbOperation::getValue() returns an NdbRecAttr object containing the 
+   value as read. To obtain the actual value, one of two methods can be 
+   used; the application can either
    - use its own memory (passed through a pointer aValue) to
      NdbOperation::getValue(), or
    - receive the attribute value in an NdbRecAttr object allocated
      by the NDB API.
 
    The NdbRecAttr object is released when Ndb::closeTransaction()
-   is called.
-   Thus, the application cannot reference this object following
-   any subsequent call to Ndb::closeTransaction().
+   is called. For this reason, the application cannot reference this 
+   object following any subsequent call to Ndb::closeTransaction().
    Attempting to read data from an NdbRecAttr object before
    calling NdbTransaction::execute() yields an undefined result.
 
@@ -212,31 +216,34 @@
    @subsection secScan              Scan Operations 
    
    Scans are roughly the equivalent of SQL cursors, providing a means to
-   preform high-speed row processing. A scan can be performed 
-   on either a table (using @ref NdbScanOperation) or 
-   an ordered index (by means of an @ref NdbIndexScanOperation).
+   perform high-speed row processing. A scan can be performed on either 
+   a table (using an @ref NdbScanOperation) or an ordered index (by 
+   means of an @ref NdbIndexScanOperation).
 
    Scan operations are characterised by the following:
-   - They can perform only reads (shared, exclusive or dirty)
-   - They can potentially work with multiple rows
-   - They can be used to update or delete multiple rows
-   - They can operate on several nodes in parallel
-
-   After the operation is created using NdbTransaction::getNdbScanOperation()
-   (or NdbTransaction::getNdbIndexScanOperation()), 
-   it is carried out in the following three steps:
-   -# Define the standard operation type, using NdbScanOperation::readTuples()
-   -# Specify search conditions, using @ref NdbScanFilter and/or 
-      @ref NdbIndexScanOperation::setBound()
-   -# Specify attribute actions, using NdbOperation::getValue()
-   -# Executing the transaction, using NdbTransaction::execute()
-   -# Traversing the result set by means of succssive calls to 
-      NdbScanOperation::nextResult()
-
-   Here are two brief examples illustrating this process. Once again, in order
-   to keep things relatively short and simple, we will forego any error handling.
+   - They can perform only reads. These may shared, exclusive or dirty.
+   - They can potentially work with multiple rows.
+   - They can be used to update or delete multiple rows.
+   - They can operate on several nodes in parallel.
+
+   After the operation is created using 
+   NdbTransaction::getNdbScanOperation() or 
+   NdbTransaction::getNdbIndexScanOperation(), it is carried out as 
+   follows:
+   -# Define the standard operation type, using 
+      NdbScanOperation::readTuples()
+   -# Specify search conditions, using @ref NdbScanFilter, 
+      @ref NdbIndexScanOperation::setBound(), or both.
+   -# Specify attribute actions using NdbOperation::getValue().
+   -# Execute the transaction using NdbTransaction::execute().
+   -# Traverse the result set by means of succssive calls to 
+      NdbScanOperation::nextResult().
+
+   Here are two brief examples illustrating this process. Once again, 
+   in order to keep things relatively short and simple, we forego any 
+   error handling.
    
-   This first example performs a table scan, using an NdbScanOperation:
+   This first example performs a table scan using an NdbScanOperation:
    @code
      // 1. Retrieve table object
      myTable= myDict->getTable("MYTABLENAME");
@@ -258,7 +265,8 @@
      myRecAttr= myOperation->getValue("ATTR2", NULL);
    @endcode
 
-   Our second example uses an NdbIndexScanOperation to perform an index scan:
+   The second example uses an NdbIndexScanOperation to perform an index 
+   scan:
    @code
      // 1. Retrieve index object
      myIndex= myDict->getIndex("MYORDEREDINDEX", "MYTABLENAME");
@@ -278,88 +286,99 @@
      myRecAttr = MyOperation->getValue("ATTR2", NULL);
    @endcode
 
-   Some additional discussion of each step required to perform a scan follows:
+   Some additional discussion of each step required to perform a scan 
+   follows:
 
    <h4>Step 1: Define Scan Operation Type</h4>
-   It is important to remember that only a single operation is supported for each scan operation 
-   (@ref NdbScanOperation::readTuples() or @ref NdbIndexScanOperation::readTuples()).
+   It is important to remember that only a single operation is supported 
+   for each scan operation (@ref NdbScanOperation::readTuples() or 
+   @ref NdbIndexScanOperation::readTuples()).
 
    @note If you want to define multiple scan operations within the same 
          transaction, then you need to call 
-	 NdbTransaction::getNdbScanOperation() or 
-	 NdbTransaction::getNdbIndexScanOperation() separately for <b>each</b> operation.
+         NdbTransaction::getNdbScanOperation() or 
+         NdbTransaction::getNdbIndexScanOperation() separately for 
+         <b>each</b> operation.
 
    <h4>Step 2: Specify Search Conditions</h4>
-   The search condition is used to select tuples.
-   If no search condition is specified, the scan will return all rows
-   in the table.
-
-   The search condition can be an @ref NdbScanFilter (which can be used on both
-   @ref NdbScanOperation and @ref NdbIndexScanOperation) or bounds which
-   can only be used on index scans (@ref NdbIndexScanOperation::setBound()).
-   An index scan can use both NdbScanFilter and bounds.
+   The search condition is used to select tuples. If no search condition 
+   is specified, the scan will return all rows in the table.
 
-   @note When NdbScanFilter is used, each row is examined, whether or not it is
-   actually returned. However, when using bounds, only rows within the bounds will be examined.
+   The search condition can be an @ref NdbScanFilter (which can be used 
+   on both @ref NdbScanOperation and @ref NdbIndexScanOperation) or 
+   bounds (which can be used only on index scans - see 
+   @ref NdbIndexScanOperation::setBound()). An index scan can use both 
+   NdbScanFilter and bounds.
+
+   @note When NdbScanFilter is used, each row is examined, whether or 
+         not it is actually returned. However, when using bounds, only 
+         rows within the bounds will be examined.
 
    <h4>Step 3: Specify Attribute Actions</h4>
-
    Next, it is necessary to define which attributes should be read.
-   As with transaction attributes, scan attributes are defined by name but it is
-   also possible to use the attributes' identities to define attributes.
-
-   As previously discussed (see @ref secSync), the value read is returned as 
-   an NdbRecAttr object by the NdbOperation::getValue() method.
-
-   <h3>Using Scan to Update/Delete</h3>
-   Scanning can also be used to update or delete rows.
-   This is performed by
-   -# Scanning using exclusive locks (using NdbOperation::LM_Exclusive)
-   -# When iterating through the result set, for each row optionally calling 
-      either NdbScanOperation::updateCurrentTuple() or 
+   As with transaction attributes, scan attributes are defined by name, 
+   but it is also possible to use the attributes' identities to define 
+   attributes.
+
+   As discussed elsewhere in this document (see @ref secSync), the value 
+   read is returned by the NdbOperation::getValue() method as an 
+   NdbRecAttr object.
+
+   <h3>Using Scan to Update or Delete Rows</h3>
+   Scanning can also be used to update or delete rows. This is performed 
+   by
+   -# Scanning using exclusive locks using NdbOperation::LM_Exclusive
+   -# (When iterating through the result set:) For each row optionally 
+      calling either NdbScanOperation::updateCurrentTuple() or 
       NdbScanOperation::deleteCurrentTuple()
-   -# (If performing NdbScanOperation::updateCurrentTuple():) 
-      Setting new values for records simply by using @ref NdbOperation::setValue().
-      NdbOperation::equal() should <em>not</em> be called in such cases, as the primary 
-      key is retrieved from the scan.
-
-   @note The actual update or delete will not be performed until the next 
-   call to NdbTransaction::execute(), just as with single row operations. 
-   NdbTransaction::execute() also must be called before any locks are released;
-   see @ref secScanLocks for more information.
-
-   <h4>Features Specific to Index Scans</h4> 
-   
-   When performing an index scan, it is possible to 
-   scan only a subset of a table using @ref NdbIndexScanOperation::setBound().
-   In addition, result sets can be sorted in either ascending or descending order, using
-   @ref NdbIndexScanOperation::readTuples(). Note that rows are returned unordered 
-   by default, that is, unless <var>sorted</var> is set to <b>true</b>.
-   It is also important to note that, when using NdbIndexScanOperation::BoundEQ 
-   on a partition key, only fragments containing rows will actually be scanned.
+   -# (If performing NdbScanOperation::updateCurrentTuple():) Setting 
+      new values for records simply by using 
+      @ref NdbOperation::setValue(). NdbOperation::equal() should 
+      <em>not</em> be called in such cases, as the primary key is 
+      retrieved from the scan.
+
+   @note The update or delete is not actually performed until the 
+         next call to NdbTransaction::execute() is made, just as with 
+         single row operations. NdbTransaction::execute() also must be 
+         called before any locks are released; see @ref secScanLocks for 
+         more information.
+
+   <h4>Features Specific to Index Scans</h4>
+
+   When performing an index scan, it is possible to scan only a subset 
+   of a table using @ref NdbIndexScanOperation::setBound(). In addition, 
+   result sets can be sorted in either ascending or descending order, 
+   using @ref NdbIndexScanOperation::readTuples(). Note that rows are 
+   returned unordered by default unless <var>sorted</var> is set to 
+   <b>true</b>. It is also important to note that, when using 
+   NdbIndexScanOperation::BoundEQ on a partition key, only fragments 
+   containing rows will actually be scanned.
    
    @note When performing a sorted scan, any value passed as the 
-   NdbIndexScanOperation::readTuples() method's <code>parallel</code> argument 
-   will be ignored and maximum parallelism will be used instead. In other words, all 
-   fragments which it is possible to scan will be scanned simultaneously and in parallel 
-   in such cases.
+         NdbIndexScanOperation::readTuples() method's 
+         <var>parallel</var> argument will be ignored and maximum 
+         parallelism will be used instead. In other words, all fragments 
+         which it is possible to scan are scanned simultaneously and in 
+         parallel in such cases.
 
    @subsection secScanLocks Lock handling with scans
 
-   Performing scans on either a tables or an index has the potential 
-   return a great many records; however, Ndb will lock only a predetermined 
-   number of rows per fragment at a time.
-   How many rows will be locked per fragment is controlled by the 
-   <var>batch</var> parameter passed to NdbScanOperation::readTuples().
+   Performing scans on either a table or an index has the potential to
+   return a great many records; however, Ndb locks only a predetermined 
+   number of rows per fragment at a time. The number of rows locked per 
+   fragment is controlled by the <var>batch</var> parameter passed to 
+   NdbScanOperation::readTuples().
 
    In order to allow the application to handle how locks are released, 
-   NdbScanOperation::nextResult() has a Boolean parameter <var>fetch_allow</var>.
-   If NdbScanOperation::nextResult() is called with <var>fetch_allow</var> equal to 
-   <b>false</b>, then no locks may be released as result of the function call. 
-   Otherwise the locks for the current batch may be released.
+   NdbScanOperation::nextResult() has a Boolean parameter 
+   <var>fetch_allow</var>. If NdbScanOperation::nextResult() is called 
+   with <var>fetch_allow</var> equal to <b>false</b>, then no locks may 
+   be released as result of the function call. Otherwise the locks for 
+   the current batch may be released.
 
-   This next example shows a scan delete that handle locks in an efficient manner.
-   For the sake of brevity, we omit error-handling.
+   This next example shows a scan delete that handle locks in an 
+   efficient manner. For the sake of brevity, we omit error-handling.
+   
    @code
      int check;
 
@@ -381,20 +400,20 @@
 
    @section secError                    Error Handling
 
-   Errors can occur either when operations making up a transaction are being 
-   defined, or when the transaction is actually being executed. Catching and 
-   handling either sort of error requires testing the value returned by 
-   NdbTransaction::execute(), and then, if an error is indicated (that is, 
-   if this value is equal to -1), using the following two methods in order to 
-   identify the error's type and location:
-
+   Errors can occur either when operations making up a transaction are 
+   being defined, or when the transaction is actually being executed. 
+   Catching and handling either sort of error requires testing the value 
+   returned by NdbTransaction::execute(), and then, if an error is 
+   indicated (that is, if this value is equal to -1), using the 
+   following two methods in order to identify the error's type and 
+   location:
    - NdbTransaction::getNdbErrorOperation() returns a reference to the 
      operation causing the most recent error.
    - NdbTransaction::getNdbErrorLine() yields the method number of the 
      erroneous method in the operation.
    
-   This short example illustrates how to detect an error and to use these 
-   two methods to identify it:
+   This short example illustrates how to detect an error and to use 
+   these two methods to identify it:
 
    @code
      theTransaction = theNdb->startTransaction();
@@ -412,33 +431,36 @@
      }
    @endcode
 
-   Here <code>errorLine</code> will be 3, as the error occurred in the 
-   third method called on the NdbOperation object (in this case, 
-   <code>theOperation</code>); if the result of 
-   NdbTransaction::getNdbErrorLine() is 0, this means that the error 
-   occurred when the operations were executed. In this example, 
-   <code>errorOperation</code> will be a pointer to the <code>theOperation</code> 
+   Here <var>errorLine</var> is 3, as the error occurred in the third 
+   method called on the NdbOperation object (in this case, 
+   <var>theOperation</var>). If the result of 
+   NdbTransaction::getNdbErrorLine() is 0, then the error occurred when 
+   the operations were executed. In this example, 
+   <var>errorOperation</var> is a pointer to the <var>theOperation</var> 
    object. The NdbTransaction::getNdbError() method returns an NdbError 
    object providing information about the error.
 
-   @note Transactions are <b>not</b> automatically closed when an error occurs. Call
-   Ndb::closeTransaction() to close the transaction.
+   @note Transactions are <b>not</b> automatically closed when an error 
+         occurs. You must call Ndb::closeTransaction() to close the 
+         transaction.
 
    One recommended way to handle a transaction failure 
-   (i.e. an error is reported) is to:
-   -# Rollback transaction (call NdbTransaction::execute() with a special parameter)
-   -# Close transaction (call NdbTransaction::closeTransaction())
-   -# If the error was temporary, attempt to restart the transaction
+   (that is, when an error is reported) is as shown here:
+   -# Roll back the transaction by calling NdbTransaction::execute() 
+      with a special parameter.
+   -# Close the transaction by calling 
+      NdbTransaction::closeTransaction().
+   -# If the error was temporary, attempt to restart the transaction.
 
    Several errors can occur when a transaction contains multiple 
-   operations which are simultaneously executed.
-   In this case the application has to go through all operations
-   and query their NdbError objects to find out what really happened.
-
-   It is also important to note that errors can occur even when a commit is 
-   reported as successful. In order to handle such situations, the NDB API 
-   provides an additional NdbTransaction::commitStatus() method to check the 
-   transactions's commit status.
+   operations which are simultaneously executed. In this case the 
+   application must go through all operations and query each of their 
+   NdbError objects to find out what really happened.
+
+   It is also important to note that errors can occur even when a commit 
+   is reported as successful. In order to handle such situations, the 
+   NDB API provides an additional NdbTransaction::commitStatus() method 
+   to check the transactions's commit status.
 
 ******************************************************************************/
 
@@ -482,142 +504,137 @@
 /**
    @page secAdapt  Adaptive Send Algorithm
 
-   At the time of "sending" a transaction 
-   (using NdbTransaction::execute()), the transactions 
-   are in reality <em>not</em> immediately transfered to the NDB Kernel.  
-   Instead, the "sent" transactions are only kept in a 
-   special send list (buffer) in the Ndb object to which they belong.
-   The adaptive send algorithm decides when transactions should
-   actually be transferred to the NDB kernel.
-  
-   The NDB API is designed as a multi-threaded interface and so
-   it is often desirable to transfer database operations from more than 
-   one thread at a time. 
-   The NDB API keeps track of which Ndb objects are active in transferring
-   information to the NDB kernel and the expected amount of threads to 
-   interact with the NDB kernel.
-   Note that a given instance of Ndb should be used in at most one thread; 
-   different threads should <em>not</em> use the same Ndb object.
+   At the time a transaction is sent using NdbTransaction::execute(), 
+   the transaction is in reality <em>not</em> immediately transfered to 
+   the NDB Kernel. Instead, the transaction is kept in a special send 
+   list (buffer) in the Ndb object to which they belong. The adaptive 
+   send algorithm decides when transactions should actually be 
+   transferred to the NDB kernel.
+  
+   The NDB API is designed as a multi-threaded interface, and so it is 
+   often desirable to transfer database operations from more than one 
+   thread at a time. The NDB API keeps track of which Ndb objects are 
+   active in transferring information to the NDB kernel and the expected 
+   number of threads to interact with the NDB kernel. Note that a given 
+   instance of Ndb should be used in at most one thread; different 
+   threads should <em>not</em> share the same Ndb object.
   
    There are four conditions leading to the transfer of database 
    operations from Ndb object buffers to the NDB kernel:
    -# The NDB Transporter (TCP/IP, OSE, SCI or shared memory)
-      decides that a buffer is full and sends it off. 
-      The buffer size is implementation-dependent and
-      may change between MySQL Cluster releases.
-      On TCP/IP the buffer size is usually around 64 KB;
-      on OSE/Delta it is usually less than 2000 bytes. 
-      Since each Ndb object provides a single buffer per storage node, 
-      the notion of a "full" buffer is local to this storage node.
+      decides that a buffer is full and sends it off. The buffer size is 
+      implementation-dependent and may change between MySQL Cluster 
+      releases. When TCP/IP is the transporter, the buffer size is 
+      usually around 64 KB; when using OSE/Delta it is usually less than 
+      2000 bytes. Since each Ndb object provides a single buffer per 
+      storage node, the notion of a "full" buffer is local to each 
+      storage node.
    -# The accumulation of statistical data on transferred information
       may force sending of buffers to all storage nodes.
    -# Every 10 ms, a special transmission thread checks whether or not
       any send activity has occurred. If not, then the thread will 
-      force transmission to all nodes. 
-      This means that 20 ms is the maximum time database operations 
-      are kept waiting before being sent off. The 10-millisecond limit 
-      is likely to become a configuration parameter in
-      future releases of MySQL Cluster; however, for checks that
-      are more frequent than each 10 ms, 
-      additional support from the operating system is required.
+      force transmission to all nodes. This means that 20 ms is the 
+      maximum amount of time that database operations are kept waiting 
+      before being dispatched. A 10-millisecond limit is likely in 
+      future releases of MySQL Cluster; checks more frequent than this 
+      require additional support from the operating system.
    -# For methods that are affected by the adaptive send alorithm
       (such as NdbTransaction::execute()), there is a <var>force</var> 
-      parameter 
-      that overrides its default behaviour in this regard and forces 
-      immediate transmission to all nodes. See the inidvidual NDB API class 
-      listings for more information.
+      parameter that overrides its default behaviour in this regard and 
+      forces immediate transmission to all nodes. See the inidvidual 
+      NDB API class listings for more information.
 
-   @note The conditions listed above are subject to change in future releases 
-   of MySQL Cluster.
+   @note The conditions listed above are subject to change in future 
+         releases of MySQL Cluster.
 */
 
 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
 /**
 
-   For each of these "sent" transactions, there are three 
+   For each transaction that is sent in this manner, there are three 
    possible states:
-   -# Waiting to be transferred to NDB Kernel.
-   -# Has been transferred to the NDB Kernel and is currently 
-      being processed.
-   -# Has been transferred to the NDB Kernel and has 
-      finished processing.
-      Now it is waiting for a call to a poll method.  
-      (When the poll method is invoked, 
-      then the transaction callback method will be executed.)
+   -# Waiting for transfer to the NDB Kernel.
+   -# Undergoing post-transfer processing.
+   -# Has been transferred to the NDB Kernel, has finished processing,
+      and is waiting for a call to a poll method. (When the poll method 
+      is invoked, then the transaction callback method will be 
+      executed.)
       
    The poll method invoked (either Ndb::pollNdb() or Ndb::sendPollNdb())
    will return when:
-   -# at least 'minNoOfEventsToWakeup' of the transactions
-      in the send list have transitioned to state 3 as described above, and 
-   -# all of these transactions have executed their callback methods.
+   -# At least <var>minNoOfEventsToWakeup</var> of the transactions in 
+      the send list have made the transition to state 3 as described 
+      above, and 
+   -# All of these transactions have executed their callback methods.
 */
 #endif
 
 /**
    @page secConcepts  MySQL Cluster Concepts
 
-   The <em>NDB Kernel</em> is the collection of storage nodes
-   belonging to a MySQL Cluster.
-   The application programmer can for most purposes view the
-   set of all storage nodes as a single entity.
-   Each storage node is made up of three main components:
-   - TC : The transaction co-ordinator
-   - ACC : Index storage component
-   - TUP : Data storage component
-
-   When an application program executes a transaction,
-   it connects to one transaction co-ordinator on one storage node.  
-   Usually, the programmer does not need to specify which TC should be used, 
-   but in some cases when performance is important, the programmer can
-   provide "hints" to use a certain TC.  
-   (If the node with the desired transaction co-ordinator is down, then another TC will 
-   automatically take over the work.)
-
-   Every storage node has an ACC and a TUP which store 
-   the indexes and data portions of the database table fragment.
-   Even though one TC is responsible for the transaction,
-   several ACCs and TUPs on other storage nodes might be involved in the 
-   execution of the transaction.
-
-
-   @section secNdbKernelConnection   Selecting a Transaction Co-ordinator 
-
-   The default method is to select the transaction co-ordinator (TC) determined to be
-   the "closest" storage node, using a heuristic for proximity based on
-   the type of transporter connection. In order of closest to most distant, these are
+   The <em>NDB Kernel</em> is the collection of storage nodes belonging 
+   to a MySQL Cluster. The application programmer can for most purposes 
+   view the set of all storage nodes as a single entity. Each storage 
+   node is made up of three main components:
+   - TC : The transaction co-ordinator.
+   - ACC : The index storage component.
+   - TUP : The data storage component.
+
+   When an application executes a transaction, it connects to one 
+   transaction co-ordinator on one storage node. Usually, the programmer 
+   does not need to specify which TC should be used, but in some cases 
+   where performance is important, the programmer can provide "hints" to 
+   use a certain TC. (If the node with the desired transaction 
+   co-ordinator is down, then another TC will automatically take its 
+   place.)
+
+   Each storage node has an ACC and a TUP which store the indexes and 
+   data portions of the database table fragment. Even though a single TC 
+   is responsible for the transaction, several ACCs and TUPs on other 
+   storage nodes might be involved in that transaction's execution.
+
+
+   @section secNdbKernelConnection   Selecting a Transaction Co-Ordinator 
+
+   The default method is to select the transaction co-ordinator (TC) 
+   determined to be the "nearest" storage node, using a heuristic for 
+   proximity based on the type of transporter connection. In order of 
+   nearest to most distant, these are:
    - SCI 
    - SHM
    - TCP/IP (localhost)
    - TCP/IP (remote host)
-   If there are several connections available with the same proximity, they will each be 
-   selected in a round robin fashion for every transaction. Optionally
-   one may set the method for TC selection to round-robin mode, where each new set of 
-   transactions is placed on the next DB node. The pool of connections from which this
-   selection is made consists of all available connections.
+   If there are several connections available with the same proximity, 
+   one is selected for each transaction in a round-robin fashion. 
+   Optionally, you may set the method for TC selection to round-robin 
+   mode, where each new set of transactions is placed on the next data 
+   node. The pool of connections from which this selection is made 
+   consists of all available connections.
    
-   As noted previously, the application programmer can provide hints to the NDB API as to 
-   which transaction co-ordinator it should use. This is done by
-   providing a <em>table</em> and <em>partition key</em> 
-   (usually the primary key).
-   By using the primary key as the partition key, 
-   the transaction will be placed on the node where the primary replica
-   of that record resides.
-   Note that this is only a hint; the system can be 
-   reconfigured at any time, in which case the NDB API will choose a transaction
-   co-ordinator without using the hint.
-   For more information, see NdbDictionary::Column::getPartitionKey() and
-   Ndb::startTransaction(). The application programmer can specify
-   the partition key from SQL by using the construct, 
-   <code>CREATE TABLE ... ENGINE=NDB PARTITION BY KEY (<var>attribute-list</var>);</code>.
+   As noted in @ref secConcepts, the application programmer can provide hints to 
+   the NDB API as to which transaction co-ordinator should be uses. This 
+   is done by providing a <em>table</em> and a <em>partition key</em> 
+   (usually the primary key). If the primary key as the partition key, 
+   then the transaction is placed on the node where the primary replica
+   of that record resides. Note that this is only a hint; the system can 
+   be reconfigured at any time, in which case the NDB API chooses a 
+   transaction co-ordinator without using the hint. For more information, 
+   see NdbDictionary::Column::getPartitionKey() and
+   Ndb::startTransaction(). The application programmer can specify the 
+   partition key from SQL by using the construct, 
+   
+   <code>CREATE TABLE ... ENGINE=NDB PARTITION BY KEY (<var>attribute_list</var>);</code>.
 
 
    @section secRecordStruct          NDB Record Structure 
-   The NDB Cluster engine used by MySQL Cluster is a relational database engine
-   storing records in tables just as with any other RDBMS.
-   Table rows represent records as tuples of relational data.
-   When a new table is created, its attribute schema is specified for the table as a whole,
-   and thus each record of the table has the same structure. Again, this is typical
-   of relational databases, and NDB is no different in this regard.
+   
+   The NDB Cluster storage engine used by MySQL Cluster is a relational 
+   database engine storing records in tables just as with any other 
+   database system. Table rows represent records as tuples of relational 
+   data. When a new table is created, its attribute schema is specified 
+   for the table as a whole, and thus each table row has the same 
+   structure. Again, this is typical of relational databases, and NDB is 
+   no different in this regard.
    
 
    @subsection secKeys               Primary Keys
@@ -626,183 +643,163 @@
    
    @section secTrans                 Transactions
 
-   Transactions are committed first to main memory, 
-   and then to disk after a global checkpoint (GCP) is issued.
-   Since all data is (in most NDB Cluster configurations) 
-   synchronously replicated and stored on multiple NDB nodes,
-   the system can still handle processor failures without loss 
-   of data.
-   However, in the case of a system failure (e.g. the whole system goes down), 
-   then all (committed or not) transactions occurring since the latest GCP are lost.
+   Transactions are committed first to main memory, and then to disk 
+   after a global checkpoint (GCP) is issued. Since all data are (in most 
+   NDB Cluster configurations) synchronously replicated and stored on 
+   multiple data nodes, the system can handle processor failures without 
+   loss of data. However, in the case of a system-wide failure, all 
+   transactions (committed or not) occurring since the most recent GCP 
+   are lost.
 
 
    @subsection secConcur                Concurrency Control
-   NDB Cluster uses pessimistic concurrency control based on locking.
-   If a requested lock (implicit and depending on database operation)
-   cannot be attained within a specified time, 
-   then a timeout error occurs.
-
-   Concurrent transactions as requested by parallel application programs and 
-   thread-based applications can sometimes deadlock when they try to access 
-   the same information simultaneously.
-   Thus, applications need to be written in a manner so that timeout errors
-   occurring due to such deadlocks are handled gracefully. This generally
-   means that the transaction encountering a timeout should be rolled back 
-   and restarted.
+
+   NDB Cluster uses <em>pessimistic concurrency control</em> based on 
+   locking. If a requested lock (implicit and depending on database 
+   operation) cannot be attained within a specified time, then a timeout 
+   error results.
+
+   Concurrent transactions as requested by parallel application programs 
+   and thread-based applications can sometimes deadlock when they try to 
+   access the same information simultaneously. Thus, applications need 
+   to be written in a manner such that timeout errors occurring due to 
+   such deadlocks are handled gracefully. This generally means that the 
+   transaction encountering a timeout should be rolled back and 
+   restarted.
 
 
    @section secHint                 Hints and Performance
 
-   Placing the transaction co-ordinator in close proximity
-   to the actual data used in the transaction can in many cases
-   improve performance significantly. This is particularly true for
-   systems using TCP/IP. For example, a Solaris system using a single 500 MHz processor
-   has a cost model for TCP/IP communication which can be represented by the formula
+   Placing the transaction co-ordinator in close proximity to the actual 
+   data used in the transaction can in many cases improve performance 
+   significantly. This is particularly true for systems using TCP/IP. 
+   For example, a Solaris system using a single 500 MHz processor has a 
+   cost model for TCP/IP communication which can be represented by the 
+   formula
 
      <code>[30 microseconds] + ([100 nanoseconds] * [<var>number of bytes</var>])</code>
 
-   This means that if we can ensure that we use "popular" links we increase
-   buffering and thus drastically reduce the communication cost.
-   The same system using SCI has a different cost model:
+   This means that if we can ensure that we use "popular" links we 
+   increase buffering and thus drastically reduce the costs of 
+   communication. The same system using SCI has a different cost model:
 
      <code>[5 microseconds] + ([10 nanoseconds] * [<var>number of bytes</var>])</code>
 
-   Thus, the efficiency of an SCI system is much less dependent on selection of 
-   transaction co-ordinators. 
-   Typically, TCP/IP systems spend 30-60% of their working time on communication,
-   whereas for SCI systems this figure is closer to 5-10%. 
-   Thus, employing SCI for data transport means that less care from the NDB API 
-   programmer is required and greater scalability can be achieved, even for 
-   applications using data from many different parts of the database.
-
-   A simple example is an application that uses many simple updates where
-   a transaction needs to update one record. 
-   This record has a 32 bit primary key, 
-   which is also the partition key. 
-   Then the keyData will be the address of the integer 
-   of the primary key and keyLen will be 4.
+   This means that the efficiency of an SCI system is much less 
+   dependent on selection of transaction co-ordinators. Typically, 
+   TCP/IP systems spend 30-60% of their working time on communication, 
+   whereas for SCI systems this figure is closer to 5-10%. Thus, 
+   employing SCI for data transport means that less effort from the NDB 
+   API programmer is required and greater scalability can be achieved, 
+   even for applications using data from many different parts of the 
+   database.
+
+   A simple example would be an application that uses many simple 
+   updates where a transaction needs to update one record. This record 
+   has a 32-bit primary key which also serves as the partitioning key. Then the 
+   <var>keyData</var> is used as the address of the integer of the primary 
+   key and <var>keyLen</var> is 4.
 */
 
 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
 /**
-   (A transaction's execution can also be divided into three 
-   steps: prepare, send, and poll. This allows us to perform asynchronous
-   transactions.  More about this later.)
-*/
-#endif
-#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
-/**
+   (A transaction's execution can also be divided into three steps: 
+   prepare, send, and poll. This allows us to perform asynchronous 
+   transactions, which are discussed later in this document.)
+   
    Another way to execute several parallel transactions is to use
    asynchronous transactions.
-*/
-#endif  
-#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
-/**
+   
    Operations are of two different kinds:
-   -# standard operations, and
-   -# interpreted program operations.
-*/
-#endif
-#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
-/**
+   -# Standard operations, and
+   -# Interpreted program operations.
+   
    <h3>Interpreted Program Operations</h3>
    The following types of interpreted program operations exist:
-    -# NdbOperation::interpretedUpdateTuple :
-       updates a tuple using an interpreted program
-    -# NdbOperation::interpretedDeleteTuple :
-       delete a tuple using an interpreted program
+    -# NdbOperation::interpretedUpdateTuple(): Updates a tuple using an 
+       interpreted program
+    -# NdbOperation::interpretedDeleteTuple(): Deletes a tuple using an 
+       interpreted program
 
    The operations interpretedUpdateTuple and interpretedDeleteTuple both
    work using the unique tuple key.
 
-   These <em>interpreted programs</em> 
-   make it possible to perform computations
-   inside the NDB Cluster Kernel instead of in the application
-   program.
-   This is sometimes very effective, since no intermediate results
-   are sent to the application, only the final result.
+   These <em>interpreted programs</em> make it possible to perform 
+   computations within the NDB Cluster Kernel, rather than in the 
+   application program. This is sometimes very effective, since no 
+   intermediate results are sent to the application, only the final 
+   result.
 
 
   <h3>Interpreted Update and Delete</h3>
 
-   Operations for interpreted updates and deletes must follow a
-   certain order when defining operations on a tuple.
-   As for read and write operations,
-   one must first define the operation type and then the search key.
-   -# The first step is to define the initial readings.
-      In this phase it is only allowed to use the
-      NdbOperation::getValue method.
-      This part might be empty.
-   -# The second step is to define the interpreted part.
-      The methods supported are the methods listed below except
-      NdbOperation::def_subroutine and NdbOperation::ret_sub
-      which can only be used in a subroutine.
-      NdbOperation::incValue and NdbOperation::subValue
-      increment and decrement attributes
-      (currently only unsigned integers supported).
-      This part can also be empty since interpreted updates
-      can be used for reading and updating the same tuple.
-      <p>
-      Even though getValue and setValue are not really interpreted
-      program instructions, it is still allowed to use them as
-      the last instruction of the program.
-      (If a getValue or setValue is found when an interpret_exit_ok
-      could have been issued then the interpreted_exit_ok
-      will be inserted.
-      A interpret_exit_ok should be viewed as a jump to the first
-      instruction after the interpreted instructions.)
-   -# The third step is to define all updates without any
-      interpreted program instructions.
-      Here a set of NdbOperation::setValue methods are called.
-      There might be zero such calls.
-   -# The fourth step is the final readings.
-      The initial readings reads the initial value of attributes
-      and the final readings reads them after their updates.
-      There might be zero NdbOperation::getValue calls.
-   -# The fifth step is possible subroutine definitions using
-      NdbOperation::def_subroutine and NdbOperation::ret_sub.
-*/
-#endif
-#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
-/**
+   Operations for interpreted updates and deletes must follow a specific 
+   order when defining operations on a tuple. As for read and write 
+   operations, you must first define the operation type and then the 
+   search key.
+   -# Define the initial readings. In this phase, only the
+      @ref NdbOperation::getValue() method may be used. This step may 
+      be empty (in other words, optional).
+   -# Define the interpreted portion of the operation. The methods 
+      supported are those listed below except for 
+      NdbOperation::def_subroutine() and NdbOperation::ret_sub(), which 
+      can be used only within a subroutine. NdbOperation::incValue() and 
+      NdbOperation::subValue() increment and decrement attributes 
+      (currently only unsigned integers are supported). This step is 
+      also optional, since interpreted updates can be used for reading 
+      and updating the same tuple.
+      <p>Even though getValue() and setValue() are not actually 
+      interpreted program instructions, you can still use them as
+      the last instruction of the program. (If getValue() or setValue() 
+      is found when an interpret_exit_ok could have been issued then the 
+      interpreted_exit_ok is automatically inserted. An 
+      interpret_exit_ok should be viewed as a jump to the first
+      instruction following the interpreted instructions.)</p>
+   -# Define all updates not having any interpreted program 
+      instructions. Here a set of NdbOperation::setValue methods is 
+      called. It is possible not to have any such such calls.
+   -# Define the final readings. The initial readings step reads the 
+      initial value of attributes; the final reading reads them after 
+      they have been updated. It is possible not to have any calls to 
+      NdbOperation::getValue() in this step.
+   -# Define subroutines (if any are required) using
+      NdbOperation::def_subroutine and() NdbOperation::ret_sub().
+      
    <h3>Interpreted Programs</h3>
-   Interpretation programs are executed in a
-   register-based virtual machine.
-   The virtual machine has eight 64 bit registers numbered 0-7.
-   Each register contains type information which is used both
-   for type conversion and for type checking.
-
-   @note Arrays are currently <b>not</b> supported in the virtual machine.
-         Currently only unsigned integers are supported and of size
-         maximum 64 bits.
+   Interpretation programs are executed in a register-based virtual 
+   machine having eight 64-bit registers numbered 0-7. Each register 
+   contains type information which is used for both type conversion and 
+   type checking.
+
+   @note Arrays are currently <b>not</b> supported in the virtual 
+         machine. Currently only unsigned integers are supported, with a 
+         maximum size of 64 bits.
 
-   All errors in the interpretation program will cause a
-   transaction abort, but will not affect any other transactions.
+   Any errors in the interpretation program cause the current
+   transaction to abort, but do not affect any other transactions.
 
    The following are legal interpreted program instructions:
-   -# incValue        : Add to an attribute
-   -# subValue        : Subtract from an attribute
-   -# def_label       : Define a label in the interpreted program
-   -# add_reg         : Add two registers
-   -# sub_reg         : Subtract one register from another
-   -# load_const_u32  : Load an unsigned 32 bit value into a register
-   -# load_const_u64  : Load an unsigned 64 bit value into a register
-   -# load_const_null : Load a NULL value into a register
-   -# read_attr       : Read attribute value into a register
-   -# write_attr      : Write a register value into an attribute
-   -# branch_ge       : Compares registers and possibly jumps to specified label
-   -# branch_gt       : Compares registers and possibly jumps to specified label
-   -# branch_le       : Compares registers and possibly jumps to specified label
-   -# branch_lt       : Compares registers and possibly jumps to specified label
-   -# branch_eq       : Compares registers and possibly jumps to specified label
-   -# branch_ne       : Compares registers and possibly jumps to specified label
-   -# branch_ne_null  : Jumps if register does not contain NULL value
-   -# branch_eq_null  : Jumps if register contains NULL value
-   -# branch_label    : Unconditional jump to label
-   -# interpret_exit_ok  : Exit interpreted program
-                           (approving tuple if used in scan)
-   -# interpret_exit_nok : Exit interpreted program
-                           (disqualifying tuple if used in scan)
+   -# incValue            : Add to an attribute
+   -# subValue            : Subtract from an attribute
+   -# def_label           : Define a label in the interpreted program
+   -# add_reg             : Add two registers
+   -# sub_reg             : Subtract one register from another
+   -# load_const_u32      : Load an unsigned 32 bit value into a register
+   -# load_const_u64      : Load an unsigned 64 bit value into a register
+   -# load_const_null     : Load a NULL value into a register
+   -# read_attr           : Read attribute value into a register
+   -# write_attr          : Write a register value into an attribute
+   -# branch_ge           : Compares registers and possibly jumps to specified label
+   -# branch_gt           : Compares registers and possibly jumps to specified label
+   -# branch_le           : Compares registers and possibly jumps to specified label
+   -# branch_lt           : Compares registers and possibly jumps to specified label
+   -# branch_eq           : Compares registers and possibly jumps to specified label
+   -# branch_ne           : Compares registers and possibly jumps to specified label
+   -# branch_ne_null      : Jumps if register does not contain NULL value
+   -# branch_eq_null      : Jumps if register contains NULL value
+   -# branch_label        : Unconditional jump to label
+   -# interpret_exit_ok   : Exit interpreted program (approving tuple if used in scan)
+   -# interpret_exit_nok  : Exit interpreted program (disqualifying tuple if used in scan)
 
    There are also three instructions for subroutines, which
    are described in the next section.
@@ -811,149 +808,134 @@
 
    The following are legal interpreted program instructions for
    subroutines:
-   -# NdbOperation::def_subroutine : 
-      Defines start of subroutine in interpreted program code
-   -# NdbOperation::call_sub : 
-      Calls a subroutine
-   -# NdbOperation::ret_sub : 
-      Return from subroutine
-
-   The virtual machine executes subroutines using a stack for
-   its operation.
-   The stack allows for up to 24 subroutine calls in succession.
-   Deeper subroutine nesting will cause an abort of the transaction.
-
-   All subroutines starts with the instruction
-   NdbOperation::def_subroutine and ends with the instruction
-   NdbOperation::ret_sub.
-   If it is necessary to return earlier in the subroutine
-   it has to be done using a branch_label instruction
-   to a label defined right before the 
-   NdbOperation::ret_sub instruction.
-
-   @note The subroutines are automatically numbered starting with 0.
-         The parameter used by NdbOperation::def_subroutine 
-	 should match the automatic numbering to make it easier to 
-	 debug the interpreted program.
-*/
-#endif
-
-#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
-/**
+   -# NdbOperation::def_subroutine(): Defines beginning of a subroutine 
+      in interpreted program code.
+   -# NdbOperation::call_sub(): Calls a subroutine.
+   -# NdbOperation::ret_sub(): Returns from a subroutine.
+
+   The virtual machine executes subroutines using a stack for its 
+   operation. The stack allows up to 24 subroutine calls in succession.
+   Deeper subroutine nesting will cause a transaction to abort.
+
+   A subroutine must begin with the instruction
+   NdbOperation::def_subroutine() and end with the instruction
+   NdbOperation::ret_sub(). If it is necessary to return to an earlier 
+   point in the subroutine, this must be done using a branch_label 
+   instruction to a label defined immediately preceding the call to
+   NdbOperation::ret_sub().
+
+   @note Subroutines are automatically numbered starting with 0. The 
+         parameter passed to NdbOperation::def_subroutine() should match 
+         this automatic numbering in order to make it easier to debug 
+         the interpreted program.
+         
    @section secAsync                    Asynchronous Transactions
-   The asynchronous interface is used to increase the speed of
-   transaction executing by better utilizing the connection
-   between the application and the NDB Kernel.
-   The interface is used to send many transactions 
-   at the same time to the NDB kernel.  
-   This is often much more efficient than using synchronous transactions.
-   The main reason for using this method is to ensure that 
-   Sending many transactions at the same time ensures that bigger 
-   chunks of data are sent when actually sending and thus decreasing 
-   the operating system overhead.
+   
+   The asynchronous interface is used to increase the speed of 
+   transaction execution by better utilising the connection between the 
+   application and the NDB Kernel. This interface is used to send 
+   multiple simultaneous transactions to the NDB kernel. This is often 
+   much more efficient than using synchronous transactions. Sending many 
+   transactions at the same time ensures that larger chunks of data are 
+   sent, decreasing operating system overhead.
 
-   The synchronous call to NdbTransaction::execute 
-   normally performs three main steps:<br>
+   The synchronous call to NdbTransaction::execute() normally performs 
+   three main steps:
    -# <b>Prepare</b> 
-      Check transaction status
-      - if problems, abort the transaction
-      - if ok, proceed
+      Check the status of the transaction
+      - in the event of problems, abort the transaction
+      - otherwise, proceed
    -# <b>Send</b> 
-      Send the defined operations since last execute
-      or since start of transaction.
+   Send the operations defined since the last transaction was executed, or 
+      since the start of the transaction.
    -# <b>Poll</b>
-      Wait for response from NDB kernel.
+      Wait for a response from the NDB kernel.
 
-   The asynchronous method NdbTransaction::executeAsynchPrepare 
-   only perform step 1.
-   (The abort part in step 1 is only prepared for.  The actual 
-   aborting of the transaction is performed in a later step.)
-
-   Asynchronous transactions are defined and executed 
-   in the following way.
-   -# Start (create) transactions (same way as for the 
-       synchronous transactions)
-   -# Add and define operations (also as in the synchronous case)
-   -# <b>Prepare</b> transactions 
-       (using NdbTransaction::executeAsynchPrepare or 
-       NdbTransaction::executeAsynch)
-   -# <b>Send</b> transactions to NDB Kernel
-       (using Ndb::sendPreparedTransactions, 
-       NdbTransaction::executeAsynch, or Ndb::sendPollNdb)
-   -# <b>Poll</b> NDB kernel to find completed transactions 
-       (using Ndb::pollNdb or Ndb::sendPollNdb)
-   -# Close transactions (same way as for the synchronous transactions)
+   The asynchronous method NdbTransaction::executeAsynchPrepare() 
+   performs Step 1 only. (The abort operation in Step 1, if necessary, 
+   is prepared but not executed; it is actually performed in a later 
+   step.)
+
+   Asynchronous transactions are defined and executed as follows:
+   -# Instantiate transactions in the same manner as with synchronous 
+      transactions.
+   -# Add and define operations (also as in the synchronous case).
+   -# <b>Prepare</b> transactions using 
+      NdbTransaction::executeAsynchPrepare() or 
+      NdbTransaction::executeAsynch().
+   -# <b>Send</b> transactions to the NDB Kernel using 
+      Ndb::sendPreparedTransactions(), 
+      NdbTransaction::executeAsynch(), or Ndb::sendPollNdb().
+   -# <b>Poll</b> the NDB kernel to find completed transactions, using 
+      Ndb::pollNdb() or Ndb::sendPollNdb().
+   -# Close transactions (again, in the same manner as with synchronous 
+      transactions).
 
-   See example program in section @ref ndbapi_example2.cpp.
+   See also the example program @ref ndbapi_example2.cpp.
    
    This prepare-send-poll protocol actually exists in four variants:
-   - (Prepare-Send-Poll).  This is the one-step variant provided
-     by synchronous transactions.
-   - (Prepare-Send)-Poll.  This is the two-step variant using
-     NdbTransaction::executeAsynch and Ndb::pollNdb.
-   - Prepare-(Send-Poll).  This is the two-step variant using
-     NdbTransaction::executeAsynchPrepare and Ndb::sendPollNdb.
-   - Prepare-Send-Poll.  This is the three-step variant using
-     NdbTransaction::executeAsynchPrepare, Ndb::sendPreparedTransactions, and
-     Ndb::pollNdb.
-  
-   Transactions first has to be prepared by using method
-   NdbTransaction::executeAsynchPrepare or NdbTransaction::executeAsynch.
-   The difference between these is that 
-   NdbTransaction::executeAsynch also sends the transaction to 
-   the NDB kernel.
-   One of the arguments to these methods is a callback method.
-   The callback method is executed during polling (item 5 above).
-  
-   Note that NdbTransaction::executeAsynchPrepare does not 
-   send the transaction to the NDB kernel.  When using 
-   NdbTransaction::executeAsynchPrepare, you either have to call 
-   Ndb::sendPreparedTransactions or Ndb::sendPollNdb to send the 
-   database operations.
-   (Ndb::sendPollNdb also polls Ndb for completed transactions.)
-  
-   The methods Ndb::pollNdb and Ndb::sendPollNdb checks if any 
-   sent transactions are completed.  The method Ndb::sendPollNdb 
-   also send all prepared transactions before polling NDB.
-   Transactions still in the definition phase (i.e. items 1-3 above, 
-   transactions which has not yet been sent to the NDB kernel) are not 
-   affected by poll-calls.
-   The poll method invoked (either Ndb::pollNdb or Ndb::sendPollNdb)
-   will return when:
-    -# at least 'minNoOfEventsToWakeup' of the transactions
-       are finished processing, and
-    -# all of these transactions have executed their 
-       callback methods.
+   - <em>(Prepare-Send-Poll)</em>: The one-step variant provided by 
+     synchronous transactions.
+   - <em>(Prepare-Send)-Poll</em>: A two-step variant using
+     NdbTransaction::executeAsynch() and Ndb::pollNdb().
+   - <em>Prepare-(Send-Poll)</em>: Another two-step variant, but using
+     NdbTransaction::executeAsynchPrepare() and Ndb::sendPollNdb().
+   - <em>Prepare-Send-Poll</em>: The three-step variant using
+     NdbTransaction::executeAsynchPrepare(), 
+     Ndb::sendPreparedTransactions(), and Ndb::pollNdb().
+  
+   Transactions first must be prepared using one of the methods
+   NdbTransaction::executeAsynchPrepare() or 
+   NdbTransaction::executeAsynch(). The difference between these is that 
+   NdbTransaction::executeAsynch() also sends the transaction to 
+   the NDB kernel. One of the arguments to these methods is a callback 
+   method, which is executed during the polling phase (Step 5 above).
+  
+   Note that NdbTransaction::executeAsynchPrepare() does <em>not</em> 
+   send the transaction to the NDB kernel. When using 
+   NdbTransaction::executeAsynchPrepare(), you must either call 
+   Ndb::sendPreparedTransactions() or Ndb::sendPollNdb() in order to 
+   send the database operations. (Note that Ndb::sendPollNdb() also 
+   polls Ndb for completed transactions.)
+  
+   The methods Ndb::pollNdb() and Ndb::sendPollNdb() determine whether 
+   any sent transactions are completed. Ndb::sendPollNdb() also sends 
+   all prepared transactions before polling NDB. Transactions still in 
+   the definition phase (Steps 1-3 above) - that is, transactions which 
+   have not yet been sent to the NDB kernel - are not affected by 
+   polling calls. The poll method invoked (either Ndb::pollNdb() or 
+   Ndb::sendPollNdb()) returns when:
+    -# At least <var>minNoOfEventsToWakeup</var> of the transactions
+       are finished processing; and
+    -# All of these transactions have executed their callback methods.
   
-   The poll method returns the number of transactions that 
-   have finished processing and executed their callback methods.
+   The polling method returns the number of transactions which have 
+   completed processing and have executed their callback methods.
 
    @note When an asynchronous transaction has been started and sent to
-         the NDB kernel, it is not allowed to execute any methods on
+         the NDB kernel, it is not permitted to execute any methods on
          objects belonging to this transaction until the transaction
-         callback method have been executed.
-         (The transaction is stated and sent by either
-	 NdbTransaction::executeAsynch or through the combination of
-         NdbTransaction::executeAsynchPrepare and either
-         Ndb::sendPreparedTransactions or Ndb::sendPollNdb).
+         callback method have been executed. The transaction is sent 
+         either by NdbTransaction::executeAsynch() or through the 
+         combination of NdbTransaction::executeAsynchPrepare() and 
+         either Ndb::sendPreparedTransactions() or Ndb::sendPollNdb().
 
-   More about how transactions are sent the NDB Kernel is 
-   available in section @ref secAdapt.
+   More information about how transactions are sent to the NDB Kernel is 
+   available in @ref secAdapt.
 */
 #endif
 
-
 /**
    
    Put this back when real array ops are supported
    i.e. get/setValue("kalle[3]");
 
    @subsection secArrays             Array Attributes
-   A table attribute in NDB Cluster can be of type <var>Array</var>,
+   A table attribute in NDB Cluster can be of type <code>Array</code>,
    meaning that the attribute consists of an ordered sequence of 
-   elements. In such cases, <var>attribute size</var> is the size
-   (expressed in bits) of any one element making up the array; the 
-   <var>array size</var> is the number of elements in the array.
+   elements. In such cases, <var>attribute_size</var> is the size
+   (expressed in bits) of any one element making up the array, and 
+   <var>array_size</var> is the number of elements in the array.
 
 */
 
@@ -993,8 +975,8 @@
 #if defined NDB_OSE
 /**
  * Default time to wait for response after request has been sent to 
- * NDB Cluster (Set to 10 seconds usually, but to 100 s in 
- * the OSE operating system)
+ * NDB Cluster. (Usually set to 10 seconds, but set to 100 sec in 
+ * the OSE operating system.)
  */
 #define WAITFOR_RESPONSE_TIMEOUT 100000 // Milliseconds
 #else
@@ -1005,43 +987,34 @@
  * @class Ndb 
  * @brief Represents the NDB kernel and is the main class of the NDB API.
  *
- * Always start your application program by creating an Ndb object. 
- * By using several Ndb objects it is possible to design 
- * a multi-threaded application, but note that Ndb objects 
- * cannot be shared by several threads. 
- * Different threads should use different Ndb objects. 
- * A thread might however use multiple Ndb objects.
- * Currently there is a limit of maximum 128 Ndb objects 
- * per application process.
+ * Always begin your application program by creating an instance of Ndb. 
+ * By using several Ndb objects it is possible to implement a 
+ * multi-threaded application; however, you should remember that one Ndb 
+ * object cannot be shared between threads. It is possible for a single 
+ * thread to use multiple Ndb objects. Note that a single application 
+ * process can support a maximum of 128 Ndb objects.
  *
- * @note It is not allowed to call methods in the NDB API 
- *       on the same Ndb object in different threads 
- *       simultaneously (without special handling of the 
- *       Ndb object).
- *
- * @note The Ndb object is multi-thread safe in the following manner. 
- *       Each Ndb object can ONLY be handled in one thread. 
- *       If an Ndb object is handed over to another thread then the 
- *       application must ensure that a memory barrier is used to 
- *       ensure that the new thread see all updates performed by 
- *       the previous thread. 
- *       Semaphores, mutexes and so forth are easy ways of issuing memory 
- *       barriers without having to bother about the memory barrier concept.
+ * @note The Ndb object is multi-thread safe in that each Ndb object can 
+ *       be handled by one thread at a time. If an Ndb object is handed 
+ *       over to another thread, then the application must ensure that a 
+ *       memory barrier is used to ensure that the new thread sees all 
+ *       updates performed by the previous thread. (Semaphores and 
+ *       mutexes are examples of easy ways to provide memory barriers 
+ *       without having to bother about the memory barrier concept.)
  *
  */
 
 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
 // to be documented later
 /*
- * If one Ndb object is used to handle parallel transactions through the 
- * asynchronous programming interface, please read the notes regarding
- * asynchronous transactions (Section @ref secAsync).
- * The asynchronous interface provides much higher performance 
- * in some situations, but is more complicated for the application designer. 
+ * If you use a single instance of Ndb to handle parallel transactions 
+ * using the asynchronous programming interface, you should be sure to 
+ * read the notes regarding asynchronous transactions found in @ref 
+ * secAsync. The asynchronous interface provides much higher performance 
+ * in some situations, but is more complex. 
  *
- * @note Each Ndb object should either use the methods for 
- *       asynchronous transaction or the methods for 
- *       synchronous transactions but not both.
+ * @note Each Ndb object should use the methods for either asynchronous 
+ *       or synchronous transactions, but not both.
  */
 #endif
 
@@ -1072,17 +1045,17 @@
   /**
    * The Ndb object represents a connection to a database.
    *
-   * @note The init() method must be called before the Ndb object may actually be used.
+   * @note The init() method must be called before the Ndb object may 
+   *       actually be used.
    *
-   * @param ndb_cluster_connection is a connection to the cluster containing
-   *        the database to be used
+   * @param ndb_cluster_connection is a connection to the cluster
+   *        containing the database to be used.
    * @param aCatalogName is the name of the catalog to be used.
    * @note The catalog name provides a namespace for the tables and
    *       indexes created in any connection from the Ndb object.
-   * @param aSchemaName is the name of the schema you 
-   *        want to use.
-   * @note The schema name provides an additional namespace 
-   *       for the tables and indexes created in a given catalog.
+   * @param aSchemaName is the name of the schema to be uses.
+   * @note The schema name provides an additional namespace for the 
+   *       tables and indexes created in a given catalog.
    */
   Ndb(Ndb_cluster_connection *ndb_cluster_connection,
       const char* aCatalogName = "", const char* aSchemaName = "def");
@@ -1091,72 +1064,75 @@
 
 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
   /**
-   * The current catalog name can be fetched by getCatalogName.
+   * The current catalog name can be obtained using getCatalogName().
    *
-   * @return the current catalog name
+   * @return The current catalog name.
    */
   const char * getCatalogName() const;
 
   /**
-   * The current catalog name can be set by setCatalogName.
+   * The current catalog name can be set using setCatalogName().
    *
-   * @param aCatalogName is the new name of the current catalog
+   * @param aCatalogName The new name of the current catalog.
    */
   void setCatalogName(const char * aCatalogName);
 
   /**
-   * The current schema name can be fetched by getSchemaName.
+   * The current schema name can be obtained using getSchemaName().
    *
-   * @return the current schema name
+   * @return The current schema name.
    */
   const char * getSchemaName() const;
 
   /**
-   * The current schema name can be set by setSchemaName.
+   * The current schema name can be set using setSchemaName().
    *
-   * @param aSchemaName is the new name of the current schema
+   * @param aSchemaName The new name for the current schema.
    */
   void setSchemaName(const char * aSchemaName);
 #endif
 
   /**
-   * The current database name can be fetched by getDatabaseName.
+   * The current database name can be obtained using getDatabaseName().
    *
-   * @return the current database name
+   * @return The current database name.
    */
   const char * getDatabaseName() const;
 
   /**
-   * The current database name can be set by setDatabaseName.
+   * The current database name can be set using setDatabaseName().
    *
-   * @param aDatabaseName is the new name of the current database
+   * @param aDatabaseName The new name of the current database.
    */
   void setDatabaseName(const char * aDatabaseName);
 
   /**
-   * The current database schema name can be fetched by getDatabaseSchemaName.
+   * The current database schema name can be obtained using 
+   * getDatabaseSchemaName().
    *
-   * @return the current database schema name
+   * @return The current database schema name.
    */
   const char * getDatabaseSchemaName() const;
 
   /**
-   * The current database schema name can be set by setDatabaseSchemaName.
+   * The current database schema name can be set using
+   * setDatabaseSchemaName().
    *
-   * @param aDatabaseSchemaName is the new name of the current database schema
+   * @param aDatabaseSchemaName The new name for the current database 
+   *        schema
    */
   void setDatabaseSchemaName(const char * aDatabaseSchemaName);
 
   /**
-   * Initializes the Ndb object
+   * Initialises the Ndb object.
    *
    * @param  maxNoOfTransactions 
-   *         Maximum number of parallel 
-   *         NdbTransaction objects that can be handled by the Ndb object.
-   *         Maximum value is 1024.
+   *         Maximum number of parallel NdbTransaction objects that can 
+   *         be handled by this instance of Ndb. The maximum value is 
+   *         1024.
    *
-   * @note each scan or index scan operation uses one extra
-   *       NdbTransaction object
+   * @note Each scan or index scan operation uses one extra
+   *       NdbTransaction object.
    *
    * @return 0 if successful, -1 otherwise.
    */
@@ -1164,16 +1140,14 @@
 
 #ifndef DOXYGEN_SHOULD_SKIP_DEPRECATED
   /**
-   * Wait for Ndb object to successfully set-up connections to 
-   * the NDB kernel. 
-   * Starting to use the Ndb object without using this method 
-   * gives unspecified behavior. 
+   * Waits for an Ndb object to set up connections to the NDB kernel. 
+   * <em>Warning</em>: Using the Ndb object without first calling this 
+   * method results in unspecified behaviour.
    * 
-   * @param  timeout  The maximum time we will wait for 
-   *                  the initiation process to finish.
-   *                  Timeout is expressed in seconds.
-   * @return  0: Ndb is ready and timeout has not occurred.<br>
-   *          -1: Timeout has expired
+   * @param  timeout  The maximum time allotted for the initialisation 
+   *                  process to complete, in seconds.
+   * @return  0 if the Ndb object is ready, or -1 if the initialisation 
+   *          process timed out.
    */
   int waitUntilReady(int timeout = 60);
 #endif
@@ -1186,12 +1160,13 @@
    */
 
   /**
-   * Get an object for retrieving or manipulating database schema information 
+   * Gets an object for retrieving or manipulating database schema 
+   * information.
    *
-   * @note this object operates outside any transaction
+   * @note This object operates apart from any transactions.
    *
-   * @return Object containing meta information about all tables 
-   *         in NDB Cluster.
+   * @return Object containing meta information about all tables in the 
+   *         cluster.
    */
   class NdbDictionary::Dictionary* getDictionary() const;
   
@@ -1204,39 +1179,38 @@
    */
 
   /**
-   * Create a subcription to an event defined in the database
+   * Creates a subscription to an event defined in the database.
    *
-   * @param eventName
-   *        unique identifier of the event
+   * @param eventName Unique identifier for this event
    *
-   * @return Object representing an event, NULL on failure
+   * @return Object representing an event, or NULL on failure.
    */
   NdbEventOperation* createEventOperation(const char* eventName);
   /**
-   * Drop a subscription to an event
+   * Drops a subscription to an event.
    *
-   * @param eventOp
-   *        Event operation
+   * @param eventOp Event operation.
    *
    * @return 0 on success
    */
   int dropEventOperation(NdbEventOperation* eventOp);
 
   /**
-   * Wait for an event to occur. Will return as soon as an event
-   * is detected on any of the created events.
+   * Waits for an event to occur. Returns as soon as an event is 
+   * detected for any events that have been created.
    *
-   * @param aMillisecondNumber
-   *        maximum time to wait
+   * @param aMillisecondNumber Maximum time to wait.
    *
-   * @return > 0 if events available, 0 if no events available, < 0 on failure
+   * @return > 0 if events are available,<br> 0 if no events are available,<br> 
+   *         or < 0 on failure
    */
   int pollEvents(int aMillisecondNumber, Uint64 *latestGCI= 0);
 
   /**
    * Returns an event operation that has data after a pollEvents
    *
-   * @return an event operations that has data, NULL if no events left with data.
+   * @return An event operation yielding data, or <code>NULL</code> if 
+   * there are no remaining events with data.
    */
   NdbEventOperation *nextEvent();
 
@@ -1256,41 +1230,41 @@
    */
 
   /**
-   * Start a transaction
+   * Starts a transaction:
    *
    * @note When the transaction is completed it must be closed using
-   *       Ndb::closeTransaction or NdbTransaction::close. 
-   *       The transaction must be closed independent of its outcome, i.e.
-   *       even if there is an error.
+   *       Ndb::closeTransaction() or NdbTransaction::close(). A 
+   *       transaction must be closed regardless of its success or 
+   *       failure. This includes a transaction that has raised an 
+   *       error.
    *
-   * @param  table    Pointer to table object used for deciding 
-   *                  which node to run the Transaction Coordinator on
+   * @param  table    Pointer to table object used for deciding on
+   *                  which node to run the Transaction Co-Ordinator.
    * @param  keyData  Pointer to partition key corresponding to
-   *                  <var>table</var>
-   * @param  keyLen   Length of partition key expressed in bytes
+   *                  <var>table</var>.
+   * @param  keyLen   Length of partition key, expressed in bytes.
    * 
    * @return NdbTransaction object, or NULL on failure.
    */
   NdbTransaction* startTransaction(const NdbDictionary::Table *table= 0,
-				   const char  *keyData = 0, 
-				   Uint32       keyLen = 0);
+           const char  *keyData = 0, 
+           Uint32       keyLen = 0);
 
   /**
-   * Close a transaction.
+   * Close a transaction:
    *
-   * @note should be called after the transaction has completed, irrespective
-   *       of success or failure
+   * @note This method should be called after the transaction is 
+   *       complete, regardless of success or failure
    */
 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
   /**
-   * @note It is not allowed to call Ndb::closeTransaction after sending the
-   *       transaction asynchronously with either 
-   *       Ndb::sendPreparedTransactions or
-   *       Ndb::sendPollNdb before the callback method has been called.
-   *       (The application should keep track of the number of 
-   *       outstanding transactions and wait until all of them 
-   *       has completed before calling Ndb::closeTransaction).
-   *       If the transaction is not committed it will be aborted.
+   * @note Calling Ndb::closeTransaction() after sending the transaction 
+   *       asynchronously (with either Ndb::sendPreparedTransactions() 
+   *       or Ndb::sendPollNdb() before its callback method has been 
+   *       invoked) is not permitted. The application should keep track 
+   *       of the number of outstanding transactions and wait until all 
+   *       of them are completed before calling Ndb::closeTransaction().
+   *       If the transaction was not committed, it is aborted.
    */
 #endif
   void closeTransaction(NdbTransaction*);
@@ -1305,75 +1279,74 @@
    */
 
   /**
-   * Wait for prepared transactions.
-   * Will return as soon as at least 'minNoOfEventsToWakeUp' 
-   * of them have completed, or the maximum time given as timeout has passed.
+   * Waits for prepared transactions.
+   * Returns as soon as at least <var>minNoOfEventsToWakeUp</var> of them 
+   * have completed, or the maximum time given as the timeout has passed.
    *
    * @param aMillisecondNumber 
-   *        Maximum time to wait for transactions to complete. Polling 
-   *        without wait is achieved by setting the timer to zero.
-   *        Time is expressed in milliseconds.
+   *        Maximum time to wait for transactions to complete, in 
+   *        milliseconds. Polling without waiting is achieved by setting 
+   *        the timer to zero.
    * @param minNoOfEventsToWakeup Minimum number of transactions 
-   *            which has to wake up before the poll-call will return.
-   *            If minNoOfEventsToWakeup is
-   *            set to a value larger than 1 then this is the minimum 
-   *            number of transactions that need to complete before the 
-   *            poll will return.
-   *            Setting it to zero means that one should wait for all
-   *            outstanding transactions to return before waking up.
+   *        which must wake up before the polling call returns. If 
+   *        <var>minNoOfEventsToWakeup</var> is set to a value greater 
+   *        than 1, then this is the minimum number of transactions that 
+   *        need to complete before the poll returns. Setting it to zero 
+   *        means that you should wait for all outstanding transactions 
+   *        to return before waking up.
    * @return Number of transactions polled.
    */
   int  pollNdb(int aMillisecondNumber = WAITFOR_RESPONSE_TIMEOUT,
-	      int minNoOfEventsToWakeup = 1);
+         int minNoOfEventsToWakeup = 1);
 
   /**
-   * This send method will send all prepared database operations. 
-   * The default method is to do it non-force and instead
-   * use the adaptive algorithm.  (See Section @ref secAdapt.)
-   * The second option is to force the sending and 
-   * finally there is the third alternative which is 
-   * also non-force but also making sure that the 
-   * adaptive algorithm do not notice the send. 
-   * In this case the sending will be performed on a 
-   * cyclical 10 millisecond event.
-   *
-   * @param forceSend When operations should be sent to NDB Kernel.
-   *                  (See @ref secAdapt.)
-   *                  - 0: non-force, adaptive algorithm notices it (default); 
-   *                  - 1: force send, adaptive algorithm notices it; 
-   *                  - 2: non-force, adaptive algorithm do not notice the send.
+   * This send method sends all prepared database operations. The 
+   * default behavuiour is to do so without forcing and instead employ 
+   * the adaptive send algorithm (see @ref secAdapt). A second option is 
+   * to force the sending. The third and final alternative is also 
+   * non-forced but makes sure that the adaptive algorithm does not 
+   * "see" the send; in this case the send will be performed as a 
+   * cyclic 10-millisecond event.
+   *
+   * @param forceSend When operations should be sent to NDB Kernel (see 
+   *                  @ref secAdapt):
+   *                  - 0: Non-forced, visible to adaptive algorithm 
+   *                       (the default);
+   *                  - 1: Forced, visible to the adaptive algorithm; 
+   *                  - 2: Non-forced, not visible to the adaptive 
+   *                       algorithm.
    */
   void sendPreparedTransactions(int forceSend = 0);
 
   /**
-   * This is a send-poll variant that first calls 
-   * Ndb::sendPreparedTransactions and then Ndb::pollNdb. 
-   * It is however somewhat faster than calling the methods 
-   * separately, since some mutex-operations are avoided. 
-   * See documentation of Ndb::pollNdb and Ndb::sendPreparedTransactions
-   * for more details.
+   * This is a send/poll variant that first calls 
+   * Ndb::sendPreparedTransactions() and then Ndb::pollNdb(). It is 
+   * somewhat faster than calling the methods separately, since some 
+   * mutex operations are avoided. See the documentation for these 
+   * methods for additional information.
    *
    * @param aMillisecondNumber Timeout specifier
-   *            Polling without wait is achieved by setting the 
+   *            Polling without waiting is achieved by setting the 
    *            millisecond timer to zero.
    * @param minNoOfEventsToWakeup Minimum number of transactions 
-   *            which has to wake up before the poll-call will return.
-   *            If minNoOfEventsToWakeup is
-   *            set to a value larger than 1 then this is the minimum 
-   *            number of transactions that need to complete before the 
-   *            poll-call will return.
-   *            Setting it to zero means that one should wait for all
-   *            outstanding transactions to return before waking up.
-   * @param forceSend When operations should be sent to NDB Kernel.
-   *                  (See @ref secAdapt.)
-   * - 0: non-force, adaptive algorithm notices it (default); 
-   * - 1: force send, adaptive algorithm notices it; 
-   * - 2: non-force, adaptive algorithm does not notice the send.
-   * @return Number of transactions polled.
+   *            which must wake up before the polling call returns.
+   *            If <var>minNoOfEventsToWakeup</var> is set to a value 
+   *            greater than 1, then this represents the minimum number 
+   *            of transactions that must be completed before the 
+   *            polling call may return. Setting this to zero means that 
+   *            you should wait for all outstanding transactions to 
+   *            return before waking up.
+   * @param forceSend When operations should be sent to NDB Kernel (see 
+   *                  @ref secAdapt):
+   *                  - 0: Non-forced, visible to adaptive algorithm 
+   *                       (the default);
+   *                  - 1: Forced, visible to the adaptive algorithm; 
+   *                  - 2: Non-forced, not visible to the adaptive 
+   *                       algorithm.
    */
   int  sendPollNdb(int aMillisecondNumber = WAITFOR_RESPONSE_TIMEOUT,
-		   int minNoOfEventsToWakeup = 1,
-		   int forceSend = 0);
+       int minNoOfEventsToWakeup = 1,
+       int forceSend = 0);
   /** @} *********************************************************************/
 #endif
   
@@ -1383,16 +1356,18 @@
    */
 
   /**
-   * Get the NdbError object
+   * Gets an NdbError object.
    *
-   * @note The NdbError object is valid until a new NDB API method is called.
+   * @note The NdbError object is valid until a new NDB API method is 
+   *       called.
    */
   const NdbError & getNdbError() const;
   
   /**
-   * Get a NdbError object for a specific error code
+   * Gets an NdbError object for a specific error code.
    *
-   * The NdbError object is valid until you call a new NDB API method.
+   * @note The NdbError object is valid until a new NDB API method is 
+   *       called.
    */
   const NdbError & getNdbError(int errorCode);
 
@@ -1401,19 +1376,19 @@
 
 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
   /**
-   * Get the application node identity.  
+   * Gets the identity of the application node.
    *
-   * @return Node id of this application.
+   * @return Node ID of this application.
    */
   int getNodeId();
 
   bool usingFullyQualifiedNames();
 
   /**
-   * Different types of tampering with the NDB Cluster.
-   * <b>Only for debugging purposes only.</b>
+   * Different ways to "tamper" with the NDB Cluster.
+   * <em>For debugging purposes only</em>.
    */
-  enum TamperType	{ 
+  enum TamperType { 
     LockGlbChp = 1,           ///< Lock GCP
     UnlockGlbChp,             ///< Unlock GCP
     CrashNode,                ///< Crash an NDB node
@@ -1425,47 +1400,47 @@
   /**
    * For testing purposes it is possible to tamper with the NDB Cluster
    * (i.e. send a special signal to DBDIH, the NDB distribution handler).
-   * <b>This feature should only used for debugging purposes.</b>
-   * In a release versions of NDB Cluster,
-   * this call always return -1 and does nothing.
+   * <em>This feature should be used for debugging purposes only.</em>
+   * In a release version of NDB Cluster, this call always returns -1 and does
+   * nothing.
    * 
-   * @param aAction Action to be taken according to TamperType above
+   * @param aAction Action to be taken according to the TamperType.
    *
-   * @param aNode  Which node the action will be taken
-   *              -1:   Master DIH.
-   *            0-16:   Nodnumber.
-   * @return -1 indicates error, other values have meaning dependent 
-   *          on type of tampering.
+   * @param aNode For which node the action will be taken:
+   *                -1:   Master DIH.
+   *              0-16:   Nodenumber.
+   * @return -1 indicates error, other values have meanings dependent 
+   *          on the type of tampering specified.
    */
   int NdbTamper(TamperType aAction, int aNode);  
 
   /**
-   * Return a unique tuple id for a table.  The id sequence is
-   * ascending but may contain gaps.
+   * Returns a unique tuple ID for a table. The sequence of IDs assigned 
+   * is ascending but may contain gaps.
    *
-   * @param aTableName table name
+   * @param aTableName Table name.
    *
-   * @param cacheSize number of values to cache in this Ndb object
+   * @param cacheSize Number of values to cache in this Ndb object.
    *
-   * @return tuple id or 0 on error
+   * @return Tuple ID, or 0 on error.
    */
   Uint64 getAutoIncrementValue(const char* aTableName, 
-			       Uint32 cacheSize = 1);
+             Uint32 cacheSize = 1);
   Uint64 getAutoIncrementValue(const NdbDictionary::Table * aTable, 
-			       Uint32 cacheSize = 1);
+             Uint32 cacheSize = 1);
   Uint64 readAutoIncrementValue(const char* aTableName);
   Uint64 readAutoIncrementValue(const NdbDictionary::Table * aTable);
   bool setAutoIncrementValue(const char* aTableName, Uint64 val, 
-			     bool increase = false);
+           bool increase = false);
   bool setAutoIncrementValue(const NdbDictionary::Table * aTable, Uint64 val, 
-			     bool increase = false);
+           bool increase = false);
   Uint64 getTupleIdFromNdb(const char* aTableName, 
-			   Uint32 cacheSize = 1000);
+         Uint32 cacheSize = 1000);
   Uint64 getTupleIdFromNdb(Uint32 aTableId, 
-			   Uint32 cacheSize = 1000);
+         Uint32 cacheSize = 1000);
   Uint64 readTupleIdFromNdb(Uint32 aTableId);
   bool setTupleIdInNdb(const char* aTableName, Uint64 val, 
-		       bool increase);
+           bool increase);
   bool setTupleIdInNdb(Uint32 aTableId, Uint64 val, bool increase);
   Uint64 opTupleIdOnNdb(Uint32 aTableId, Uint64 opValue, Uint32 op);
 
@@ -1488,7 +1463,7 @@
   
 
 /*****************************************************************************
- *	These are service routines used by the other classes in the NDBAPI.
+ *  These are service routines used by the other classes in the NDB API.
  ****************************************************************************/
  Uint32 get_cond_wait_index() { return cond_wait_index; }
  void set_cond_wait_index(Uint32 index) { cond_wait_index = index; }
@@ -1498,7 +1473,7 @@
   void cond_signal();
   
   void setup(Ndb_cluster_connection *ndb_cluster_connection,
-	     const char* aCatalogName, const char* aSchemaName);
+       const char* aCatalogName, const char* aSchemaName);
 
   void connected(Uint32 block_reference);
  
@@ -1508,32 +1483,32 @@
 // Connect the connection object to the Database.
   int NDB_connect(Uint32 tNode);
   NdbTransaction* doConnect(Uint32 nodeId); 
-  void    doDisconnect();	 
+  void    doDisconnect();  
   
-  NdbReceiver*	        getNdbScanRec();// Get a NdbScanReceiver from idle list
-  NdbLabel*		getNdbLabel();	// Get a NdbLabel from idle list
-  NdbBranch*            getNdbBranch();	// Get a NdbBranch from idle list
-  NdbSubroutine*	getNdbSubroutine();// Get a NdbSubroutine from idle
-  NdbCall*		getNdbCall();	// Get a NdbCall from idle list
-  NdbApiSignal*	        getSignal();	// Get an operation from idle list
-  NdbRecAttr*	        getRecAttr();	// Get a receeive attribute object from
-					// idle list of the Ndb object.
-  NdbOperation* 	getOperation();	// Get an operation from idle list
+  NdbReceiver*          getNdbScanRec();// Get a NdbScanReceiver from idle list
+  NdbLabel*   getNdbLabel();  // Get a NdbLabel from idle list
+  NdbBranch*            getNdbBranch(); // Get a NdbBranch from idle list
+  NdbSubroutine*  getNdbSubroutine();// Get a NdbSubroutine from idle
+  NdbCall*    getNdbCall(); // Get a NdbCall from idle list
+  NdbApiSignal*         getSignal();  // Get an operation from idle list
+  NdbRecAttr*         getRecAttr(); // Get a receeive attribute object from
+          // idle list of the Ndb object.
+  NdbOperation*   getOperation(); // Get an operation from idle list
   NdbIndexScanOperation* getScanOperation(); // Get a scan operation from idle
-  NdbIndexOperation* 	getIndexOperation();// Get an index operation from idle
+  NdbIndexOperation*  getIndexOperation();// Get an index operation from idle
 
   NdbBlob*              getNdbBlob();// Get a blob handle etc
 
-  void			releaseSignal(NdbApiSignal* anApiSignal);
+  void      releaseSignal(NdbApiSignal* anApiSignal);
   void                  releaseSignalsInList(NdbApiSignal** pList);
-  void			releaseNdbScanRec(NdbReceiver* aNdbScanRec);
-  void			releaseNdbLabel(NdbLabel* anNdbLabel);
-  void			releaseNdbBranch(NdbBranch* anNdbBranch);
-  void			releaseNdbSubroutine(NdbSubroutine* anNdbSubroutine);
-  void			releaseNdbCall(NdbCall* anNdbCall);
-  void			releaseRecAttr (NdbRecAttr* aRecAttr);	
-  void		 	releaseOperation(NdbOperation* anOperation);	
-  void		 	releaseScanOperation(NdbIndexScanOperation*);
+  void      releaseNdbScanRec(NdbReceiver* aNdbScanRec);
+  void      releaseNdbLabel(NdbLabel* anNdbLabel);
+  void      releaseNdbBranch(NdbBranch* anNdbBranch);
+  void      releaseNdbSubroutine(NdbSubroutine* anNdbSubroutine);
+  void      releaseNdbCall(NdbCall* anNdbCall);
+  void      releaseRecAttr (NdbRecAttr* aRecAttr);  
+  void      releaseOperation(NdbOperation* anOperation);  
+  void      releaseScanOperation(NdbIndexScanOperation*);
   void                  releaseNdbBlob(NdbBlob* aBlob);
 
   void                  check_send_timeout();
@@ -1545,62 +1520,62 @@
   // synchronous and asynchronous interface
   void handleReceivedSignal(NdbApiSignal* anApiSignal, struct LinearSectionPtr ptr[3]);
   
-  int			sendRecSignal(Uint16 aNodeId,
-				      Uint32 aWaitState,
-				      NdbApiSignal* aSignal,
+  int     sendRecSignal(Uint16 aNodeId,
+              Uint32 aWaitState,
+              NdbApiSignal* aSignal,
                                       Uint32 nodeSequence,
                                       Uint32 *ret_conn_seq= 0);
   
   // Sets Restart GCI in Ndb object
-  void			RestartGCI(int aRestartGCI);
+  void      RestartGCI(int aRestartGCI);
 
   // Get block number of this NDBAPI object
-  int			getBlockNumber();
+  int     getBlockNumber();
   
   /****************************************************************************
-   *	These are local service routines used by this class.	
+   *  These are local service routines used by this class.  
    ***************************************************************************/
   
-  int			createConIdleList(int aNrOfCon);
-  int 		createOpIdleList( int nrOfOp );	
+  int     createConIdleList(int aNrOfCon);
+  int     createOpIdleList( int nrOfOp ); 
 
-  void	freeOperation();          // Free the first idle operation.
-  void	freeScanOperation();      // Free the first idle scan operation.
-  void	freeIndexOperation();     // Free the first idle index operation.
-  void	freeNdbCon();	// Free the first idle connection.
-  void	freeSignal();	// Free the first idle signal	
-  void	freeRecAttr();	// Free the first idle receive attr obj	
-  void	freeNdbLabel();	// Free the first idle NdbLabel obj
-  void	freeNdbBranch();// Free the first idle NdbBranch obj
-  void	freeNdbSubroutine();// Free the first idle NdbSubroutine obj
-  void	freeNdbCall();	    // Free the first idle NdbCall obj
-  void	freeNdbScanRec();   // Free the first idle NdbScanRec obj
+  void  freeOperation();          // Free the first idle operation.
+  void  freeScanOperation();      // Free the first idle scan operation.
+  void  freeIndexOperation();     // Free the first idle index operation.
+  void  freeNdbCon(); // Free the first idle connection.
+  void  freeSignal(); // Free the first idle signal
+  void  freeRecAttr();  // Free the first idle receive attr obj 
+  void  freeNdbLabel(); // Free the first idle NdbLabel obj
+  void  freeNdbBranch();// Free the first idle NdbBranch obj
+  void  freeNdbSubroutine();// Free the first idle NdbSubroutine obj
+  void  freeNdbCall();      // Free the first idle NdbCall obj
+  void  freeNdbScanRec();   // Free the first idle NdbScanRec obj
   void  freeNdbBlob();      // Free the first etc
 
-  NdbTransaction* getNdbCon();	// Get a connection from idle list
+  NdbTransaction* getNdbCon();  // Get a connection from idle list
   
   /**
-   * Get a connected NdbTransaction to nodeId
-   *   Returns NULL if none found
+   * Gets an NdbTransaction connected to node <var>nodeId</var>.
+   *   Returns <code>NULL</code> if none is found.
    */
   NdbTransaction* getConnectedNdbTransaction(Uint32 nodeId);
 
-  // Release and disconnect from DBTC a connection
-  // and seize it to theConIdleList
-  void	releaseConnectToNdb (NdbTransaction*);
+  // Releases and disconnects a connection from DBTC
+  // and attaches it to theConIdleList
+  void  releaseConnectToNdb (NdbTransaction*);
 
-  // Release a connection to idle list
-  void 	releaseNdbCon (NdbTransaction*);
+  // Releases a connection to idle list
+  void  releaseNdbCon (NdbTransaction*);
   
-  int	checkInitState();		// Check that we are initialized
-  void	report_node_failure(Uint32 node_id);           // Report Failed node
-  void	report_node_failure_completed(Uint32 node_id); // Report Failed node(NF comp.)
+  int checkInitState();   // Check that we are initialised
+  void  report_node_failure(Uint32 node_id);           // Report Failed node
+  void  report_node_failure_completed(Uint32 node_id); // Report Failed node(NF comp.)
 
-  void	checkFailedNode();		// Check for failed nodes
+  void  checkFailedNode();    // Checks for failed nodes
 
-  int   NDB_connect();     // Perform connect towards NDB Kernel
+  int   NDB_connect();     // Performs connection to NDB Kernel
 
-  // Release arrays of NdbTransaction pointers
+  // Releases arrays of NdbTransaction pointers
   void  releaseTransactionArrays();     
 
   Uint32  pollCompleted(NdbTransaction** aCopyArray);
@@ -1608,7 +1583,7 @@
   void    reportCallback(NdbTransaction** aCopyArray, Uint32 aNoOfComplTrans);
   int     poll_trans(int milliSecs, int noOfEventsToWaitFor, PollGuard *pg);
   void    waitCompletedTransactions(int milliSecs, int noOfEventsToWaitFor,
-		                    PollGuard *pg);
+                        PollGuard *pg);
   void    completedTransaction(NdbTransaction* aTransaction);
   void    completedScanTransaction(NdbTransaction* aTransaction);
 
@@ -1639,7 +1614,7 @@
   NdbIndexOperation* void2rec_iop (void* val);
 
 /******************************************************************************
- *	These are the private variables in this class.	
+ *  These are the private variables in this class.  
  *****************************************************************************/
   NdbTransaction**       thePreparedTransactionsArray;
   NdbTransaction**       theSentTransactionsArray;
@@ -1662,7 +1637,7 @@
   class NdbDictionaryImpl* theDictionary;
   class NdbEventBuffer* theEventBuffer;
 
-  NdbTransaction*	theTransactionList;
+  NdbTransaction* theTransactionList;
   NdbTransaction**      theConnectionArray;
 
   Uint32   theMyRef;        // My block reference  
@@ -1671,16 +1646,16 @@
   Uint64               the_last_check_time;
   Uint64               theFirstTransId;
   
-  // The tupleId is retreived from DB the 
-  // tupleId is unique for each tableid. 
+  // The tupleId is retrieved from the DB; the 
+  // tupleId is unique for each tableId. 
   Uint64               theFirstTupleId[2048]; 
   Uint64               theLastTupleId[2048];           
 
-  Uint32		theRestartGCI;	// the Restart GCI used by DIHNDBTAMPER
+  Uint32    theRestartGCI;  // The Restart GCI used by DIHNDBTAMPER.
   
   NdbError              theError;
 
-  Int32        	        theNdbBlockNumber;
+  Int32                 theNdbBlockNumber;
 
   enum InitType {
     NotConstructed,
@@ -1701,7 +1676,7 @@
 #endif
 
   static void executeMessage(void*, NdbApiSignal *, 
-			     struct LinearSectionPtr ptr[3]);
+           struct LinearSectionPtr ptr[3]);
   static void statusMessage(void*, Uint32, bool, bool);
 #ifdef VM_TRACE
   void printState(const char* fmt, ...);
Thread
bk commit into 5.1 tree (jon:1.2099)jon31 Jan