Description.  This creates an instance of Ndb, which represents a connection to the MySQL Cluster. All NDB API applications should begin with the creation of at least one Ndb object. This requires the creation of at least one instance of Ndb_cluster_connection, which serves as a container for a cluster connectstring.

Signature. 

Ndb
    (
      Ndb_cluster_connection* ndb_cluster_connection,
      const char*                    catalogName = "",
      const char*                    schemaName = "def"
    )

Parameters.  The Ndb class constructor can take up to 3 parameters, of which only the first is required:

Return value.  An Ndb object.

~Ndb() (Class Destructor).  The destructor for the Ndb class should be called in order to terminate an instance of Ndb. It requires no arguments, nor any special handling.

Description.  This is one of two NDB API methods provided for closing a transaction (the other being NdbTransaction::close()). You must call one of these two methods to close the transaction once it has been completed, whether or not the transaction succeeded.

Signature. 

void closeTransaction
    (
      NdbTransaction *transaction
    )

Parameters.  This method takes a single argument, a pointer to the NdbTransaction to be closed.

Return value.  N/A.

Description.  This method can be used to compute a distribution hash value, given a table and its keys.

Signature. 

static int computeHash
    (
      Uint32*                     hashvalueptr,
      const NdbDictionary::Table* table,
      const struct Key_part_ptr*  keyData,
      void*                       xfrmbuf = 0,
      Uint32                      xfrmbuflen = 0
    )

Parameters.  This method takes the following parameters:

Return value.  0 on success, an error code on failure. (If the method call succeeds, the computed hash value is made available via hashvalueptr.)

Description.  This method creates a subscription to a database event.

Signature. 

NdbEventOperation* createEventOperation
    (
      const char *eventName
    )

Parameters.  This method takes a single argument, the unique eventName identifying the event to which you wish to subscribe.

Return value.  A pointer to an NdbEventOperation object (or NULL, in the event of failure). See Section 2.3.19, “The NdbEventOperation Class”.

Description.  This method drops a subscription to a database event represented by an NdbEventOperation object.

Signature. 

int dropEventOperation
    (
      NdbEventOperation *eventOp
    )

Parameters.  This method requires a single input parameter, a pointer to an instance of NdbEventOperation.

Return value.  0 on success; any other result indicates failure.

Description.  This method is used to obtain an object for retrieving or manipulating database schema information. This Dictionary object contains meta-information about all tables in the cluster.

Signature. 

NdbDictionary::Dictionary* getDictionary
    (
      void
    ) const

Parameters.  None.

Return value.  An instance of the Dictionary class.

Description.  This method can be used to obtain the name of the current database.

Signature. 

const char* getDatabaseName
    (
      void
    )

Parameters.  None.

Return value.  The name of the current database.

Description.  This method can be used to obtain the current database schema name.

Signature. 

const char* getDatabaseSchemaName
    (
      void
    )

Parameters.  None.

Return value.  The name of the current database schema.

Description.  Iterates over distinct event operations which are part of the current GCI, becoming valid after calling nextEvent(). You can use this method to obtain summary information for the epoch (such as a list of all tables) before processing the event data.

Signature. 

const NdbEventOperation* getGCIEventOperations
    (
      Uint32* iter, 
      Uint32* event_types
    )

Parameters.  An iterator and a mask of event types. Set *iter=0 to start.

Return value.  The next event operation; returns NULL when there are no more event operations. If event_types is not NULL, then after calling the method it contains a bitmask of the event types received. .

Description.  This method provides you with two different ways to obtain an NdbError object representing an error condition. For more detailed information about error handling in the NDB API, see Chapter 7, MySQL Cluster API Errors.

Signature.  The getNdbError() method actually has two variants.

The first of these simply gets the most recent error to have occurred:

const NdbError& getNdbError
    (
      void
    )

The second variant returns the error corresponding to a given error code:

const NdbError& getNdbError
    (
      int errorCode
    )

Regardless of which version of the method is used, the NdbError object returned persists until the next NDB API method is invoked.

Parameters.  To obtain the most recent error, simply call getNdbError() without any parameters. To obtain the error matching a specific errorCode, invoke the method passing the code (an int) to it as a parameter. For a listing of NDB API error codes and corresponding error messages, see Section 7.2, “NDB API Errors and Error Handling”.

Return value.  An NdbError object containing information about the error, including its type and, where applicable, contextual information as to how the error arose. See Section 2.3.18, “The NdbError Structure”, for details.

Description.  This method, introduced in MySQL Cluster NDB 6.2.19, MySQL Cluster NDB 6.3.29, and MySQL Cluster NDB 7.0.10, provides an easier and safer way to access any extra information about an error. Formerly, it was necessary to read these extra details from the NdbError object's details property, which is now deprecated in favor of getNdbErrorDetail() (Bug #48851). This method enables storage of such details in a user-supplied buffer, returning a pointer to the beginning of this buffer. In the event that the string containing the details exceeds the length of the buffer, it is truncated to fit.

getErrorDetail() makes it much simpler to determine the source of an error than reading NdbError.details, because this method provides the information in the form of a string. For example, in the case of a unique constraint violation (error 893), this string supplies the fully qualified name of the index where the problem originated, in the format database-name/schema-name/table-name/index-name, (NdbError.details, on the other hand, supplies only an index ID, and it is often not readily apparent to which table this index belongs.) Regardless of the type of error and details concerning this error, the string retrieved by getErrorDetail() is always null-terminated.

Signature.  The getNdbErrorDetail() method has the following signature:

const char* getNdbErrorDetail
            (
              const NdbError& error,
              char*           buffer,
              Uint32          bufferLength
            ) const

Parameters.  To obtain detailed information about an error, call getNdbErrorDetail() with a reference to the corresponding NdbError object, a buffer, and the length of this buffer (expressed as an unsigned 32-bit integer).

Return value.  When extra details about the error are available, this method returns a pointer to the beginning of the buffer supplied. As stated previously, if the string containing the details is longer than bufferLength, the string is truncated to fit. In the event that no addition details are available, getNdbErrorDetail() returns NULL.

Description.  This method can be used to obtain a reference to a given Ndb object. This is the same value that is returned for a given operation corresponding to this object in the output of DUMP 2350. (See Section 8.2.3.9, “DUMP 2350”, for an example.)

Signature. 

Uint32 getReference
    (
      void
    )

Parameters.  None.

Return value.  A 32-bit unsigned integer.

Description.  This method is used to initialize an Ndb object.

Signature. 

int init
    (
      int maxNoOfTransactions = 4
    )

Parameters.  The init() method takes a single parameter maxNoOfTransactions of type integer. This parameter specifies the maximum number of parallel NdbTransaction objects that can be handled by this instance of Ndb. The maximum permitted value for maxNoOfTransactions is 1024; if not specified, it defaults to 4.

Return value.  This method returns an int, which can be either of the following two values:

Description.  If a node failure occurs when resources are exhausted, events may be lost and the delivered event data might thus be incomplete. This method makes it possible to determine if this is the case by checking whether all events in a GCI are consistent.

Signature. 

bool isConsistentGCI
    (
      Uint64 gci
    )

Parameters.  A global checkpoint index (or a reference to one)..

Return value.  true if GCI is consistent; false indicates that the GCI may be possible inconsistent.

Description.  Returns the next event operation having data from a subscription queue.

Signature. 

NdbEventOperation* nextEvent
    (
      void
    )

Parameters.  None.

Return value.  This method returns an NdbEventOperation object representing the next event in a subscription queue, if there is such an event. If there is no event in the queue, it returns NULL instead. (See Section 2.3.19, “The NdbEventOperation Class”.)

Description.  This method waits for a GCP to complete. It is used to determine whether any events are available in the subscription queue.

Beginning with MySQL Cluster NDB 6.2.5, this method waits for the next epoch, rather than the next GCP. See Section 2.3.19, “The NdbEventOperation Class”, for more information about the differences in event handling for this and later MySQL Cluster NDB 6.X and 7.X releases. releases.

Signature. 

int pollEvents
    (
      int     maxTimeToWait,
      Uint64* latestGCI = 0
    )

Parameters.  This method takes the two parameters listed here:

Return value.  pollEvents() returns a value of type int, which may be interpreted as follows:

Description.  This method is used to set the name of the current database.

Signature. 

void setDatabaseName
    (
      const char *databaseName
    )

Parameters.  setDatabaseName() takes a single, required parameter, the name of the new database to be set as the current database.

Return value.  N/A.

Description.  This method sets the name of the current database schema.

Signature. 

void setDatabaseSchemaName
    (
      const char *databaseSchemaName
    )

Parameters.  The name of the database schema.

Return value.  N/A.

Description.  This method is used to begin a new transaction. There are three variants, the simplest of these using a table and a partition key or partition ID to specify the transaction coordinator (TC). The third variant makes it possible for you to specify the TC by means of a pointer to the data of the key.

Signature. 

NdbTransaction* startTransaction
    (
      const NdbDictionary::Table* table = 0,
      const char* keyData = 0,
      Uint32* keyLen = 0
    )

Parameters.  This method takes the following three parameters:

Distribution-aware forms of startTransaction().  Beginning with MySQL Cluster NDB 6.1.4, it is possible to employ distribution awareness with this method; that is, to suggest which node should act as the transaction coordinator.

Signature. 

NdbTransaction* startTransaction
    (
      const NdbDictionary::Table* table,
      const struct Key_part_ptr*  keyData,
      void*                       xfrmbuf = 0,
      Uint32                      xfrmbuflen = 0
    )

Parameters.  When specifying the transaction coordinator, this method takes the four parameters listed here:

If xfrmbuf is NULL (the default), then a call to malloc() or free() is made automatically, as appropriate. startTransaction() fails if xfrmbuf is not NULL and xfrmbuflen is too small.

Example.  Suppose that the table's partition key is a single BIGINT column. Then you would declare the distribution key array as shown here:

Key_part_ptr distkey[2];

The value of the distribution key would be defined as shown here:

unsigned long long distkeyValue= 23;

The pointer to the distribution key array would be set as follows:

distkey[0].ptr= (const void*) &distkeyValue;

The length of this pointer would be set accordingly:

distkey[0].len= sizeof(distkeyValue);

The distribution key array must terminate with a NULL element. This is necessary to avoid to having an additional parameter providing the number of columns in the distribution key:

distkey[1].ptr= NULL;
distkey[1].len= NULL;

Setting the buffer to NULL permits startTransaction() to allocate and free memory automatically:

xfrmbuf= NULL;
xfrmbuflen= 0;

Now, when you start the transaction, you can access the node that contains the desired information directly.

In MySQL Cluster NDB 6.2 and later, another distribution-aware version of this method is available. This variant makes it possible for you to specify a table and partition (using the partition ID) as a hint for selecting the transaction coordinator, and is defined as shown here:

NdbTransaction* startTransaction
    (
      const NdbDictionary::Table* table,
      Uint32 partitionId
    )

In the event that the cluster has the same number of data nodes as it has replicas, specifying the transaction coordinator gains no improvement in performance, since each data node contains the entire database. However, where the number of data nodes is greater than the number of replicas (for example, where NoOfReplicas is set equal to 2 in a cluster with 4 data nodes), you should see a marked improvement in performance by using the distribution-aware version of this method.

It is still possible to use this method as before, without specifying the transaction coordinator. In either case, you must still explicitly close the transaction, whether or not the call to startTransaction() was successful.

Return value.  On success, an NdbTransaction object. In the event of failure, NULL is returned.