Merge mskold@bk-internal.mysql.com:/home/bk/mysql-5.0-ndb

into mysql.com:/usr/local/home/marty/MySQL/test/mysql-5.0-ndb

ndb/examples/Makefile

-BIN_DIRS := ndbapi_example1 ndbapi_example3 ndbapi_example4 \
-	    ndbapi_example5 ndbapi_scan_example
+BIN_DIRS := 	ndbapi_simple_example \
+	 	ndbapi_async_example \
+	 	ndbapi_async_example1 \
+		ndbapi_retries_example \
+		ndbapi_simple_index_example \
+		ndbapi_event_example \
+		ndbapi_scan_example
 
 bins: $(patsubst %, _bins_%, $(BIN_DIRS))
 

ndb/examples/ndbapi_example3/Makefile → ndb/examples/ndbapi_async_example1/Makefile

-TARGET = ndbapi_example3
-SRCS = ndbapi_example3.cpp
-OBJS = ndbapi_example3.o
+TARGET = ndbapi_async1
+SRCS = ndbapi_async1.cpp
+OBJS = ndbapi_async1.o
 CXX = g++
 CFLAGS = -c -Wall -fno-rtti -fno-exceptions
 DEBUG = 

ndb/examples/ndbapi_example2/ndbapi_example2.cpp → ndb/examples/ndbapi_async_example1/ndbapi_async1.cpp

@@ -15,7 +15,7 @@
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */
 
 //
-//  ndbapi_example2.cpp: Using asynchronous transactions in NDB API
+//  ndbapi_async1.cpp: Using asynchronous transactions in NDB API
 //
 //  Execute ndbapi_example1 to create the table "MYTABLENAME"
 //  before executing this program.

ndb/examples/ndbapi_example5/Makefile → ndb/examples/ndbapi_event_example/Makefile

-TARGET = ndbapi_example5
-SRCS = ndbapi_example5.cpp
-OBJS = ndbapi_example5.o
+TARGET = ndbapi_event
+SRCS = ndbapi_event.cpp
+OBJS = ndbapi_event.o
 CXX = g++
 CFLAGS = -c -Wall -fno-rtti -fno-exceptions
 CXXFLAGS = 

ndb/examples/ndbapi_example5/ndbapi_example5.cpp → ndb/examples/ndbapi_event_example/ndbapi_event.cpp

@@ -15,7 +15,38 @@
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */
 
 /**
- * ndbapi_example5.cpp: Using API level events in NDB API
+ *  ndbapi_event.cpp: Using API level events in NDB API
+ *
+ *  Classes and methods used in this example:
+ *
+ *  Ndb_cluster_connection
+ *       connect()
+ *       wait_until_ready()
+ *
+ *  Ndb
+ *       init()
+ *       getDictionary()
+ *       createEventOperation()
+ *       dropEventOperation()
+ *       pollEvents()
+ *
+ *  NdbDictionary
+ *       createEvent()
+ *       dropEvent()
+ *
+ *  NdbDictionary::Event
+ *       setTable()
+ *       addtableEvent()
+ *       addEventColumn()
+ *
+ *  NdbEventOperation
+ *       getValue()
+ *       getPreValue()
+ *       execute()
+ *       next()
+ *       isConsistent()
+ *       getEventType()
+ *
  */
 
 #include <NdbApi.hpp>

ndb/examples/ndbapi_example2/Makefile → ndb/examples/ndbapi_retries_example/Makefile

-TARGET = ndbapi_example2
-SRCS = ndbapi_example2.cpp
-OBJS = ndbapi_example2.o
+TARGET = ndbapi_retries
+SRCS = ndbapi_retries.cpp
+OBJS = ndbapi_retries.o
 CXX = g++
 CFLAGS = -c -Wall -fno-rtti -fno-exceptions
 DEBUG = 

ndb/examples/ndbapi_example3/ndbapi_example3.cpp → ndb/examples/ndbapi_retries_example/ndbapi_retries.cpp

@@ -15,9 +15,9 @@
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */
 
 // 
-//  ndbapi_example3.cpp: Error handling and transaction retries
+//  ndbapi_retries.cpp: Error handling and transaction retries
 //
-//  Execute ndbapi_example1 to create the table "MYTABLENAME"
+//  Execute ndbapi_simple to create the table "MYTABLENAME"
 //  before executing this program.
 //
 //  There are many ways to program using the NDB API.  In this example

ndb/examples/ndbapi_example1/Makefile → ndb/examples/ndbapi_simple_example/Makefile

-TARGET = ndbapi_example1
+TARGET = ndbapi_simple
 SRCS = $(TARGET).cpp
 OBJS = $(TARGET).o
 CXX = g++

ndb/examples/ndbapi_example1/ndbapi_example1.cpp → ndb/examples/ndbapi_simple_example/ndbapi_simple.cpp

@@ -15,7 +15,7 @@
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */
 
 /* 
- *  ndbapi_example1.cpp: Using synchronous transactions in NDB API
+ *  ndbapi_simple.cpp: Using synchronous transactions in NDB API
  *
  *  Correct output from this program is:
  *

ndb/examples/ndbapi_example4/Makefile → ndb/examples/ndbapi_simple_index_example/Makefile

-TARGET = ndbapi_example4
+TARGET = ndbapi_simple_index
 SRCS = $(TARGET).cpp
 OBJS = $(TARGET).o
 CXX = g++

ndb/examples/ndbapi_example4/ndbapi_example4.cpp → ndb/examples/ndbapi_simple_index_example/ndbapi_simple_index.cpp

@@ -15,7 +15,7 @@
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */
 
 // 
-//  ndbapi_example4.cpp: Using secondary indexes in NDB API
+//  ndbapi_simple_index.cpp: Using secondary indexes in NDB API
 //
 //  Correct output from this program is:
 //

ndb/include/ndbapi/Ndb.hpp

@@ -25,7 +25,7 @@
    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 the database, 
+   - Ndb is the main class, representing 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.
@@ -44,15 +44,15 @@
    The main structure of an application program is as follows:
    -# Construct and connect to a cluster using the Ndb_cluster_connection
       object.
-   -# Construct and initialize Ndb object(s).
-   -# Define and execute transactions using NdbTransaction and Ndb*Operation.
-   -# Delete Ndb objects
-   -# Delete cluster connection
+   -# Construct and initialize Ndb object(s) to connect to a database.
+   -# Define and execute transactions using NdbTransaction.
+   -# Delete Ndb objects.
+   -# Delete cluster connection.
 
    The main structure of a transaction is as follows:
    -# Start transaction (an NdbTransaction)
    -# Add and define operations associated with the transaction using
-      Ndb*Operation
+      NdbOperation, NdbScanOperation, NdbIndexOperation, NdbIndexScanOperation
    -# Execute transaction
 
    The execution can be of two different types, 
@@ -65,8 +65,9 @@
    for later execution.
 
    If the execute is of type <var>Commit</var>, then the transaction is
-   committed, and no further addition or definition of operations 
-   is allowed.
+   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 is allowed.
 
 
    @section secSync                     Synchronous Transactions
@@ -78,14 +79,18 @@
        (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 NdbTransaction::getNdb*Operation() and
-       methods of the Ndb*Operation class.
+    -# Define operations and add them to the transaction, using 
+       NdbTransaction::getNdbOperation(),
+       NdbTransaction::getNdbScanOperation(),
+       NdbTransaction::getNdbIndexOperation(), or
+       NdbTransaction::getNdbIndexScanOperation(),
+       and methods of the respective NdbOperation class.
        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 (using Ndb::closeTransaction()).
   
-   For an example of this process, see the program listing in @ref ndbapi_example1.cpp.
+   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 
@@ -93,9 +98,9 @@
 
    @section secNdbOperations            Operations
 
-   Each NdbTransaction
-   consists of a list of operations which are represented by instances 
-   of Ndb*Operation.
+   Each NdbTransaction consists of a list of operations which are represented 
+   by instances of NdbOperation, NdbScanOperation, NdbIndexOperation, and/or
+   NdbIndexScanOperation.
 
    <h3>Single row operations</h3>
    After the operation is created using NdbTransaction::getNdbOperation()
@@ -105,8 +110,8 @@
    -# 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
@@ -122,12 +127,12 @@
      // 4. Attribute Actions
      MyRecAttr= MyOperation->getValue("ATTR2", NULL);
    @endcode
-   For additional examples of this sort, see @ref ndbapi_example1.cpp.
+   For additional examples of this sort, see @ref ndbapi_simple.cpp.
 
    The second example uses an NdbIndexOperation:
    @code
      // 1. Create
-     MyOperation= MyTransaction->getNdbIndexOperation("MYINDEX", "MYTABLENAME");
+     MyOperation= MyTransaction->getNdbIndexOperation("MYINDEX","MYTABLENAME");
 
      // 2. Define type of operation and lock mode
      MyOperation->readTuple(NdbOperation::LM_Read);
@@ -138,10 +143,11 @@
      // 4. Attribute Actions 
      MyRecAttr = MyOperation->getValue("ATTR2", NULL);
    @endcode
-   Another example of this second type can be found in @ref ndbapi_example4.cpp.
+   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 creation 
-   and use of synchronous transactions.
+   We will 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 types of operations exist:
@@ -162,18 +168,11 @@
    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::getNdb*Operation for each
-         operation.
+         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.
-
-   For NdbOperation::insertTuple it is also allowed to define the
-   search key by using NdbOperation::setValue.
-   The NDB API will automatically detect that it is
-   supposed to use NdbOperation::equal instead. 
-   For NdbOperation::insertTuple it is not necessary to use
-   NdbOperation::setValue on key attributes before other attributes.
+   The search condition is used to select tuples using NdbOperation::equal()
 
    <h4>Step 3: Specify Attribute Actions</h4>
    Now it is time to define which attributes should be read or updated.
@@ -183,21 +182,21 @@
    also possible to use the attribute identity to define the
    attribute.
 
-   NdbOperation::getValue returns an NdbRecAttr object
+   NdbOperation::getValue() returns an NdbRecAttr object
    containing the read value.
    To get the value, there is actually two methods.
    The application can either
    - use its own memory (passed through a pointer aValue) to
-     NdbOperation::getValue, or
+     NdbOperation::getValue(), or
    - receive the attribute value in an NdbRecAttr object allocated
      by the NDB API.
 
-   The NdbRecAttr object is released when Ndb::closeTransaction
+   The NdbRecAttr object is released when Ndb::closeTransaction()
    is called.
    Thus, the application can not reference this object after
-   Ndb::closeTransaction have been called.
+   Ndb::closeTransaction() have been called.
    The result of reading data from an NdbRecAttr object before
-   calling NdbTransaction::execute is undefined.
+   calling NdbTransaction::execute() is undefined.
 
 
    @subsection secScan              Scan Operations 
@@ -214,16 +213,17 @@
    - They can operate on several nodes in parallell
 
    After the operation is created using NdbTransaction::getNdbScanOperation()
-   (or NdbTransaction::getNdbIndexScanOperation()), it is defined in the following 
-   three steps:
+   (or NdbTransaction::getNdbIndexScanOperation()), 
+   it is defined 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 search conditions, using @ref NdbScanFilter and/or 
+      @ref NdbIndexScanOperation::setBound()
    -# Specify attribute actions, using NdbOperation::getValue()
    -# Executing the transaction, using NdbTransaction::execute()
-   -# Iterating through the result set using NdbScanOperation::nextResult
+   -# Iterating through the result set using NdbScanOperation::nextResult()
 
-   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 NdbScanOperation:
    @code
@@ -262,11 +262,14 @@
    @endcode
 
    <h4>Step 1: Define scan operation operation type</h4>
-   Scan operations only support 1 operation, @ref NdbScanOperation::readTuples or @ref NdbIndexScanOperation::readTuples
+   Scan operations only support 1 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::getNdb*ScanOperation for each
-         operation.
+   @note If you want to define multiple scan operations within the same 
+         transaction, then you need to call 
+	 NdbTransaction::getNdbScanOperation() or 
+	 NdbTransaction::getNdbIndexScanOperation() for each operation.
 
    <h4>Step 2: Specify Search Conditions</h4>
    The search condition is used to select tuples.
@@ -288,33 +291,32 @@
    also possible to use the attribute identity to define the
    attribute.
 
-   NdbOperation::getValue returns an NdbRecAttr object
+   NdbOperation::getValue() returns an NdbRecAttr object
    containing the read value.
    To get the value, there is actually two methods.
    The application can either
    - use its own memory (passed through a pointer aValue) to
-     NdbOperation::getValue, or
+     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 can not reference this object after
-   Ndb::closeTransaction have been called.
+   The NdbRecAttr object is released when Ndb::closeTransaction()
+   is called. Thus, the application can not reference this object after
+   Ndb::closeTransaction() have been called.
    The result of reading data from an NdbRecAttr object before
-   calling NdbTransaction::execute is undefined.
+   calling NdbTransaction::execute() is undefined.
 
    <h3> Using Scan to update/delete </h3>
    Scanning can also be used to update/delete rows.
    This is performed by
    -# Scan using exclusive locks, NdbOperation::LM_Exclusive
    -# When iterating through the result set, for each row optionally call 
-      either NdbScanOperation::updateCurrentTuple or 
-      NdbScanOperation::deleteCurrentTuple
-   -# If performing NdbScanOperation::updateCurrentTuple, 
-      set new values on record using ordinary @ref NdbOperation::setValue.
-      NdbOperation::equal should _not_ be called as the primary key is 
-      retreived from the scan.
+      either NdbScanOperation::updateCurrentTuple() or 
+      NdbScanOperation::deleteCurrentTuple()
+   -# If performing NdbScanOperation::updateCurrentTuple(), 
+      set new values on record using ordinary @ref NdbOperation::setValue().
+      NdbOperation::equal() should <em>not</em> be called as the primary 
+      key is retreived from the scan.
 
    @note that the actual update/delete will not be performed until next 
    NdbTransaction::execute (as with single row operations), 
@@ -323,13 +325,16 @@
 
    <h4> Index scans specific features </h4> 
    The following features are available when performing an index scan
-   - Scan subset of table using @ref NdbIndexScanOperation::setBound
-   - Ordering result set ascending or descending, @ref NdbIndexScanOperation::readTuples
-   - When using NdbIndexScanOperation::BoundEQ on distribution key 
-     only fragment containing rows will be scanned.
+   - Scan subset of table using @ref NdbIndexScanOperation::setBound()
+   - Ordering result set ascending or descending, 
+     @ref NdbIndexScanOperation::readTuples()
+   - When using NdbIndexScanOperation::BoundEQ on partition key 
+     only fragments containing rows will be scanned.
    
    Rows are returned unordered unless sorted is set to true.
-   @note When performing sorted scan, parameter parallelism to readTuples will
+
+   @note When performing sorted scan, parameter parallelism to 
+   NdbIndexScanOperation::readTuples() will
    be ignored and max parallelism will be used instead. 
 
    @subsection secScanLocks Lock handling with scans
@@ -339,11 +344,11 @@
 
    But Ndb will only lock a batch of rows per fragment at a time.
    How many rows will be locked per fragment is controlled by the 
-   batch parameter to @ref NdbScanOperation::readTuples.
+   batch parameter to NdbScanOperation::readTuples().
 
    To let the application handle how locks are released 
-   @ref NdbScanOperation::nextResult have a parameter fetch_allow.
-   If NdbScanOperation::nextResult is called with fetch_allow = false, no
+   NdbScanOperation::nextResult() have a parameter fetch_allow.
+   If NdbScanOperation::nextResult() is called with fetch_allow = false, no
    locks may be released as result of the function call. Otherwise the locks
    for the current batch may be released.
 
@@ -376,11 +381,12 @@
 
    One recommended way to handle a transaction failure 
    (i.e. an error is reported) is to:
-   -# Rollback transaction (NdbTransaction::execute with a special parameter)
+   -# Rollback transaction (NdbTransaction::execute() with a special parameter)
    -# Close transaction
    -# Restart transaction (if the error was temporary)
 
-   @note Transaction are not automatically closed when an error occur.
+   @note Transactions are not automatically closed when an error occur. Call
+   Ndb::closeTransaction() to close.
 
    Several errors can occur when a transaction holds multiple 
    operations which are simultaneously executed.
@@ -388,9 +394,9 @@
    objects and query for their NdbError objects to find out what really
    happened.
 
-   NdbTransaction::getNdbErrorOperation returns a reference to the 
+   NdbTransaction::getNdbErrorOperation() returns a reference to the 
    operation causing the latest error.
-   NdbTransaction::getNdbErrorLine delivers the method number of the 
+   NdbTransaction::getNdbErrorLine() delivers the method number of the 
    erroneous method in the operation.
 
    @code
@@ -413,35 +419,35 @@
    Getting errorLine == 0 means that the error occurred when executing the 
    operations.
    Here errorOperation will be a pointer to the theOperation object.
-   NdbTransaction::getNdbError will return the NdbError object 
+   NdbTransaction::getNdbError() will return the NdbError object 
    including holding information about the error.
 
    Since errors could have occurred even when a commit was reported,
-   there is also a special method, NdbTransaction::commitStatus,
+   there is also a special method, NdbTransaction::commitStatus(),
    to check the commit status of the transaction.
 
-*******************************************************************************/
+******************************************************************************/
 
 /**
- * @page ndbapi_example1.cpp ndbapi_example1.cpp
- * @include ndbapi_example1.cpp 
+ * @page ndbapi_simple.cpp ndbapi_simple.cpp
+ * @include ndbapi_simple.cpp 
  */
 
 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
 /**
- * @page ndbapi_example2.cpp ndbapi_example2.cpp
- * @include ndbapi_example2.cpp 
+ * @page ndbapi_async1.cpp ndbapi_async1.cpp
+ * @include ndbapi_async1.cpp 
  */
 #endif
 
 /**
- * @page ndbapi_example3.cpp ndbapi_example3.cpp
- * @include ndbapi_example3.cpp 
+ * @page ndbapi_retries.cpp ndbapi_retries.cpp
+ * @include ndbapi_retries.cpp 
  */
 
 /**
- * @page ndbapi_example4.cpp ndbapi_example4.cpp
- * @include ndbapi_example4.cpp 
+ * @page ndbapi_simple_index.cpp ndbapi_simple_index.cpp
+ * @include ndbapi_simple_index.cpp 
  */
 
 /**
@@ -454,32 +460,14 @@
    @page secAdapt  Adaptive Send Algorithm
 
    At the time of "sending" the transaction 
-   (using NdbTransaction::execute), the transactions 
+   (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
    be transfered to the NDB kernel.
   
-   For each of these "sent" transactions, 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.)
-      
-   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.
-  
-  
-   Since the NDB API is designed as a multi-threaded interface, 
+   The NDB API is designed as a multi-threaded interface and
    it is 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 transfering
@@ -510,14 +498,36 @@
       later releases of NDB Cluster.
       However, to support faster than 10 ms checks, 
       there has to be support from the operating system.
-   -# When calling NdbTransaction::execute synchronously or calling any 
-      of the poll-methods, there is a force parameter that overrides the 
-      adaptive algorithm and forces the send to all nodes.
+   -# When methods that are affected by the adaptive send alorithm,
+      e.g. NdbTransaction::execute(), there is a force parameter 
+      that overrides it forces the send to all nodes.
 
-   @note The times mentioned above are examples.  These might 
+   @note The reasons mentioned above are examples.  These might 
          change in later releases of NDB Cluster.
 */
 
+#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
+/**
+
+   For each of these "sent" transactions, 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.)
+      
+   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.
+*/
+#endif
+
 /**
    @page secConcepts  NDB Cluster Concepts
 
@@ -559,14 +569,17 @@
    
    The application programmer can however hint the NDB API which 
    transaction coordinator to use
-   by providing a <em>distribution key</em> (usually the primary key).
-   By using the primary key as distribution key, 
+   by providing a <em>partition key</em> (usually the primary key).
+   By using the primary key as 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 and then the NDB API will choose a transaction
    coordinator without using the hint.
-   For more information, see NdbDictionary::Column::setDistributionKey.
+   For more information, see NdbDictionary::Column::getPartitionKey(),
+   Ndb::startTransaction().  The application programmer can specify
+   the partition key from SQL by using the construct, 
+   "CREATE TABLE ... ENGINE=NDB PARTITION BY KEY (<attribute list>)".
 
 
    @section secRecordStruct          Record Structure 
@@ -635,7 +648,7 @@
    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 distribution 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.
 */

ndb/include/ndbapi/NdbDictionary.hpp

@@ -56,7 +56,7 @@ typedef struct charset_info_st CHARSET_INFO;
  * -# NdbDictionary::Column for creating table columns
  * -# NdbDictionary::Index for creating secondary indexes
  *
- * See @ref ndbapi_example4.cpp for details of usage.
+ * See @ref ndbapi_simple_index.cpp for details of usage.
  */
 class NdbDictionary {
 public:
@@ -286,14 +286,14 @@ public:
     int getSize() const;
 
     /** 
-     * Check if column is part of distribution key
+     * Check if column is part of partition key
      *
-     * A <em>distribution key</em> is a set of attributes which are used
+     * A <em>partition key</em> is a set of attributes which are used
      * to distribute the tuples onto the NDB nodes.
-     * The distribution key uses the NDB Cluster hashing function.
+     * The partition key uses the NDB Cluster hashing function.
      *
      * An example where this is useful is TPC-C where it might be
-     * good to use the warehouse id and district id as the distribution key. 
+     * good to use the warehouse id and district id as the partition key. 
      * This would place all data for a specific district and warehouse 
      * in the same database node.
      *
@@ -301,9 +301,12 @@ public:
      * will still be used with the hashing algorithm.
      *
      * @return  true then the column is part of 
-     *                 the distribution key.
+     *                 the partition key.
      */
-    bool getDistributionKey() const;
+    bool getPartitionKey() const;
+#ifndef DOXYGEN_SHOULD_SKIP_DEPRECATED
+    inline bool getDistributionKey() const { return getPartitionKey(); };
+#endif
 
     /** @} *******************************************************************/
 
@@ -401,13 +404,17 @@ public:
     void setStripeSize(int size);
 
     /** 
-     * Set distribution key
-     * @see getDistributionKey
+     * Set partition key
+     * @see getPartitionKey
      *
      * @param  enable  If set to true, then the column will be part of 
-     *                 the distribution key.
+     *                 the partition key.
      */
-    void setDistributionKey(bool enable);
+    void setPartitionKey(bool enable);
+#ifndef DOXYGEN_SHOULD_SKIP_DEPRECATED
+    inline void setDistributionKey(bool enable)
+    { setPartitionKey(enable); };
+#endif
 
     /** @} *******************************************************************/
 

ndb/include/ndbapi/NdbError.hpp

@@ -41,7 +41,7 @@
  * The <em>error messages</em> and <em>error details</em> may
  * change without notice.
  * 
- * For example of use, see @ref ndbapi_example3.cpp.
+ * For example of use, see @ref ndbapi_retries.cpp.
  */
 struct NdbError {
   /**

ndb/include/ndbapi/NdbEventOperation.hpp

@@ -46,7 +46,7 @@ class NdbEventOperationImpl;
  * The instance is removed by Ndb::dropEventOperation
  *
  * For more info see:
- * @ref ndbapi_example5.cpp
+ * @ref ndbapi_event.cpp
  *
  * Known limitations:
  *

ndb/include/ndbapi/NdbIndexScanOperation.hpp

@@ -73,7 +73,7 @@ public:
    *
    * For equality, it is better to use BoundEQ instead of the equivalent
    * pair of BoundLE and BoundGE.  This is especially true when table
-   * distribution key is an initial part of the index key.
+   * partition key is an initial part of the index key.
    *
    * The sets of lower and upper bounds must be on initial sequences of
    * index keys.  All but possibly the last bound must be non-strict.

ndb/include/ndbapi/NdbOperation.hpp

@@ -237,10 +237,13 @@ public:
    * use several equals (then all of them must be satisfied for the
    * tuple to be selected).
    *
-   * @note There are 10 versions of NdbOperation::equal with
+   * @note For insertTuple() it is also allowed to define the
+   *       search key by using setValue().
+   *
+   * @note There are 10 versions of equal() with
    *       slightly different parameters.
    *
-   * @note When using NdbOperation::equal with a string (char *) as
+   * @note When using equal() with a string (char *) as
    *       second argument, the string needs to be padded with 
    *       zeros in the following sense:
    *       @code
@@ -249,6 +252,8 @@ public:
    *       NdbOperation->equal("Attr1", buf);
    *       @endcode
    *
+   * 
+   * 
    * @param   anAttrName   Attribute name 
    * @param   aValue       Attribute value.
    * @param   len          Attribute length expressed in bytes.
@@ -328,6 +333,12 @@ public:
    * then the API will assume that the pointer
    * is correct and not bother with checking it.
    *
+   * @note For insertTuple() the NDB API will automatically detect that 
+   *       it is supposed to use equal() instead. 
+   *
+   * @note For insertTuple() it is not necessary to use
+   *       setValue() on key attributes before other attributes.
+   *
    * @note There are 14 versions of NdbOperation::setValue with
    *       slightly different parameters.
    * 
@@ -720,7 +731,7 @@ public:
   void setAbortOption(Int8 ao) { m_abortOption = ao; }
   
   /**
-   * Set/get distribution/partition key
+   * Set/get partition key
    */
   void setPartitionId(Uint32 id);
   void setPartitionHash(Uint32 key);

ndb/include/ndbapi/NdbRecAttr.hpp

@@ -39,7 +39,7 @@ class NdbOperation;
  *   ndbout << MyRecAttr->u_32_value();
  * @endcode
  * For more examples, see 
- * @ref ndbapi_example1.cpp.
+ * @ref ndbapi_simple.cpp.
  *
  * @note The NdbRecAttr object is instantiated with its value when 
  *       NdbTransaction::execute is called.  Before this, the value is 

ndb/include/ndbapi/NdbTransaction.hpp

@@ -76,33 +76,35 @@ enum ExecType {
  * @brief Represents a transaction.
  *
  * A transaction (represented by an NdbTransaction object) 
- * belongs to an Ndb object and is typically created using 
- * Ndb::startTransaction.
+ * belongs to an Ndb object and is created using 
+ * Ndb::startTransaction().
  * A transaction consists of a list of operations 
- * (represented by NdbOperation objects). 
+ * (represented by NdbOperation, NdbScanOperation, NdbIndexOperation,
+ *  and NdbIndexScanOperation objects). 
  * Each operation access exactly one table.
  *
  * After getting the NdbTransaction object, 
- * the first step is to get (allocate) an operation given the table name. 
+ * the first step is to get (allocate) an operation given the table name using
+ * one of the methods getNdbOperation(), getNdbScanOperation(),
+ * getNdbIndexOperation(), or getNdbIndexScanOperation().
  * Then the operation is defined. 
- * Several operations can be defined in parallel on the same 
- * NdbTransaction object. 
- * When all operations are defined, the NdbTransaction::execute
+ * Several operations can be defined on the same 
+ * NdbTransaction object, they will in that case be executed in parallell.
+ * When all operations are defined, the execute()
  * method sends them to the NDB kernel for execution.
  *
- * The NdbTransaction::execute method returns when the NDB kernel has 
+ * The execute() method returns when the NDB kernel has 
  * completed execution of all operations defined before the call to 
- * NdbTransaction::execute. 
- * All allocated operations should be properly defined 
- * before calling NdbTransaction::execute.
+ * execute(). All allocated operations should be properly defined 
+ * before calling execute().
  *
- * A call to NdbTransaction::execute uses one out of three types of execution:
+ * A call to execute() uses one out of three types of execution:
  *  -# ExecType::NoCommit  Executes operations without committing them.
  *  -# ExecType::Commit	   Executes remaining operation and commits the 
  *        	           complete transaction
  *  -# ExecType::Rollback  Rollbacks the entire transaction.
  *
- * NdbTransaction::execute is equipped with an extra error handling parameter 
+ * execute() is equipped with an extra error handling parameter. 
  * There are two alternatives:
  * -# AbortOption::AbortOnError (default).
  *    The transaction is aborted if there are any error during the
@@ -298,7 +300,7 @@ public:
    *        ExecType::Rollback rollbacks the entire transaction.
    * @param callback       A callback method.  This method gets 
    *                        called when the transaction has been 
-   *                        executed.  See @ref ndbapi_example2.cpp 
+   *                        executed.  See @ref ndbapi_async1.cpp 
    *                        for an example on how to specify and use 
    *                        a callback method.
    * @param anyObject       A void pointer.  This pointer is forwarded to the 
@@ -345,6 +347,8 @@ public:
 
   /**
    * Close transaction
+   *
+   * @note Equivalent to to calling Ndb::closeTransaction()
    */
 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
   /**
@@ -366,7 +370,13 @@ public:
    *   Once a transaction has been completed successfully
    *     it can be started again wo/ calling closeTransaction/startTransaction
    *
-   *   Note this method also releases completed operations
+   *  @note This method also releases completed operations
+   *
+   *  @note This method does not close open scans, 
+   *        c.f. NdbScanOperation::close()
+   *
+   *  @note This method can only be called _directly_ after commit
+   *        and only if commit is successful
    */
   int restart();
 #endif
@@ -409,10 +419,7 @@ public:
   Uint64	getTransactionId();
 
   /**
-   * Returns the commit status of the transaction.
-   *
-   * @return  The commit status of the transaction, i.e. one of
-   *          { NotStarted, Started, TimeOut, Committed, Aborted, NeedAbort } 
+   * The commit status of the transaction.
    */
   enum CommitStatusType { 
     NotStarted,                   ///< Transaction not yet started
@@ -422,6 +429,11 @@ public:
     NeedAbort                     ///< <i>Missing explanation</i>
   };
 
+  /**
+   * Get the commit status of the transaction.
+   *
+   * @return  The commit status of the transaction
+   */
   CommitStatusType commitStatus();
 
   /** @} *********************************************************************/
@@ -443,7 +455,7 @@ public:
    * This method is used on the NdbTransaction object to find the
    * NdbOperation causing an error.  
    * To find more information about the
-   * actual error, use method NdbOperation::getNdbError 
+   * actual error, use method NdbOperation::getNdbError()
    * on the returned NdbOperation object.
    *
    * @return The NdbOperation causing the latest error.

ndb/src/ndbapi/NdbDictionary.cpp

@@ -177,12 +177,12 @@ NdbDictionary::Column::getPrimaryKey() const {
 }
 
 void 
-NdbDictionary::Column::setDistributionKey(bool val){
+NdbDictionary::Column::setPartitionKey(bool val){
   m_impl.m_distributionKey = val;
 }
 
 bool 
-NdbDictionary::Column::getDistributionKey() const{
+NdbDictionary::Column::getPartitionKey() const{
   return m_impl.m_distributionKey;
 }