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/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
@@ -248,6 +251,8 @@ public:
    *       strncpy(buf, str, sizeof(buf));
    *       NdbOperation->equal("Attr1", buf);
    *       @endcode
+   *
+   * 
    * 
    * @param   anAttrName   Attribute name 
    * @param   aValue       Attribute value.
@@ -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

@@ -52,7 +52,7 @@ enum AbortOption {
   TryCommit = 0,                ///< <i>Missing explanation</i>
 #endif
   AbortOnError = 0,             ///< Abort transaction on failed operation
-  AO_IgnoreError = 2               ///< Transaction continues on failed operation
+  AO_IgnoreError = 2            ///< Transaction continues on failed operation
 };
   
 typedef AbortOption CommitType;
@@ -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
- * method sends them to the NDB kernel for execution. 
+ * 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;
 }