2.3.16.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 connection string.

Prior to MySQL Cluster 7.3.8 and MySQL Cluster NDB 7.4.3, it
was possible to delete the
Ndb_cluster_connection used to create a
given instance of Ndb without first
deleting the dependent Ndb object. (Bug
#19999242)

catalogName is an optional
parameter providing a namespace for the tables and indexes
created in any connection from the
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.16.1.2. Ndb::closeTransaction()

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.

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.15, “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.

Previously, it was assumed that the memory returned by the
malloc() call would always be suitably
aligned, which is not always the case. Beginning with
MySQL Cluster NDB versions 7.0.38, 7.1.27, 7.2.13, and
7.3.2, when malloc() provides a buffer
to this method, the buffer is explicitly aligned after it
is allocated, and before it is actually used. (Bug
#16484617)

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.16.1.4. Ndb::createEventOperation()

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

Note

NDB API event subscriptions do not persist after a MySQL
Cluster has been restored using
ndb_restore; in such cases, all of the
subscriptions must be recreated explicitly.

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.

2.3.16.1.7. 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.16.1.8. 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.16.1.9. Ndb::getGCIEventOperations()

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.

This method is deprecated in MySQL Cluster NDB 7.4.3, and is
subject to removal in a future release. In MySQL Cluster NDB
7.4.3 and later, you should use
getNextEventOpInEpoch2()
instead.

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. .

2.3.16.1.10. Ndb::get_eventbuf_max_alloc()

Description.
Gets the maximum memory, in bytes, that can be used for the
event buffer. This is the same as reading the value of the
ndb_eventbuffer_max_alloc
system variable in the MySQL Server.

2.3.16.1.13. Ndb::getHighestQueuedEpoch()

Added in MySQL Cluster NDB 7.4.3, this method supersedes
getLatestGCI(), which is
now deprecated and subject to removal in a future MySQL Cluster
release.

Signature.

Uint64 getHighestQueuedEpoch
(
void
)

Parameters. None.

Return value.
The most recent epoch number, an integer.

2.3.16.1.14. Ndb::getLatestGCI()

Description.
Gets the index for the most recent global checkpoint.

This method is deprecated in MySQL Cluster NDB 7.4.3, and is
subject to removal in a future release. In MySQL Cluster NDB
7.4.3 and later, you should use
getHighestQueuedEpoch()
instead.

Signature.

Uint64 getLatestGCI
(
void
)

Parameters. None.

Return value.
The most recent GCI, an integer.

2.3.16.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 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”.

2.3.16.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 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:

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.16.1.17. Ndb::getNdbObjectName()

Description.
If a name was set for the Ndb object prior
to its initialization, you can retrieve it using this method.
Used for debugging.

Signature.

const char* getNdbObjectName
(
void
) const

Parameters. None.

Return value.
The Ndb object name, if one has been set
using setNdbObjectName().
Otherwise, this method returns 0.

2.3.16.1.18. Ndb::getNextEventOpInEpoch2()

Description.
Iterates over individual event operations making up the
current global checkpoint. Use following
nextEvent2() to obtain
summary information for the epoch, such as a listing of all
tables, before processing event data. * * Set *iter=0 to
start. Returns NULL when no more. If event_types * is not
NULL, it returns bitmask of received event types. */

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

Signature.

Uint32 getReference
(
void
)

Parameters. None.

Return value.
A 32-bit unsigned integer.

2.3.16.1.20. Ndb::init()

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.

2.3.16.1.21. Ndb::isConsistent()

Description.
Check if all events are consistent. 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.

Parameters.
A reference to a global checkpoint index. This is the first
inconsistent GCI found, if any.

Return value. true if all events are consistent.

2.3.16.1.22. Ndb::isConsistentGCI()

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 given GCI are
consistent.

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

2.3.16.1.23. Ndb::nextEvent()

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

This method is deprecated in MySQL Cluster NDB 7.4.3, and is
subject to removal in a future release. In MySQL Cluster NDB
7.4.3 and later, you should use
nextEvent2() instead.

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.

Beginning with MySQL Cluster NDB 7.1.32, MySQL Cluster NDB
7.2.17, and MySQL Cluster NDB 7.3.6, this method clears
inconsistent data events from the event queue when processing
them. In order to able to clear all such events in these and
later versions, applications must call this method even in cases
when pollEvents() has
already returned 0. (Bug #18716991)

2.3.16.1.24. Ndb::nextEvent2()

Description.
Returns the event operation associated with the data dequeued
from the event queue. This should be called repeatedly after
pollEvents2() populates
the queue, until the event queue is empty.

Added in MySQL Cluster NDB 7.4.3, this method supersedes
nextEvent(), which is now
deprecated and subject to removal in a future MySQL Cluster
release.

After calling this method, use
NdbEventOperation::getEpoch()
to determine the epoch, then check the type of the returned
event data using
NdbEventOperation::getEventType2().
Handling must be provided for all exceptional
TableEvent types,
including TE_EMPTY,
TE_INCONSISTENT, and
TE_OUT_OF_MEMORY (also introduced in MySQL
Cluster NDB 7.4.3). No other
NdbEventOperation methods than
the two named here should be called for an exceptional epoch.
Returning empty epochs (TE_EMPTY) may flood
applications when data nodes are idle. If this is not desirable,
applications should filter out any empty epochs.

Signature.

NdbEventOperation* nextEvent2
(
void
)

Parameters.
None.

Return value.
This method returns an
NdbEventOperation object
representing the next event in an event queue, if there is
such an event. If there is no event in the queue, it returns
NULL instead.

2.3.16.1.25. 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.21, “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.

This method is deprecated in MySQL Cluster NDB 7.4.3, and is
subject to removal in a future release. In MySQL Cluster NDB
7.4.3 and later, you should use
pollEvents2() instead.

Signature.

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

Parameters.
This method takes the two parameters listed 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.16.1.26. Ndb::pollEvents2()

Description.
Waits for an event to occur. Returns as soon as any event data
is available. This method also moves an epoch's complete
event data to the event queue.

Added in MySQL Cluster NDB 7.4.3, this method supersedes
pollEvents(), which is now
deprecated and subject to removal in a future MySQL Cluster
release.

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 highest queued epoch. Normally, this may
safely be permitted to assume its default value, which is
0. If this value is not
NULL and new event data is available in
the event queue, it is set to the highest epoch found in the
available event data.

Return value. pollEvents2() returns an integer whose
value can 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.16.1.27. 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.16.1.28. Ndb::setDatabaseSchemaName()

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.

2.3.16.1.29. Ndb::set_eventbuf_max_alloc()

Description.
Sets the maximum memory, in bytes, that can be used for the
event buffer. This has the same effect as setting the value of
the ndb_eventbuffer_max_alloc
system variable in the MySQL Server.

Parameters.
The percentage (pct) of event
buffer memory that must be present. Valid range is 1 to 99
inclusive.

Return value.
The value that was set.

2.3.16.1.31. Ndb::setNdbObjectName()

Description.
Starting with MySQL Cluster NDB 7.1.32, MySQL Cluster NDB
7.2.17, and MySQL Cluster NDB 7.3.6, you can set an arbitrary,
human-readable name to identify an Ndb
object for debugging purposes. This name can then be retrieved
using getNdbObjectName().
(Bug #18419907) This must be done prior to calling
init() for this object;
trying to set a name after initialization fails with an error.

You can set a name only once for a given Ndb
object; subsequent attempts after the name has already been set
fail with an error.

Signature.

int setNdbObjectName
(
const char* name
)

Parameters.
A name that is intended to be
human-readable.

Return value.
0 on success.

2.3.16.1.32. 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 makes it possible for 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.

table: A pointer to a
Table object. 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.

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;

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

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.