Skip navigation links
2.3.9 The NdbBlob Class »
Section Navigation      [Toggle]

2.3.8.1. Ndb Methods

[+/-]

2.3.8.1.1. Ndb Class Constructor
2.3.8.1.2. Ndb::init()
2.3.8.1.3. Ndb::getDictionary()
2.3.8.1.4. Ndb::getDatabaseName()
2.3.8.1.5. Ndb::setDatabaseName()
2.3.8.1.6. Ndb::getDatabaseSchemaName()
2.3.8.1.7. Ndb::setDatabaseSchemaName()
2.3.8.1.8. Ndb::startTransaction()
2.3.8.1.9. Ndb::closeTransaction()
2.3.8.1.10. Ndb::computeHash()
2.3.8.1.11. Ndb::createEventOperation
2.3.8.1.12. Ndb::dropEventOperation()
2.3.8.1.13. Ndb::pollEvents()
2.3.8.1.14. Ndb::nextEvent()
2.3.8.1.15. Ndb::getNdbError()
2.3.8.1.16. Ndb::getNdbErrorDetail()
2.3.8.1.17. Ndb::getReference()

Abstract

The sections that follow discuss the public methods of the Ndb class.

2.3.8.1.1. Ndb Class Constructor

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:

  • ndb_cluster_connection is an instance of Ndb_cluster_connection, which represents a cluster connectstring. (See Section 2.3.24, “The Ndb_cluster_connection Class”.)

  • catalogName is an optional parameter providing a namespace for the tables and indexes created in any connection from the Ndb object.

    This is equivalent to what mysqld considers “the database”.

    The default value for this parameter is an empty string.

  • The optional schemaName provides an additional namespace for the tables and indexes created in a given catalog.

    The default value for this parameter is the string “def”.

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.

2.3.8.1.2. Ndb::init()

Description.  This method is used to initialise 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.

Note

Each scan or index operation uses an extra NdbTransaction object. See Section 2.3.19, “The NdbTransaction Class”.

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

  • 0: indicates that the Ndb object was initialised successfully.

  • -1: indicates failure.

2.3.8.1.3. Ndb::getDictionary()

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.

Note

The dictionary returned by this method operates independently of any transaction. See Section 2.3.3, “The Dictionary Class”, for more information.

Signature.  

NdbDictionary::Dictionary* getDictionary
    (
      void
    ) const

Parameters.  None.

Return value.  An instance of the Dictionary class.

2.3.8.1.4. Ndb::getDatabaseName()

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.

2.3.8.1.5. Ndb::setDatabaseName()

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.

2.3.8.1.6. Ndb::getDatabaseSchemaName()

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.

2.3.8.1.7. Ndb::setDatabaseSchemaName()

Description.  This method allows you to set the name of the current database schema.

Signature.  

void setDatabaseSchemaName
    (
      const char *databaseSchemaName
    )

Parameters.  The name of the database schema.

Return value.  N/A.

2.3.8.1.8. Ndb::startTransaction()

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 allows you to specify the TC by means of a pointer to the data of the key.

Important

When the transaction is completed it must be closed using NdbTransaction::close() or Ndb::closeTransaction(). Failure to do so aborts the transaction. This must be done regardless of the transaction's final outcome, even if it fails due to an error.

See Section 2.3.8.1.9, “Ndb::closeTransaction()”, and Section 2.3.19.2.7, “NdbTransaction::close()”.

Signature.  

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

Parameters.  This method takes three parameters, as follows:

  • table: A pointer to a Table object. (See Section 2.3.21, “The Table Class”.) This is used to determine on which node the transaction coordinator should run.

  • keyData: A pointer to a partition key corresponding to table.

  • keyLen: The length of the partition key, expressed in bytes.

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 four parameters:

  • A pointer to a table (NdbDictionary::Table object) used for deciding which node should act as the transaction coordinator.

  • A null-terminated array of pointers to the values of the distribution key columns. The length of the key part is read from metadata and checked against the passed value.

    A Key_part_ptr is defined as shown in Section 2.3.30, “The Key_part_ptr Structure”.

  • A pointer to a temporary buffer, used to calculate the hash value.

  • The length of the buffer.

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 allows startTransaction() to allocate and free memory automatically: 

xfrmbuf= NULL;
xfrmbuflen= 0;

Note

You can also specify a buffer to save having to make explicit malloc() and free() calls, but calculating an appropriate size for this buffer is not a simple matter; if the buffer is not NULL but its length is too short, then the startTransaction() call fails. However, if you choose to specify the buffer, 1 MB is usually a sufficient size.

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 allows 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 (see Section 2.3.19, “The NdbTransaction Class”). In the event of failure, NULL is returned.

2.3.8.1.9. Ndb::closeTransaction()

Description.  This is one of two NDB API methods provided for closing a transaction (the other being NdbTransaction::close() — see Section 2.3.19.2.7, “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.

Important

If the transaction has not yet been committed, it is aborted when this method is called. See Section 2.3.8.1.8, “Ndb::startTransaction()”.

Signature.  

void closeTransaction
    (
      NdbTransaction *transaction
    )

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

Return value.  N/A.

2.3.8.1.10. Ndb::computeHash()

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

Important

computeHash() can be used onlyt for tables that use native NDB partitioning.

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:

  • If the method call id successful, hashvalueptr is set to the computed hash value.

  • A pointer to a table (see Section 2.3.21, “The Table Class”).

  • keyData is a null-terminated array of pointers to the key parts that are part of the table's distribution key. The length of each key part is read from metadata and checked against the passed value (see Section 2.3.30, “The Key_part_ptr Structure”).

  • xfrmbuf is a pointer to temporary buffer used to calculate the hash value.

  • xfrmbuflen is the length of this buffer.

    Note

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

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

2.3.8.1.11. Ndb::createEventOperation

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.11, “The NdbEventOperation Class”.

2.3.8.1.12. Ndb::dropEventOperation()

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.

2.3.8.1.13. Ndb::pollEvents()

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.11, “The NdbEventOperation Class”, for more information about the differences in event handling for this and later MySQL Cluster NDB 6.2.x releases.

Signature.  

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

Parameters.  This method takes two parameters, as shown here:

  • The maximum time to wait, in milliseconds, before “giving up” and reporting that no events were available (that is, before the method automatically returns 0).

  • The index of the most recent global checkpoint. Normally, this may safely be permitted to assume its default value, which is 0.

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

  • > 0: There are events available in the queue.

  • 0: There are no events available.

  • < 0: Indicates failure (possible error).

2.3.8.1.14. Ndb::nextEvent()

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.11, “The NdbEventOperation Class”.)

2.3.8.1.15. Ndb::getNdbError()

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 5, 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 5.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.31, “The NdbError Structure”, for details.

2.3.8.1.16. Ndb::getNdbErrorDetail()

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 allows you to store 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.

2.3.8.1.17. Ndb::getReference()

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 6.2.3.9, “DUMP 2350”, for an example.)

Signature.  

Uint32 getReference
    (
      void
    )

Parameters.  None.