Commit 29b3edb9 authored by unknown's avatar unknown
Browse files

mgmapi.h, Ndb.hpp: Various fixes in Doxygen comments 


ndb/include/mgmapi/mgmapi.h:
  Minor fixes in Doxygen comments.
ndb/include/ndbapi/Ndb.hpp:
  Spelling/grammar/stylistic fixes in Doxygen comments.
parent 708411bb

ndb/include/mgmapi/mgmapi.h

+1 −1
Original line number Diff line number Diff line
@@ -38,7 +38,7 @@ 
 *  -# An integer value.

 *     A value of <b>-1</b> indicates an error.

 *  -# A pointer value.  A <var>NULL</var> value indicates an error;

 *     Otherwise, the return value must be <code>free()</code>ed by the user of the MGM API.

 *     otherwise, the return value must be freed by the user of the MGM API.

 *

 * Error conditions can be identified by using the appropriate

 * error-reporting functions.

ndb/include/ndbapi/Ndb.hpp

+64 −56
Original line number Diff line number Diff line
@@ -23,76 +23,76 @@ 
   The <em>NDB API</em> is a MySQL Cluster application interface 

   that implements transactions.

   The NDB API consists of the following fundamental classes:

   - Ndb_cluster_connection class representing a connection to a cluster, 

   - Ndb is the main class representing the database, 

   - NdbTransaction represents a transaction, 

   - NdbOperation represents a operation using primary key,

   - NdbScanOperation represents a operation performing a full table scan.

   - NdbIndexOperation represents a operation using a unique hash index,

   - NdbIndexScanOperation represents a operation performing a scan using

   - <code>Ndb_cluster_connection</code>, representing a connection to a cluster, 

   - <code>Ndb</code> is the main class, representing the database, 

   - <code>NdbTransaction</code> represents a transaction, 

   - <code>NdbOperation</code> represents an operation using a primary key,

   - <code>NdbScanOperation</code> represents an operation performing a full table scan.

   - <code>NdbIndexOperation</code> represents an operation using a unique hash index,

   - <code>NdbIndexScanOperation</code> represents an operation performing a scan using

     an ordered index,

   - NdbRecAttr represents the value of an attribute, and

   - NdbDictionary represents meta information about tables and attributes.

   - NdbError contains a specification of an error.

   - <code>NdbRecAttr</code> represents an attribute value

   - <code>NdbDictionary</code> represents meta information about tables and attributes.

   - <code>NdbError</code> contains the specification for an error.

   There are also some auxiliary classes.

     

   The main structure of an application program is as follows:

   -# Construct and connect to a cluster using the Ndb_cluster_connection

   -# Construct and connect to a cluster using the <code>Ndb_cluster_connection</code>

      object.

   -# Construct and initialize Ndb object(s).

   -# Define and execute transactions using NdbTransaction and Ndb*Operation.

   -# Delete Ndb objects

   -# Delete connection to cluster

   -# Construct and initialize <code>Ndb</code> object(s).

   -# Define and execute transactions using <code>NdbTransaction</code> and <code>Ndb*Operation</code>.

   -# Delete <code>Ndb</code> objects

   -# Delete cluster connection



   The main structure of a transaction is as follows:

   -# Start transaction, a NdbTransaction

   -# Add and define operations (associated with the transaction),

      Ndb*Operation

   -# Start transaction (an <code>NdbTransaction</code>)

   -# Add and define operations associated with the transaction using

      <code>Ndb*Operation</code>

   -# Execute transaction



   The execute can be of two different types, 

   <em>Commit</em> or <em>NoCommit</em>.

   The execution can be of two different types, 

   <var>Commit</var> or <var>NoCommit</var>.

*/

#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL

/**

   (The execute can also be divided into three 

   steps: prepare, send, and poll to get asynchronous

   (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

/** 

   If the execute is of type NoCommit, 

   If the execution is of type <var>NoCommit</var>, 

   then the application program executes part of a transaction,

   but without committing the transaction.

   After a NoCommit type of execute, the program can continue 

   After executing a <var>NoCommit</var> transaction, the program can continue 

   to add and define more operations to the transaction

   for later execution.



   If the execute is of type Commit, then the transaction is

   committed and no further adding and defining of operations 

   If the execute is of type <var>Commit</var>, then the transaction is

   committed, and no further addition or definition of operations 

   is allowed.





   @section secSync                     Synchronous Transactions

  

   Synchronous transactions are defined and executed in the following way.

   Synchronous transactions are defined and executed as follows:

  

    -# Start (create) transaction (the transaction will be 

       referred to by an NdbTransaction object, 

       typically created by Ndb::startTransaction).

       At this step the transaction is being defined.

       It is not yet sent to the NDB kernel.

    -# Add and define operations to the transaction 

       (using NdbTransaction::getNdb*Operation and

       methods from class Ndb*Operation).

       The transaction is still not sent to the NDB kernel.

    -# Execute the transaction (using NdbTransaction::execute).

    -# Close the transaction (using Ndb::closeTransaction).

    -# Start (create) the transaction, which is

       referenced by an <code>NdbTransaction</code> object 

       (typically created using <code>Ndb::startTransaction()</code>).

       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 <code>NdbTransaction::getNdb*Operation()</code> and

       methods of the <code>Ndb*Operation</code> class.

       Note that the transaction has still not yet been sent to the NDB kernel.

    -# Execute the transaction, using the <code>NdbTransaction::execute()</code> method.

    -# Close the transaction (using <code>Ndb::closeTransaction()</code>).

  

   See example program in section @ref ndbapi_example1.cpp.

   For an example of this process, see the program listing in @ref ndbapi_example1.cpp.



   To execute several parallel synchronous transactions, one can either 

   use multiple Ndb objects in several threads or start multiple 

   use multiple <code>Ndb</code> objects in several threads, or start multiple 

   applications programs.  

*/

#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
@@ -104,8 +104,9 @@ 
/**  

   @section secNdbOperations            Operations



   Each transaction (NdbTransaction object) consist of a list of 

   operations (Ndb*Operation objects).

   Each <code>NdbTransaction</code> (that is, a transaction) 

   consists of a list of operations which are represented by instances 

   of <code>Ndb*Operation</code>.

*/

#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL

/**
@@ -116,17 +117,17 @@ 
#endif

/**

   <h3>Single row operations</h3>

   After the operation is created using NdbTransaction::getNdbOperation

   (or NdbTransaction::getNdbIndexOperation),

   it is defined in the following three steps:

   -# Defining standard operation type

      (e.g. using NdbOperation::readTuple)

   -# Specifying search conditions 

      (e.g. using NdbOperation::equal)

   -# Specify attribute actions 

      (e.g. using NdbOperation::getValue)



   Example code (using an NdbOperation and excluding error handling):

   After the operation is created using <code>NdbTransaction::getNdbOperation()</code>

   (or <code>NdbTransaction::getNdbIndexOperation()</code>), it is defined in the following 

   three steps:

   -# Define the standard operation type, using <code>NdbOperation::readTuple()</code>

   -# Specify search conditions, using <code>NdbOperation::equal()</code>

   -# Specify attribute actions, using <code>NdbOperation::getValue()</code>



   Here are two brief examples illustrating this process. For the sake of brevity, 

   we omit error-handling.

   

   This first example uses an <code>NdbOperation</code>:

   @code

     // 1. Create

     MyOperation= MyTransaction->getNdbOperation("MYTABLENAME");
@@ -140,10 +141,10 @@ 
     // 4. Attribute Actions

     MyRecAttr= MyOperation->getValue("ATTR2", NULL);

   @endcode

   For more examples, see @ref ndbapi_example1.cpp and 

   For additional examples of this sort, see @ref ndbapi_example1.cpp and 

   @ref ndbapi_example2.cpp.



   Example code (using an NdbIndexOperation and excluding error handling):

   The second example uses an <code>NdbIndexOperation</code>:

   @code

     // 1. Create

     MyOperation= MyTransaction->getNdbIndexOperation("MYINDEX", "MYTABLENAME");
@@ -157,9 +158,16 @@ 
     // 4. Attribute Actions 

     MyRecAttr = MyOperation->getValue("ATTR2", NULL);

   @endcode

   For more examples, see @ref ndbapi_example4.cpp.

   Another example of this second type can be found in @ref ndbapi_example4.cpp.



   We will now discuss in somewhat greater detail each step involved in the creation 

   and use of synchronous transactions.



*/



  //  Edit stop point - JS, 20041228 0425+1000



/**

   <h4>Step 1: Define single row operation type</h4>

   The following types of operations exist:

    -# NdbOperation::insertTuple :