Chapter 3. NDB API CLASSES

Description of the purpose of the class in the API.
A diagram of the class showing its public members and types.
The sections of this covering the NdbDictionary and NdbOperation classes also include entity-relationship diagrams showing the hierarchy of inner classes, subclasses, and public types descending from them.
Listings of all public members, including descriptions of all method parameters and types.

3.1. The `Ndb` Class

3.1.1. Ndb Class Methods

Abstract

This class represents the NDB kernel; it is the primary class of the NDB API.

Description. Any non-trivial NDB API program makes use of at least one instance of Ndb. By using several Ndb objects, it is possible to implement a multi-threaded application. You should remember that one Ndb object cannot be shared between threads; however, it is possible for a single thread to use multiple Ndb objects. A single application process can support a maximum of 128 Ndb objects.

Note

The Ndb object is multi-thread safe in that each Ndb object can be handled by one thread at a time. If an Ndb object is handed over to another thread, then the application must ensure that a memory barrier is used to ensure that the new thread sees all updates performed by the previous thread.

Semaphores and mutexes are examples of easy ways to provide memory barriers without having to bother about the memory barrier concept.

Public Methods. The following table lists the public methods of this class and the purpose or use of each method:

Method	Purpose / Use
`Ndb()`	Class constructor; represents a connection to a MySQL Cluster.
`~Ndb()`	Class destructor; terminates a Cluster connection when it is no longer to be used
`init()`	Initialises an `Ndb` object and makes it ready for use.
`getDatabaseName()`	Gets the name of the current database.
`setDatabaseName()`	Sets the name of the current database.
`getDatabaseSchemaName()`	Gets the name of the current database schema.
`setDatabaseSchemaName()`	Sets the name of the current database schema.
`startTransaction()`	Begins a transaction. (See Section 3.9, “The `NdbTransaction` Class”.)
`closeTransaction()`	Closes a transaction.
`createEventOperation()`	Creates a subscription to a database event. (See Section 3.5, “The `NdbEventOperation` Class”.)
`dropEventOperation()`	Drops a subscription to a database event.
`pollEvents()`	Waits for an event to occur.
`getNdbError()`	Retrieves an error. (See Section 4.1, “The `NdbError` Structure”.)

For detailed descriptions, signatures, and examples of use for each of these methods, see Section 3.1.1, “Ndb Class Methods”.

Class Diagram. This diagram shows all the available methods of the Ndb class:

3.1.1. `Ndb` Class Methods

3.1.1.1. Ndb Class Constructor
3.1.1.2. Ndb::init()
3.1.1.3. Ndb::getDatabaseName()
3.1.1.4. Ndb::setDatabaseName()
3.1.1.5. Ndb::getDatabaseSchemaName()
3.1.1.6. Ndb::setDatabaseSchemaName()
3.1.1.7. Ndb::startTransaction()
3.1.1.8. Ndb::closeTransaction()
3.1.1.9. Ndb::createEventOperation
3.1.1.10. Ndb::dropEventOperation()
3.1.1.11. Ndb::pollEvents()
3.1.1.12. Ndb::nextEvent()
3.1.1.13. Ndb::getNdbError()

Abstract

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

3.1.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 3.2, “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.
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.

3.1.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 3.9, “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.

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

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

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

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

3.1.1.7. `Ndb::startTransaction()`

Description. This method is used to begin a new transaction.

Important

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

See Section 3.1.1.8, “Ndb::closeTransaction()”, and Section 3.9.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 3.4.3.7, “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.

Return Value. An NdbTransaction object. See Section 3.9, “The NdbTransaction Class”.

3.1.1.8. `Ndb::closeTransaction()`

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

Signature.

void closeTransaction
    ( 
      NdbTransaction *transaction
    )

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

Return Value. N/A.

3.1.1.9. `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 3.5, “The NdbEventOperation Class”.

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

3.1.1.11. `Ndb::pollEvents()`

Description. This method waits for an event to occur, and returns as soon as an event is detected in any existing subscription belonging to the Ndb object for which the method is invoked. It is used to determine whether any events are available in the subscription queue.

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

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

3.1.1.13. `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 4, NDB 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 4.2, “NDB Error Codes, Classifications, and Messages”.

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

3.2. The `Ndb_cluster_connection` Class

3.2.1. Ndb_cluster_connection Class Methods

Abstract

This class represents a connection to a cluster of data nodes.

Description. Any NDB application program should begin with the creation of a single Ndb_cluster_connection object, and should make use of one and only one Ndb_cluster_connection. The application connects to a cluster management server when this object's connect() method is called. By using the wait_until_ready() method it is possible to wait for the connection to reach one or more data nodes.

Public Methods. The following table lists the public methods of this class and the purpose or use of each method:

Method	Purpose / Use
`Ndb_cluster_connection()`	Constructor; Creates a connection to a cluster of data nodes.
`connect()`	Connects to a cluster management server.
`wait_until_ready()`	Waits until a connection with one or more data nodes is successful.
`set_optimzed_node_selection()`	Used to control node-selection behaviour.

For detailed descriptions, signatures, and examples of use for each of these methods, see Section 3.2.1, “Ndb_cluster_connection Class Methods”.

Class Diagram. This diagram shows all the available methods of the ... class:

Public methods of the
Ndb_cluster_connection class.

3.2.1. `Ndb_cluster_connection` Class Methods

3.2.1.1. Ndb_cluster_connection Class Constructor
3.2.1.2. Ndb_cluster_connection::connect()
3.2.1.3. Ndb_cluster_connection::wait_until_ready()
3.2.1.4. Ndb_cluster_connection::set_optimized_node_selection()

3.2.1.1. `Ndb_cluster_connection` Class Constructor

Description. This method creates a connection to a MySQL cluster, that is, to a cluster of data nodes. The object returned by this method is required in order to instantiate an Ndb object. (See Section 3.1, “The Ndb Class”.) Thus, every NDB API application requires the use of an Ndb_cluster_connection.

Signature.

Ndb_cluster_connection
    (
      const char* connectstring = 0
    )

Parameters. This method requires a single parameter — a connectstring pointing to the location of the management server.

Return Value. An instance of Ndb_cluster_connection.

3.2.1.2. `Ndb_cluster_connection::connect()`

Description. This method connects to a cluster management server.

Signature.

int connect
    (
      int retries = 0,
      int delay   = 1,
      int verbose = 0
    )

Parameters. This method takes three parameters, all of which are optional:

retries specifies the number of times to retry the connection in the event of failure. The default value (0) means that no additional attempts to connect will be made in the event of failure; a negative value for retries results in the connection attempt being repeated indefinitely.
The delay represents the number of seconds between reconnect attempts; the default is 1 second.
verbose indicates whether the method should output a report of its progress, with 1 causing this reporting to be enabled; the default is 0 (reporting disabled).

Return Value. This method returns an int, which can have one of the following 3 values:

0: The connection attempt was successful.
1: Indicates a recoverable error.
-1: Indicates an unrecoverable error.

3.2.1.3. `Ndb_cluster_connection::wait_until_ready()`

Description. This method waits until the requested connection with one or more data nodes is successful.

Signature.

int wait_until_ready
    (
      int timeoutBefore,
      int timeoutAfter
    )

Parameters. This method takes two parameters:

timeoutBefore determines the number of seconds to wait until the first “live” node is detected. If this amount of time is exceeded with no live nodes detected, then the method immediately returns a negative value.
timeoutAfter determines the number of seconds to wait after the first “live” node is detected for all nodes to become active. If this amount of time is exceeded without all nodes becoming active, then the method immediately returns a value greater than zero.

If this method returns 0, then all nodes are “live”.

Return Value. wait_until_ready() returns an int, whose value is interpreted as follows:

= 0: All nodes are “live”.
> 0: At least one node is “live” (however, it is not known whether all nodes are “live”).
< 0: An error occurred.

3.2.1.4. `Ndb_cluster_connection::set_optimized_node_selection()`

Description. This method can be used to override the connect() method's default behaviour as regards which node should be connected to first.

Signature.

void set_optimized_node_selection
    (
      int value
    )

Parameters. An integer value.

Return Value. None.

3.3. The `NdbBlob` Class

3.3.1. NdbBlob Types
3.3.2. NdbBlob Class Methods

Abstract

This class represents a handle to a BLOB column and provides read and write access to BLOB column values. This object has a number of different states and provides several modes of access to BLOB data; these are also described in this section.

Description. An instance of NdbBlob is created using the NdbOperation::getBlobHandle() method during the operation preparation phase. (See Section 3.6, “The NdbOperation Class”.) This object acts as a handle on a BLOB column.

BLOB Data Storage. BLOB data is stored in 2 locations:

The header and inline bytes are stored in the blob attribute.
The blob's data segments are stored in a separate table named NDB$BLOB_tid_cid, where tid is the table ID, and cid is the blob column ID.

The inline and data segment sizes can be set using the appropriate NdbDictionary::Column() methods when the table is created. See Section 3.4.2, “The Column Class”, for more information about these methods.

Data Access Types. NdbBlob supports 3 types of data access:

In the preparation phase, the NdbBlob methods getValue() and setValue() are used to prepare a read or write of a BLOB value of known size.
Also in the preparation phase, setActiveHook() is used to define a routine which is invoked as soon as the handle becomes active.
In the active phase, readData() and writeData() are used to read and write BLOB values having arbitrary sizes.

These data access types can be applied in combination, provided that they are used in the order given above.

BLOB Operations. BLOB operations take effect when the next transaction is executed. In some cases, NdbBlob is forced to perform implicit execution. To avoid this, you should always operate on complete blob data segments, and use NdbTransaction::executePendingBlobOps() to flush reads and writes. There is no penalty for doing this if nothing is pending. It is not necessary to do so following execution (obviously) or after next scan result is obtained. NdbBlob also supports reading post- or pre-blob data from events. The handle can be read after the next event on the main table has been retrieved. The data becomes available immediately. (See Section 3.5, “The NdbEventOperation Class”.)

BLOBs and NdbOperations. NdbOperation methods acting on NdbBlob objects have the following characteristics:

NdbOperation::insertTuple() must use NdbBlob::setValue() if the BLOB attribute is non-nullable.
NdbOperation::readTuple() used with any lock mode can read but not write blob values.
When the LM_CommittedRead lock mode is used with readTuple(), the lock mode is automatically upgraded to LM_Read whenever blob attributes are accessed.
NdbOperation::updateTuple() can either overwrite an existing value using NdbBlob::setValue(), or update it during the active phase.
NdbOperation::writeTuple() always overwrites blob values, and must use NdbBlob::setValue() if the BLOB attribute is non-nullable.
NdbOperation::deleteTuple() creates implicit, non-accessible BLOB handles.
A scan with any lock mode can use its blob handles to read blob values but not write them.
A scan using the LM_Exclusive lock mode can update row and blob values using updateCurrentTuple(); the operation returned must explicitly create its own blob handle.
A scan using the LM_Exclusive lock mode can delete row values (and therefore blob values) using deleteCurrentTuple(); this create implicit non-accessible blob handles.
An operation which is returned by lockCurrentTuple() cannot update blob values.

See Section 3.6, “The NdbOperation Class”.

Known Issues. The following are known issues or limitations encountered when working with NdbBlob objects:

Too many pending BLOB operations can overflow the I/O buffers.
The table and its BLOB data segment tables are not created atomically.

Public Types. The public types defined by NdbBlob are shown here:

Type	Purpose / Use
`ActiveHook`	Callback for `NdbBlob::setActiveHook()`
`State`	Represents the states that may be assumed by the `NdbBlob`.

For a discussion of each of these types, along with its possible values, see Section 3.3.1, “NdbBlob Types”.

Public Methods. The following table lists the public methods of this class and the purpose or use of each method:

Method	Purpose / Use
`getState()`	Gets the state of an `NdbBlob` object
`getValue()`	Prepares to read a blob value
`setValue()`	Prepares to insert or update a blob value
`setActiveHook()`	Defines a callback for blob handle activation
`getVersion()`	Checks whether a blob is statement-based or event-based
`getNull()`	Checks whether a blob value is `NULL`
`setNull()`	Sets a blob to `NULL`
`getLength()`	Gets the length of a blob, in bytes
`truncate()`	Truncates a bloc to a given length
`getPos()`	Gets the current position for reading/writing
`setPos()`	Sets the position at which to begin reading/writing
`readData()`	Reads data from a blob
`writeData()`	Writes blob data
`getColumn()`	Gets a blob column.
`getNdbError()`	Gets an error (an `NdbError` object)
`blobsFirstBlob()`	Gets the first blob in a list.
`blobsNextBlob()`	Gets the next blob in a list
`getBlobEventName()`	Gets a blob event name
`getBlobTableName()`	Gets a blob data segment's table name.

Note

blobsFirstBlob() and blobsNextBlob() are static methods.

Tip

Most NdbBlob methods (nearly all of those whose return type is int) return 0 on success and -1 in the event of failure.

For detailed descriptions, signatures, and examples of use for each of these methods, see Section 3.3.2, “NdbBlob Class Methods”.

Class Diagram. This diagram shows all the available methods and types of the NdbBlob class:

Public methods and types of the
NdbBlob class.

3.3.1. `NdbBlob` Types

3.3.1.1. The NdbBlob::ActiveHook Type
3.3.1.2. The NdbBlob::State Type

Abstract

This section details the public types belonging to the NdbBlob class.

3.3.1.1. The `NdbBlob::ActiveHook` Type

Abstract

ActiveHook is a datatype defined for use as a callback for the setActiveHook() method. (See Section 3.3.2.4, “NdbBlob::setActiveHook()”.)

Definition. ActiveHook is a custom datatype defined as shown here:

typedef int ActiveHook
    (
      NdbBlob* me, 
      void*    arg
    )

Description. This is a callback for NdbBlob::setActiveHook(), and is invoked immediately once the prepared operation has been executed (but not committed). Any calls to getValue() or setValue() are performed first. The BLOB handle is active so readData() or writeData() can be used to manipulate the BLOB value. A user-defined argument is passed along with the NdbBlob. ActiveHook() returns a nonzero value in the event of an error.

3.3.1.2. The `NdbBlob::State` Type

Abstract

This is an enumerated datatype which represents the possible states of an NdbBlob instance.

Description. An NdbBlob may assume any one of these states

Enumeration Values.

Value	Description
`Prepared`	this is the state of the `NdbBlob` prior to operation execution.
`Active`	This is the `BLOB` handle's state following execution or the fetching of the next result, but before the transaction is committed.
`Closed`	This state occurs after the transaction has been committed.
`Invalid`	This follows a rollback or the close of a transaction.

3.3.2. `NdbBlob` Class Methods

3.3.2.1. NdbBlob::getState()
3.3.2.2. NdbBlob::getValue()
3.3.2.3. NdbBlob::setValue()
3.3.2.4. NdbBlob::setActiveHook()
3.3.2.5. NdbBlob::getVersion()
3.3.2.6. NdbBlob::getNull()
3.3.2.7. NdbBlob::setNull()
3.3.2.8. NdbBlob::setLength()
3.3.2.9. NdbBlob::truncate()
3.3.2.10. NdbBlob::getPos()
3.3.2.11. NdbBlob::setPos()
3.3.2.12. NdbBlob::readData()
3.3.2.13. NdbBlob::writeData()
3.3.2.14. NdbBlob::getColumn()
3.3.2.15. NdbBlob::getNdbError()
3.3.2.16. NdbBlob::blobsFirstBlob()
3.3.2.17. NdbBlob::blobsNextBlob()
3.3.2.18. NdbBlob::getBlobEventName()
3.3.2.19. NdbBlob::getBlobTabletName()

Abstract

This section discusses the public methods available in the NdbBlob class.

Important

This class has no public constructor. You can obtain a blob handle using NdbEventOperation::getBlobHandle(). (See Section 3.5, “The NdbEventOperation Class”.)

3.3.2.1. `NdbBlob::getState()`

Description. This method gets the current state of the NdbBlob object for which it is invoked. Possible states are described in Section 3.3.1.2, “The NdbBlob::State Type”.

Signature.

State getState
    (
      void
    )

Parameters. None.

Return Value. A State value. For possible values, see Section 3.3.1.2, “The NdbBlob::State Type”.

3.3.2.2. `NdbBlob::getValue()`

Description. Use this method to prepare to read a blob value; the value is available following invocation. Use getNull() to check for a NULL value; use getLength() to get the actual length of the blob, and to check for truncation. getValue() sets the current read/write position to the point following the end of the data which was read.

Signature.

int getValue
    (
      void*  data, 
      Uint32 bytes
    )

Parameters. This method takes two parameters — a pointer to the data to be read, and the number of bytes to be read.

Return Value. 0 on success, -1 on failure.

3.3.2.3. `NdbBlob::setValue()`

Description. This method is used to prepare for inserting or updating a blob value. Any existing blob data that is longer than the new data is truncated. The data buffer must remain valid until the operation has been executed. setValue() sets the current read/write position to the point following the end of the data. You can set data to a null pointer (0) in order to create a NULL value.

Signature.

int setValue
    (
      const void*  data, 
      Uint32       bytes
    )

Parameters. This method takes two parameters:

The data that is to be inserted or used to overwrite the blob value.
The number of bytes — that is, the length — of the data.

Return Value. 0 on success, -1 on failure.

3.3.2.4. `NdbBlob::setActiveHook()`

Description. This method defines a callback for blob handle activation. The queue of prepared operations will be executed in no-commit mode up to this point; then, the callback is invoked. For additional information, see Section 3.3.1.1, “The NdbBlob::ActiveHook Type”.

Signature.

int setActiveHook
    (
      ActiveHook*  activeHook,
      void*        arg
    )

Parameters. This method requires two parameters:

A pointer to an ActiveHook value; this is a callback as explained in Section 3.3.1.1, “The NdbBlob::ActiveHook Type”.
A pointer to void, for any data to be passed to the callback.

Return Value. 0 on success, -1 on failure.

3.3.2.5. `NdbBlob::getVersion()`

Description. This method is used to distinguish whether a blob operation is statement-based or event-based.

Signature.

void getVersion
    (
      int& version
    )

Parameters. This method takes a single parameter, an integer reference to the blob version (operation type).

Return Value. One of the following three values:

-1: This is a “normal” (statement-based) blob.
0: This is an event-operation based blob, following a change in its data.
1: This is an event-operation based blob, prior to any change in its data.

Note

getVersion() is always successful, assuming that it is invoked as a method of a valid NdbBlob instance.

3.3.2.6. `NdbBlob::getNull()`

Description. This method checks whether the blob's value is NULL.

Signature.

int getNull
    (
      void
    )

Parameters. None.

Return Value. One of the following values, interpreted as shown here:

-1: The blob is undefined. If this is a non-event blob, this result causes a state error.
0: The blob has a non-null value.
1: The blob's value is NULL.

3.3.2.7. `NdbBlob::setNull()`

Description. This method sets the value of a blob to NULL.

Signature.

int setNull
    (
      void
    )

Parameters. None.

Return Value. 0 on success; -1 on failure.

3.3.2.8. `NdbBlob::setLength()`

Description. This method gets the blob's current length in bytes.

Signature.

int getLength
    (
      Uint64& length
    )

Parameters. A reference to the length.

Return Value. The blob's length in bytes. For a NULL blob, this method returns 0. to distinguish between a blob whose length is 0 blob and one which is NULL, use the getNull() method.

3.3.2.9. `NdbBlob::truncate()`

Description. This method is used to truncate a blob to a given length.

Signature.

int truncate
    (
      Uint64 length = 0
    )

Parameters. truncate() takes a single parameter which specifies the new length to which the blob is to be truncated. This method has no effect if length is greater than the blob's current length (which you can check using getLength()).

Return Value. 0 on success, -1 on failure.

3.3.2.10. `NdbBlob::getPos()`

Description. This method gets the current read/write position in a blob.

Signature.

int getPos
    (
      Uint64& pos
    )

Parameters. One parameter, a reference to the position.

Return Value. Returns 0 on success, or -1 on failure. (Following a successful invocation, pos will hold the current read/write position within the blob, as a number of bytes from the beginning.)

3.3.2.11. `NdbBlob::setPos()`

Description. This method sets the position within the blob at which to read or write data.

Signature.

int setPos
    (
      Uint64 pos
    )

Parameters. The setPos() method takes a single parameter pos (an unsigned 64-bit integer), which is the position for reading or writing data. The value of pos must be between 0 and the blob's current length.

Important

“Sparse” blobs are not supported in the NDB API; there can be no unused data positions within a blob.

Return Value. 0 on success, -1 on failure.

3.3.2.12. `NdbBlob::readData()`

Description. This method is used to read data from a blob.

Signature.

int readData
    (
      void*     data, 
      Uint32&  bytes
    )

Parameters. readData() accepts a pointer to the data to be read, and a reference to the number of bytes read.

Return Value. 0 on success, -1 on failure. Following a successful invocation, data points to the data that was read, and bytes holds the number of bytes read.

3.3.2.13. `NdbBlob::writeData()`

Description. This method is used to write data to an NdbBlob. After a successful invocation, the read/write position will be at the first byte following the data that was written to the blob.

Note

A write past the current end of the blob data extends the blob automatically.

Signature.

int writeData
    (
      const void*  data, 
      Uint32       bytes
    )

Parameters. This method takes two parameters, a pointer to the data to be written, and the number of bytes to write.

Return Value. 0 on success, -1 on failure.

3.3.2.14. `NdbBlob::getColumn()`

Description. Use this method to get the BLOB column to which the NdbBlob belongs.

Signature.

const Column* getColumn
    (
      void
    )

Parameters. None.

Return Value. A Column object. (See Section 3.4.2, “The Column Class”.)

3.3.2.15. `NdbBlob::getNdbError()`

Description. Use this method to obtain an error object. The error may be blob-specific or may be copied from a failed implicit operation. The error code is copied back to the operation unless the operation already has a non-zero error code.

Signature.

const NdbError& getNdbError
    (
      void
    ) const

Parameters. None.

Return Value. An NdbError object. See Section 4.1, “The NdbError Structure”.

3.3.2.16. `NdbBlob::blobsFirstBlob()`

Description. This method initialises a list of blobs belonging to the current operation and returns the first blob in the list.

Signature.

NdbBlob* blobsFirstBlob
    (
      void
    )

Parameters. None.

Return Value. A pointer to the desired blob.

3.3.2.17. `NdbBlob::blobsNextBlob()`

Description. Use the method to obtain the next in a list of blobs that was initialised using blobsFirstBlob(). See Section 3.3.2.16, “NdbBlob::blobsFirstBlob()”.

Signature.

NdbBlob* blobsNextBlob
    (
      void
    )

Parameters. None.

Return Value. A pointer to the desired blob.

3.3.2.18. `NdbBlob::getBlobEventName()`

Description. This method gets a blob event name. The blob event is created if the main event monitors the blob column. The name includes the main event name.

Signature.

static int getBlobEventName
    (
      char*       name, 
      Ndb*        ndb, 
      const char* event, 
      const char* column
    )

Parameters. This method takes 4 parameters:

name: The name of the blob event.
ndb: The relevant Ndb object.
event: The name of the main event.
column: The blob column.

Return Value. 0 on success, -1 on failure.

3.3.2.19. `NdbBlob::getBlobTabletName()`

Description. This method gets the blob data segment table name.

Note

This method is generally of use only for testing and debugging purposes.

Signature.

static int getBlobTableName
    (
      char*       name, 
      Ndb*        ndb, 
      const char* table, 
      const char* column
    )

Parameters. This method takes 4 parameters:

name: The name of the blob data segment table.
ndb: The relevant Ndb object.
table: The name of the main table.
column: The blob column.

Return Value. 0 on success, -1 on failure.

3.4. The `NdbDictionary` Class

3.4.1. The Dictionary Class
3.4.2. The Column Class
3.4.3. The Object Class
3.4.4. The AutoGrowSpecification Structure

Abstract

This class provides meta-information about database objects, such as tables, columns, and indexes.

While the preferred method of database object creation and deletion is through the MySQL Server, NdbDictionary also permits the developer to perform these tasks via the NDB API.

Description. This is a data dictionary class that supports enquiries about tables, columns, and indexes. It also provides ways to define these database objects and to remove them. Both sorts of functionality are supplied via inner classes that model these objects. These include the following:

NdbDictionary::Object::Table for working with tables
NdbDictionary::Column for creating table columns
NdbDictionary::Object::Index for working with secondary indexes
NdbDictionary::Dictionary for creating database objects and making schema enquiries
NdbDictionary::Object::Event for working with events in the cluster.

Additional NdbDictionary::Object subclasses model the tablespaces, logfile groups, datafiles, and undofiles required for working with Cluster Disk Data tables introduced in MySQL 5.1.

Important

Tables and indexes created using NdbDictionary cannot be viewed from the MySQL Server.

Dropping indexes via the NDB API that were created originally from a MySQL Cluster causes inconsistencies.

Public Methods. NdbDictionary itself has no public methods. All work is accomplished by accessing its subclasses and their public members.

NdbDictionary Subclass Hierarchy. This diagram shows the hierarchy made up of the NdbDictionary class, its subclasses, and their enumerated datatypes:

Diagram showing relationships of the
NdbDictionary class, its subclasses, and
their enumerated datatypes.

The next several sections discuss NdbDictionary's subclasses and their public members in detail. The organisation of these sections reflects that of the NdbDictionary class hierarchy.

Note

For the numeric equivalents to enumerations of NdbDictionary subclasses, see the file /storage/ndb/include/ndbapi/NdbDictionary.hpp in the MySQL 5.1 source tree.

3.4.1. The `Dictionary` Class

3.4.1.1. Dictionary Class Methods
3.4.1.2. The List Class

Abstract

This section describes the Dictionary class and its subclasses List and Element.

Description. This is used for defining and retrieving data object metadata. It also includes methods for creating and dropping database objects.

Public Methods. The following table lists the public methods of this class and the purpose or use of each method:

Method	Purpose / Use
`Dictionary()`	Class constructor method
`~Dictionary()`	Destructor method
`getTable()`	Gets the table having the given name
`getIndex()`	Gets the index having the given name
`getEvent()`	Gets the event having the given name
`getTablespace()`	Gets the tablespace having the given name
`getLogfileGroup()`	Gets the logfile group having the given name
`getDatafile()`	Gets the datafile having the given name
`getUndofile()`	Gets the undofile having the given name
`getNdbError()`	Retrieves the latest error
`createTable()`	Creates a table
`createIndex()`	Creates an index
`createEvent()`	Creates an event
`createTablespace()`	Creates a tablespace
`createLogfileGroup()`	Creates a logfile group
`createDatafile()`	Creates a datafile
`createUndofile()`	Creates an undofile
`dropTable()`	Drops a table
`dropIndex()`
`dropEvent()`	Drops an index
`dropTablespace()`	Drops a tablespace
`dropLogfileGroup()`	Drops a logfile group
`dropDatafile()`	Drops a datafile
`dropUndofile()`	Drops an undofile
`listObjects()`	Fetches a list of the objects in the dictionary
`listIndexes()`	Fetches a list of the indexes defined on a given table
`removeCachedTable()`	Removes a table from the local cache
`removeCachedIndex()`	Removes an index from the local cache

For detailed descriptions, signatures, and examples of use for each of these methods, see Section 3.4.1.1, “Dictionary Class Methods”.

Important

Objects created using the Dictionary::create*() methods are not visible from the MySQL Server. For this reason, it is usually preferable to avoid using them.

Note

The Dictionary class does not have any methods for working directly with columns. You must use Column class methods for this purpose — see Section 3.4.2, “The Column Class”, for details.

Public Types. See Section 3.4.1.2, “The List Class”, and Section 3.4.1.2.1, “The Element Structure”.

Dictionary Class and Subclass Diagram. This diagram shows all the public members of the Dictionary class and its subclasses:

3.4.1.1. `Dictionary` Class Methods

3.4.1.1.1. Dictionary Class Constructor
3.4.1.1.2. Dictionary::getTable()
3.4.1.1.3. Dictionary::getIndex()
3.4.1.1.4. Dictionary::getEvent()
3.4.1.1.5. Dictionary::getTablespace()
3.4.1.1.6. Dictionary::getLogfileGroup()
3.4.1.1.7. Dictionary::getDatafile()
3.4.1.1.8. Dictionary::getUndofile()
3.4.1.1.9. Dictionary::getNdbError()
3.4.1.1.10. Dictionary::createTable()
3.4.1.1.11. Dictionary::createIndex()
3.4.1.1.12. Dictionary::createEvent()
3.4.1.1.13. Dictionary::createTablespace()
3.4.1.1.14. Dictionary::createLogfileGroup()
3.4.1.1.15. Dictionary::createDatafile()
3.4.1.1.16. Dictionary::createUndofile()
3.4.1.1.17. Dictionary::dropTable()
3.4.1.1.18. Dictionary::dropIndex()
3.4.1.1.19. Dictionary::dropEvent()
3.4.1.1.20. Dictionary::dropTablespace()
3.4.1.1.21. Dictionary::dropLogfileGroup()
3.4.1.1.22. Dictionary::dropDatafile()
3.4.1.1.23. Dictionary::dropUndofile()
3.4.1.1.24. Dictionary::listObjects()
3.4.1.1.25. Dictionary::listIndexes()
3.4.1.1.26. Dictionary::removeCachedTable()
3.4.1.1.27. Dictionary::removeCachedIndex()

Abstract

This section details all of the public methods of the Dictionary class.

3.4.1.1.1. `Dictionary` Class Constructor

Description. This method creates a new instance of the Dictionary class.

Note

Both the constructor and destructor for this class are protected methods, rather than public.

Signature.

protected Dictionary
    (
      Ndb& ndb
    )

Parameters. An Ndb object. See Section 3.1, “The Ndb Class”.

Return Value. A Dictionary object.

Destructor. The destructor takes no parameters and returns nothing.

protected ~Dictionary
    (
      void
    )

3.4.1.1.2. `Dictionary::getTable()`

Description. This method can be used to access the table with a known name. See Section 3.4.3.7, “The Table Class”.

Signature.

const Table* getTable
    (
      const char* name
    ) const

Parameters. The name of the table.

Return Value. A pointer to the table, or NULL if there is no table with the name supplied.

3.4.1.1.3. `Dictionary::getIndex()`

Description. This method retrieves a pointer to an index, given the name of the index and the name of the table to which the table belongs.

Signature.

const Index* getIndex
    (
      const char* iName,
      const char* tName
    ) const

Parameters. Two parameters are required:

The name of the index (iName)
The name of the table to which the index belongs (tName)

Both are string values, represented by character pointers.

Return Value. A pointer to an Index. See Section 3.4.3.5, “The Index Class”, for information about this object.

3.4.1.1.4. `Dictionary::getEvent()`

Description. This method is used to obtain an Event object, given the event's name.

Signature.

const Event* getEvent
    (
      const char* eventName
    )

Parameters. The eventName, a string (character pointer).

Return Value. A pointer to an Event object. See Section 3.4.3.4, “The Event Class”, for more information.

3.4.1.1.5. `Dictionary::getTablespace()`

Description. Given either the name or ID of a tablespace, this method returns the corresponding Tablespace object.

Signatures. Using the tablespace name:

Tablespace getTablespace
    (
      const char* name
    )

Using the tablespace ID:

Tablespace getTablespace
    (
      Uint32 id
    )

Parameters. Either one of the following:

The name of the tablespace, a string (as a character pointer)
The unsigned 32-bit integer id of the tablespace

Return Value. A Tablespace object, as discussed in Section 3.4.3.8, “The Tablespace Class”.

3.4.1.1.6. `Dictionary::getLogfileGroup()`

Description. This method gets a LogfileGroup object, given the name of the logfile group.

Signature.

LogfileGroup getLogfileGroup
    (
      const char* name
    )

Parameters. The name of the logfile group.

Return Value. An instance of LogfileGroup; see Section 3.4.3.6, “The LogfileGroup Class”, for more information.

3.4.1.1.7. `Dictionary::getDatafile()`

Description. This method is used to retrieve a Datafile object, given the node ID of the data node where a datafile is located and the path to the datafile on that node's filesystem.

Signature.

Datafile getDatafile
    (
      Uint32      nodeId, 
      const char* path
    )

Parameters. This method must be invoked using two arguments, as shown here:

The 32-bit unsigned integer nodeId of the data node where the datafile is located
The path to the datafile on the node's filesystem (string as character pointer)

Return Value. A Datafile object — see Section 3.4.3.3, “The Datafile Class”, for details.

3.4.1.1.8. `Dictionary::getUndofile()`

Description. This method gets an Undofile object, given the ID of the node where an undofile is located and the filesystem path to the file.

Signature.

Undofile getUndofile
    (
      Uint32      nodeId, 
      const char* path
    )

Parameters. This method requires the following two arguments:

The nodeId of the data node where the undofile is located; this value is passed as a 32-bit unsigned integer
The path to the undofile on the node's filesystem (string as character pointer)

Return Value. An instance of Undofile. For more information, see Section 3.4.3.9, “The Undofile Class”.

3.4.1.1.9. `Dictionary::getNdbError()`

Description. This method retrieves the most recent NDB API error.

Signature.

const struct NdbError& getNdbError
    (
      void
    ) const

Parameters. None.

Return Value. A reference to an NdbError object. See Section 4.1, “The NdbError Structure”.

3.4.1.1.10. `Dictionary::createTable()`

Description. Creates a table given an instance of Table.

Signature.

int createTable
    (
      const Table& table
    )

Parameters. An instance of Table. See Section 3.4.3.7, “The Table Class”, for more information.

Return Value. 0 on success, -1 on failure.

3.4.1.1.11. `Dictionary::createIndex()`

Description. This method creates an index given an instance of Index and possibly an optional instance of Table.

Signature.

int createIndex
    (
      const Index& index
    )

int createIndex
    (
      const Index& index, 
      const Table& table
    )

Parameters. Required: A reference to an Index object. Optional: A reference to a Table object.

Return Value. 0 on success, -1 on failure.

3.4.1.1.12. `Dictionary::createEvent()`

Description. Creates an event, given a reference to an Event object.

Signature.

int createEvent
    (
      const Event& event
    )

Parameters. A reference event to an Event object.

Return Value. 0 on success, -1 on failure.

3.4.1.1.13. `Dictionary::createTablespace()`

Description. This method creates a new tablespace, given a Tablespace object.

Signature.

int createTablespace
    (
      const Tablespace& tSpace
    )

Parameters. This method requires a single argument — a reference to an instance of Tablespace.

Return Value. 0 on success, -1 on failure.

3.4.1.1.14. `Dictionary::createLogfileGroup()`

Description. This method creates a new logfile group, given an instance of LogfileGroup.

Signature.

int createLogfileGroup
    (
      const LogfileGroup& lGroup
    )

Parameters. A single argument, a reference to a LogfileGroup object, is required.

Return Value. 0 on success, -1 on failure.

3.4.1.1.15. `Dictionary::createDatafile()`

Description. This method creates a new datafile, given a Datafile object.

Signature.

int createDatafile
    (
      const Datafile& dFile
    )

Parameters. A single argument — a reference to an instance of Datafile — is required.

Return Value. 0 on success, -1 on failure.

3.4.1.1.16. `Dictionary::createUndofile()`

Description. This method creates a new undofile, given an Undofile object.

Signature.

int createUndofile
    (
      const Undofile& uFile
    )

Parameters. This method requires one argument: a reference to an instance of Undofile.

Return Value. 0 on success, -1 on failure.

3.4.1.1.17. `Dictionary::dropTable()`

Description. Drops a table given an instance of Table.

Signature.

int dropTable
    (
      const Table& table
    )

Parameters. An instance of Table. See Section 3.4.3.7, “The Table Class”, for more information.

Return Value. 0 on success, -1 on failure.

3.4.1.1.18. `Dictionary::dropIndex()`

Description. This method drops an index given an instance of Index and possibly an optional instance of Table.

Signature.

int dropIndex
    (
      const Index& index
    )

int dropIndex
    (
      const Index& index, 
      const Table& table
    )

Parameters. Required: A reference to an Index object. Optional: A reference to a Table object.

Return Value. 0 on success, -1 on failure.

3.4.1.1.19. `Dictionary::dropEvent()`

Description. This method drops an event, given a reference to an Event object.

Signature.

int dropEvent
    (
      const Event& event
    )

Parameters. A reference event to an Event object.

Return Value. 0 on success, -1 on failure.

3.4.1.1.20. `Dictionary::dropTablespace()`

Description. This method drops a tablespace, given a Tablespace object.

Signature.

int dropTablespace
    (
      const Tablespace& tSpace
    )

Parameters. This method requires a single argument — a reference to an instance of Tablespace.

Return Value. 0 on success, -1 on failure.

3.4.1.1.21. `Dictionary::dropLogfileGroup()`

Description. This method drops a logfile group, given an instance of LogfileGroup.

Signature.

int dropLogfileGroup
    (
      const LogfileGroup& lGroup
    )

Parameters. A single argument, a reference to a LogfileGroup object, is required.

Return Value. 0 on success, -1 on failure.

3.4.1.1.22. `Dictionary::dropDatafile()`

Description. This method drops a datafile, given a Datafile object.

Signature.

int dropDatafile
    (
      const Datafile& dFile
    )

Parameters. A single argument — a reference to an instance of Datafile — is required.

Return Value. 0 on success, -1 on failure.

3.4.1.1.23. `Dictionary::dropUndofile()`

Description. This method drops an undofile, given an Undofile object.

Signature.

int dropUndofile
    (
      const Undofile& uFile
    )

Parameters. This method requires one argument: a reference to an instance of Undofile.

Return Value. 0 on success, -1 on failure.

3.4.1.1.24. `Dictionary::listObjects()`

Description. This method is used to obtain a list of objects in the dictionary. It is possible to get all of the objects in the dictionary, or to restrict the list to objects of a single type.

Signatures.

int listObjects
    (
      List&       list,
      Object::Type type = Object::TypeUndefined
    ) const

int listObjects
    (
      List&       list,
      Object::Type type = Object::TypeUndefined
    )

Parameters. A reference to a List object is required — this is the list that contains the dictionary's objects after listObjects() is called. (See Section 3.4.1.2, “The List Class”.) An optional second argument type may be used to restrict the list to only those objects of the given type — that is, of the specified Object::Type. (See Section 3.4.3.1.5, “The Object::Type Type”.)

Return Value. 0 on success, -1 on failure.

3.4.1.1.25. `Dictionary::listIndexes()`

Description. This method is used to obtain a List of all the indexes on a table, given the table's name. (See Section 3.4.1.2, “The List Class”.)

Signature.

int listIndexes
    (
      List&      list, 
      const char* table
) const

int listIndexes
    (
      List&      list, 
      const char* table
    )

Parameters. listIndexes() takes two arguments:

A reference to the List that contains the indexes following the call to the method
The name of the table whose indexes are to be listed

Both of these arguments are required.

Return Value. 0 on success, -1 on failure.

3.4.1.1.26. `Dictionary::removeCachedTable()`

Description. This method removes the specified table from the local cache.

Signature.

void removeCachedTable
    (
      const char* table
    )

Parameters. The name of the table to be removed from the cache.

Return Value. None.

3.4.1.1.27. `Dictionary::removeCachedIndex()`

Description. This method removes the specified index from the local cache.

Signature.

void removeCachedIndex
    (
      const char* index,
      const char* table
    )

Parameters. The removeCachedIndex() requires two arguments:

The name of the index to be removed from the cache
The name of the table in which the index is found

Return Value. None.

3.4.1.2. The `List` Class

3.4.1.2.1. The Element Structure

Abstract

This section covers the List class, a subclass of NdbDictionary::Dictionary.

Description. The List class is a Dictionary subclass that is used for representing lists populated by the methods Dictionary::listObjects() and Dictionary::listIndexes(). (See Section 3.4.1.1.24, “Dictionary::listObjects()”, and Section 3.4.1.1.25, “Dictionary::listIndexes()”.)

Class Methods. This class has only two methods, a constructor and a destructor. Neither method takes any arguments, and the return type of each is void.

Constructor. Calling the List constructor creates a new List whose count and elements attributes are both set equal to 0.

Destructor. The destructor ~List() is simply defined in such a way as to remove all elements and their properties. You can find its definition in the file /storage/ndb/include/ndbapi/NdbDictionary.hpp.

Attributes. A List has two attributes:

count, an unsigned integer, which stores the number of elements in the list.
elements, a pointer to an array of Element data structures contained in the list. See Section 3.4.1.2.1, “The Element Structure”.

Types. The List class defines an Element structure, which is described in the following section.

Note

For a graphical representation of this class and its parent-child relationships, see Section 3.4.1, “The Dictionary Class”.

3.4.1.2.1. The `Element` Structure

Abstract

This section discusses the structure NdbDictionary::Dictionary::List::Element.

Description. The Element structure models an element of a list; it is used to store an object in a List populated by the methods Dictionary::listObjects() and Dictionary::listIndexes().

Attributes. An Element has the attributes shown in the following table:

Attribute	Type	Initial Value	Description
`id`	`unsigned int`	`0`	The object's ID
`type`	`Object::Type`	`Object::TypeUndefined`	The object's type — see Section 3.4.3.1.5, “The `Object::Type` Type” for possible values
`state`	`Object::State`	`Object::StateUndefined`	The object's state — see Section 3.4.3.1.2, “The `Object::State` Type” for possible values
`store`	`Object::Store`	`Object::StoreUndefined`	How the object is stored — see Section 3.4.3.1.4, “The `Object::Store` Type” for possible values
`database`	`char*`	`0`	The database in which the object is found
`schema`	`char*`	`0`	The schema in which the object is found
`name`	`char*`	`0`	The object's name

Note

For a graphical representation of this class and its parent-child relationships, see Section 3.4.1, “The Dictionary Class”.

3.4.2. The `Column` Class

3.4.2.1. Column Types
3.4.2.2. Column Class Methods

Abstract

This class represents a column in an NDB Cluster table.

Description. Each instance of the Column is characterised by its type, which is determined by a number of type specifiers:

Built-in type
Array length or maximum length
Precision and scale (currently not in use)
Character set (applicable only to columns using string datatypes)
Inline and part sizes (applicable only to BLOB columns)

These types in general correspond to MySQL datatypes and their variants. The data formats are same as in MySQL. The NDB API provides no support for constructing such formats; however, they are checked by the NDB kernel.

Public Methods. The following table lists the public methods of this class and the purpose or use of each method:

Method	Purpose / Use
`getName()`	Gets the name of the column
`getNullable()`	Checks whether the column can be set to `NULL`
`getPrimaryKey()`	Check whether the column is part of the table's primary key
`getColumnNo()`	Gets the column number
`equal()`	Compares `Column` objects
`getType()`	Gets the column's type (`Type` value)
`getLength()`	Gets the column's length
`getCharset()`	Get the character set used by a string (text) column (not applicable to columns not storing character data)
`getInlineSize()`	Gets the inline size of a `BLOB` column (not applicable to other column types)
`getPartSize()`	Gets the part size of a `BLOB` column (not applicable to other column types)
`getStripeSize()`	Gets a BLOB column's stripe size (not applicable to other column types)
`getSize()`	Gets the size of an element
`getPartitionKey()`	Checks whether the column is part of the table's partitioning key
`getArrayType()`	Gets the column's array type
`getStorageType()`	Gets the storage type used by this column
`getPrecision()`	Gets the column's precision (used for decimal types only)
`getScale()`	Gets the column's scale (used for decimal types only)
`Column()`	Class constructor; there is also a copy constructor
`~Column()`	Class destructor
`setName()`	Sets the column's name
`setNullable()`	Toggles the column's nullability
`setPrimaryKey()`	Determines whether the column is part of the primary key
`setType()`	Sets the column's `Type`
`setLength()`	Sets the column's length
`setCharset()`	Sets the character set used by a column containing character data (not applicable to non-textual columns)
`setInlineSize()`	Sets the inline size for a `BLOB` column (not applicable to non-`BLOB` columns)
`setPartSize()`	Sets the part size for a `BLOB` column (not applicable to non-`BLOB` columns)
`setStripeSize()`	Sets the stripe size for a `BLOB` column (not applicable to non-`BLOB` columns)
`setPartitionKey()`	Determines whether the column is part of the table's partitioning key
`setArrayType()`	Sets the column's `ArrayType`
`setStorageType()`	Sets the storage type to be used by this column
`getPrecision()`	Gets the column's precision (used for decimal types only)
`getScale()`	Gets the column's scale (used for decimal types only)
`getPrecision()`	Sets the column's precision (used for decimal types only)
`getScale()`	Sets the column's scale (used for decimal types only)

For detailed descriptions, signatures, and examples of use for each of these methods, see Section 3.4.2.2, “Column Class Methods”.

Public Types. These are the public types of the Column class:

Type	Purpose / Use
`ArrayType`	Specifies the column's internal storage format
`StorageType`	Determines whether the column is stored in memory or on disk
`Type`	The column's datatype. `NDB` columns have the datatypes as found in MySQL

For a discussion of each of these types, along with its possible values, see Section 3.4.2.1, “Column Types”.

Class Diagram. This diagram shows all the available methods and enumerated types of the Column class:

Public methods and enumerated types of
the Column class.

3.4.2.1. `Column` Types

3.4.2.1.1. The Column::ArrayType Type
3.4.2.1.2. The Column::StorageType Type
3.4.2.1.3. Column::Type

Abstract

This section details the public types belonging to the Column class.

3.4.2.1.1. The `Column::ArrayType` Type

Abstract

This type describes the Column's internal attribute format.

Description. The attribute storage format can be either fixed or variable.

Enumeration Values.

Value	Description
`ArrayTypeFixed`	stored as a fixed number of bytes
`ArrayTypeShortVar`	stored as a variable number of bytes; uses 1 byte overhead
`ArrayTypeMediumVar`	stored as a variable number of bytes; uses 2 bytes overhead

The fixed storage format is faster but also generally requires more space than the variable format. The default is ArrayTypeShortVar for Var* types and ArrayTypeFixed for others. The default is usually sufficient.

3.4.2.1.2. The `Column::StorageType` Type

Abstract

This type describes the storage type used by a Column object.

Description. The storage type used for a given column can be either in memory or on disk. Columns stored on disk mean that less RAM is required overall but such columns cannot be indexed, and are potentially much slower to access. The default is StorageTypeMemory.

Enumeration Values.

Value	Description
`StorageTypeMemory`	Store the column in memory
`StorageTypeDisk`	Store the column on disk

3.4.2.1.3. `Column::Type`

Abstract

Type is used to describe the Column object's datatype.

Description. Datatypes for Column objects are analogous to the datatypes used by MySQL. The types Tinyint, Tinyintunsigned, Smallint, Smallunsigned, Mediumint, Mediumunsigned, Int, Unsigned, Bigint, Bigunsigned, Float, and Double (that is, types Tinyint through Double in the order listed in the Enumeration Values table) can be used in arrays.

Enumeration Values.

Value	Description
`Undefined`	Undefined
`Tinyint`	1-byte signed integer
`Tinyunsigned`	1-byte unsigned integer
`Smallint`	2-byte signed integer
`Smallunsigned`	2-byte unsigned integer
`Mediumint`	3-byte signed integer
`Mediumunsigned`	3-byte unsigned integer
`Int`	4-byte signed integer
`Unsigned`	4-byte unsigned integer
`Bigint`	8-byte signed integer
`Bigunsigned`	8-byte signed integer
`Float`	4-byte float
`Double`	8-byte float
`Olddecimal`	Signed decimal as used prior to MySQL 5.0
`Olddecimalunsigned`	Unsigned decimal as used prior to MySQL 5.0
`Decimal`	Signed decimal as used by MySQL 5.0 and later
`Decimalunsigned`	Unsigned decimal as used by MySQL 5.0 and later
`Char`	A fixed-length array of 1-byte characters; maximum length is 255 characters
`Varchar`	A variable-length array of 1-byte characters; maximum length is 255 characters
`Binary`	A fixed-length array of 1-byte binary characters; maximum length is 255 characters
`Varbinary`	A variable-length array of 1-byte binary characters; maximum length is 255 characters
`Datetime`	An 8-byte date and time value, with a precision of 1 second
`Date`	A 4-byte date value, with a precision of 1 day
`Blob`	A binary large object; see Section 3.3, “The `NdbBlob` Class”
`Text`	A text blob
`Bit`	A bit value; the length specifies the number of bits
`Longvarchar`	A 2-byte `Varchar`
`Longvarbinary`	A 2-byte `Varbinary`
`Time`	Time without date
`Year`	1-byte year value in the range 1901-2155 (same as MySQL)
`Timestamp`	Unix time

Caution

Do not confuse Column::Type with Object::Type or Table::Type.

3.4.2.2. `Column` Class Methods

3.4.2.2.1. Column Constructor
3.4.2.2.2. Column::getName()
3.4.2.2.3. Column::getNullable()
3.4.2.2.4. Column::getPrimaryKey()
3.4.2.2.5. Column::getColumnNo()
3.4.2.2.6. Column::equal()
3.4.2.2.7. Column::getType()
3.4.2.2.8. Column::getPrecision()
3.4.2.2.9. Column::getScale()
3.4.2.2.10. Column::getLength()
3.4.2.2.11. Column::getCharset()
3.4.2.2.12. Column::getInlineSize()
3.4.2.2.13. Column::getPartSize()
3.4.2.2.14. Column::getStripeSize()
3.4.2.2.15. Column::getSize()
3.4.2.2.16. Column::getPartitionKey()
3.4.2.2.17. Column::getArrayType()
3.4.2.2.18. Column::getStorageType()
3.4.2.2.19. Column::setName()
3.4.2.2.20. Column::setNullable()
3.4.2.2.21. Column::setPrimaryKey()
3.4.2.2.22. Column::setType()
3.4.2.2.23. Column::setPrecision()
3.4.2.2.24. Column::setScale()
3.4.2.2.25. Column::setLength()
3.4.2.2.26. Column::setCharset()
3.4.2.2.27. Column::setInlineSize
3.4.2.2.28. Column::setPartSize()
3.4.2.2.29. Column::setStripeSize()
3.4.2.2.30. Column::setPartitionKey()

Abstract

This section documents the public methods of the Column class.

Note

The assignment (=) operator is overloaded for this class, so that it always performs a deep copy.

Warning

As with other database objects, Column object creation and attribute changes to existing columns done using the NDB API are not visible from MySQL. For example, if you change a column's datatype using Column::setType(), MySQL will regard the type of column as being unchanged. The only exception to this rule with regard to columns is that you can change the name of an existing column using Column::setName().

3.4.2.2.1. `Column` Constructor

Description. You can create a new Column or copy an existing one using the class constructor.

Warning

A Column created using the NDB API will not be visible to a MySQL server.

Signature. You can create either a new instance of the Column class, or by copying an existing Column object. Both of these are shown here.

Constructor for a new Column:

Column
    (
      const char* name = ""
    )

Copy constructor:

Column
    (
      const Column& column
    )

Parameters. When creating a new instance of Column, the constructor takes a single argument, which is the name of the new column to be created. The copy constructor also takes one parameter — in this case, a reference to the Column instance to be copied.

Return Value. A Column object.

Destructor. The Column class destructor takes no arguments and None.

Examples.

[To be supplied...]

3.4.2.2.2. `Column::getName()`

Description. This method returns the name of the column for which it is called.

Signature.

const char* getName
    (
      void
    ) const

Parameters. None.

Return Value. The name of the column.

3.4.2.2.3. `Column::getNullable()`

Description. This method is used to determine whether the column can be set to NULL.

Signature.

bool getNullable
    (
      void
    ) const

Parameters. None.

Return Value. A Boolean value: true if the column can be set to NULL, otherwise false.

3.4.2.2.4. `Column::getPrimaryKey()`

Description. This method is used to determine whether the column is part of the table's primary key.

Signature.

bool getPrimaryKey
    (
      void
    ) const

Parameters. None.

Return Value. A Boolean value: true if the column is part of the primary key of the table to which this column belongs, otherwise false.

3.4.2.2.5. `Column::getColumnNo()`

Description. This method gets the number of a column — that is, its horizontal position within the table.

Signature.

int getColumnNo
    (
      void
    ) const

Parameters. None.

Return Value. The column number as an integer.

3.4.2.2.6. `Column::equal()`

Description. This method is used to compare one Column with another to determine whether the two Column objects are the same.

Signature.

bool equal
    (
      const Column& column
    ) const

Parameters. equal() takes a single parameter, a reference to an instance of Column.

Return Value. true if the columns being compared are equal, otherwise false.

3.4.2.2.7. `Column::getType()`

Description. This method gets the column's datatype.

Signature.

Type getType
    (
      void
    ) const

Parameters. None.

Return Value. The Type (datatype) of the column. For a list of possible values, see Section 3.4.2.1.3, “Column::Type”.

3.4.2.2.8. `Column::getPrecision()`

Description. This method gets the precision of a column.

Note

This method is applicable to decimal columns only.

Signature.

int getPrecision
    (
      void
    ) const

Parameters. None.

Return Value. The column's precision, as an integer. The precision is defined as the number of significant digits; for more information, see the discussion of the DECIMAL datatype in the Numeric Types section of the MySQL Manual.

3.4.2.2.9. `Column::getScale()`

Description. This method gets the scale used for a decimal column value.

Note

This method is applicable to decimal columns only.

Signature.

int getScale
    (
      void
    ) const

Parameters. None.

Return Value. The decimal column's scale, as an integer. The scale of a decimal column represents the number of digits that can be stored following the decimal point. It is possible for this value to be 0. For more information, see the discussion of the DECIMAL datatype in the Numeric Types section of the MySQL Manual.

3.4.2.2.10. `Column::getLength()`

Description. This method gets the length of a column. This is either the array length for the column or — for a variable length array — the maximum length.

Signature.

int getLength
    (
      void
    ) const

Parameters. None.

Return Value. The (maximum) array length of the column, as an integer.

3.4.2.2.11. `Column::getCharset()`

Description. This gets the character set used by a text column.

Note

This method is applicable only to columns whose Type value is Char, Varchar, or Text.

Signature.

CHARSET_INFO* getCharset
    (
      void
    ) const

Parameters. None.

Return Value. A pointer to a CHARSET_INFO structure specifying both character set and collation. This is the same as a MySQL MY_CHARSET_INFO data structure; for more information, see the description of the MySQL C API function mysql_get_character_set_info() in the MySQL Manual.

3.4.2.2.12. `Column::getInlineSize()`

Description. This method retrieves the inline size of a blob column — that is, the number of initial bytes to store in the table's blob attribute. This part is normally in main memory and can be indexed.

Note

This method is applicable only to blob columns.

Signature.

int getInlineSize
    (
      void
    ) const

Parameters. None.

Return Value. The blob column's inline size, as an integer.

3.4.2.2.13. `Column::getPartSize()`

Description. This method is used to get the part size of a blob column — that is, the number of bytes that are stored in each tuple of the blob table.

Note

This method is applicable to blob columns only.

Signature.

int getPartSize
    (
      void
    ) const

Parameters. None.

Return Value. The column's part size, as an integer. In the case of a Tinyblob column, this value is 0 (that is, only inline bytes are stored).

3.4.2.2.14. `Column::getStripeSize()`

Description. This method gets the stripe size of a blob column — that is, the number of consecutive parts to store in each node group.

Signature.

int getStripeSize
    (
      void
    ) const

Parameters. None.

Return Value. The column's stripe size, as an integer.

3.4.2.2.15. `Column::getSize()`

Description. This function is used to obtain the size of a column.

Signature.

int getSize
    (
      void
    ) const

Parameters. None.

Return Value. The column's size in bytes (an integer value).

3.4.2.2.16. `Column::getPartitionKey()`

Description. This method is used to check whether the column is part of the table's partitioning key.

Note

A partitioning key is a set of attributes used to distribute the tuples onto the NDB nodes. This key a hashing function specific to the NDBCluster storage engine.

An example where this would be useful is an inventory tracking application involving multiple warehouses and regions, where it might be 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. Locally to each fragment the full primary key will still be used with the hashing algorithm in such a case.

For more information about partitioning, partitioning schemes, and partitioning keys in MySQL 5.1, see Partitioning in the MySQL Manual.

Important

The only type of user-defined partitioning that is supported for use with the NDBCluster storage engine in MySQL 5.1 is key partitioning.

Signature.

bool getPartitionKey
    (
      void
    ) const

Parameters. None.

Return Value. true if the column is part of the partitioning key for the table, otherwise false.

3.4.2.2.17. `Column::getArrayType()`

Description. This method gets the column's array type.

Signature.

ArrayType getArrayType
    (
      void
    ) const

Parameters. None.

Return Value. An ArrayType; see Section 3.4.2.1.1, “The Column::ArrayType Type” for possible values.

3.4.2.2.18. `Column::getStorageType()`

Description. This method obtains a column's storage type.

Signature.

StorageType getStorageType
    (
      void
    ) const

Parameters. None.

Return Value. A StorageType value; for more information about this type, see Section 3.4.2.1.2, “The Column::StorageType Type”.

3.4.2.2.19. `Column::setName()`

Description. This method is used to set the name of a column.

Important

setName() is the only Column method whose result is visible from a MySQL Server. MySQL cannot see any other changes made to existing columns using the NDB API.

Signature.

void setName
    (
      const char* name
    )

Parameters. This method takes a single argument — the new name for the column.

Return Value. This method None.

3.4.2.2.20. `Column::setNullable()`

Description. This method allows you to toggle the nullability of a column.

Important

Changes made to columns using this method are not visible to MySQL.

Signature.

void setNullable
    (
      bool nullable
    )

Parameters. A Boolean value. Using true makes it possible to insert NULLs into the column; if nullable is false, then this method performs the equivalent of changing the column to NOT NULL in MySQL.

Return Value. No return value.

3.4.2.2.21. `Column::setPrimaryKey()`

Description. This method is used to make a column part of the table's primary key, or to remove it from the primary key.

Important

Changes made to columns using this method are not visible to MySQL.

Signature.

void setPrimaryKey
    (
      bool primary
    )

Parameters. This method takes a single Boolean value. If it is true, then the column becomes part of the table's primary key; if false, then the column is removed from the primary key.

Return Value. No return value.

3.4.2.2.22. `Column::setType()`

Description. This method sets the Type (datatype) of a column.

Important

setType() resets all column attributes to their (type dependent) default values; it should be the first method that you call when changing the attributes of a given column.

Changes made to columns using this method are not visible to MySQL.

Signature.

void setType
    (
      Type type
    )

Parameters. This method takes a single parameter — the new Column::Type for the column. The default is Unsigned. For a listing of all permitted values, see Section 3.4.2.1.3, “Column::Type”.

Return Value. No return value.

3.4.2.2.23. `Column::setPrecision()`

Description. This method can be used to set the precision of a decimal column.

Important

This method is applicable to decimal columns only.

Changes made to columns using this method are not visible to MySQL.

Signature.

void setPrecision
    (
      int precision
    )

Parameters. This method takes a single parameter — precision is an integer, the value of the column's new precision. For additional information about decimal precision and scale, see Section 3.4.2.2.8, “Column::getPrecision()”, and Section 3.4.2.2.9, “Column::getScale()”.

Return Value. No return value.

3.4.2.2.24. `Column::setScale()`

Description. This method can be used to set the scale of a decimal column.

Important

This method is applicable to decimal columns only.

Changes made to columns using this method are not visible to MySQL.

Signature.

void setScale
    (
      int scale
    )

Parameters. This method takes a single parameter — the integer scale is the new scale for the decimal column. For additional information about decimal precision and scale, see Section 3.4.2.2.8, “Column::getPrecision()”, and Section 3.4.2.2.9, “Column::getScale()”.

Return Value. No return value.

3.4.2.2.25. `Column::setLength()`

Description. This method sets the length of a column. For a variable-length array, this is the maximum length; otherwise it is the array length.

Important

Changes made to columns using this method are not visible to MySQL.

Signature.

void setLength
    (
      int length
    )

Parameters. This method takes a single argument — the integer value length is the new length for the column.

Return Value. No return value.

3.4.2.2.26. `Column::setCharset()`

Description. This method can be used to set the character set and collation of a Char, Varchar, or Text column.

Important

This method is applicable to Char, Varchar, and Text columns only.

Changes made to columns using this method are not visible to MySQL.

Signature.

void setCharset
    (
      CHARSET_INFO* cs
    )

Parameters. This method takes one parameter. cs is a pointer to a CHARSET_INFO structure. For additional information, see Section 3.4.2.2.11, “Column::getCharset()”.

Return Value. No return value.

3.4.2.2.27. `Column::setInlineSize`

Description. This method gets the inline size of a BLOB column — that is, the number of initial bytes to store in the table's blob attribute. This part is normally kept in main memory, and can be indexed and interpreted.

Important

This method is applicable to BLOB columns only.

Changes made to columns using this method are not visible to MySQL.

Signature.

void setInlineSize
    (
      int size
    )

Parameters. The integer size is the new inline size for the BLOB column.

Return Value. No return value.

3.4.2.2.28. `Column::setPartSize()`

Description. This method sets the part size of a BLOB column — that is, the number of bytes to store in each tuple of the BLOB table.

Important

This method is applicable to BLOB columns only.

Changes made to columns using this method are not visible to MySQL.

Signature.

void setPartSize
    (
      int size
    )

Parameters. The integer size is the number of bytes to store in the BLOB table. Using zero for this value allows only inline bytes to be stored, in effect making the column's type TINYBLOB.

Return Value. No return value.

3.4.2.2.29. `Column::setStripeSize()`

Description. This method sets the stripe size of a BLOB column — that is, the number of consecutive parts to store in each node group.

Important

This method is applicable to BLOB columns only.

Changes made to columns using this method are not visible to MySQL.

Signature.

void setStripeSize
    (
      int size
    )

Parameters. This method takes a single argument. The integer size is the new stripe size for the column.

Return Value. No return value.

3.4.2.2.30. `Column::setPartitionKey()`

Description. This method makes it possible to add a column to the partitioning key of the table to which it belongs, or to remove the column from the table's partitioning key.

Important

Changes made to columns using this method are not visible to MySQL.

For additional information, see Section 3.4.2.2.16, “Column::getPartitionKey()”.

Signature.

void setPartitionKey
    (
      bool enable
    )

Parameters. The single parameter enable is a Boolean value. Passing true to this method makes the column part of the table's partitioning key; if enable is false, then the column is removed from the partitioning key.

Return Value. No return value.

3.4.3. The `Object` Class

3.4.3.1. Object Class Enumerated Types
3.4.3.2. Object Class Methods
3.4.3.3. The Datafile Class
3.4.3.4. The Event Class
3.4.3.5. The Index Class
3.4.3.6. The LogfileGroup Class
3.4.3.7. The Table Class
3.4.3.8. The Tablespace Class
3.4.3.9. The Undofile Class

Abstract

This class provides meta-information about database objects such as tables and indexes. Object subclasses model these and other database objects.

Public Methods. The following table lists the public methods of the Object class and the purpose or use of each method:

Method	Purpose / Use
`getObjectStatus()`	Gets an object's status
`getObjectVersion()`	Gets the version of an object
`getObjectId()`	Gets an object's ID

For a detailed discussion of each of these methods, see Section 3.4.3.2, “Object Class Methods”.

Public Types. These are the public types of the Object class:

Type	Purpose / Use
`FragmentType`	Fragmentation type used by the object (a table or index)
`State`	The object's state (whether it is usable)
`Status`	The object's state (whether it is available)
`Store`	Whether the object has been temporarily or permanently stored
`Type`	The object's type (what sort of table, index, or other database object the `Object` represents)

For a discussion of each of these types, along with its possible values, see Section 3.4.3.1, “Object Class Enumerated Types”.

This diagram shows all public members of the Object class:

UML Diagram showing methods of the
Object class.

For a visual representation of Object's subclasses, see Section 3.4, “The NdbDictionary Class”.

3.4.3.1. `Object` Class Enumerated Types

3.4.3.1.1. The Object::FragmentType Type
3.4.3.1.2. The Object::State Type
3.4.3.1.3. The Object::Status Type
3.4.3.1.4. The Object::Store Type
3.4.3.1.5. The Object::Type Type

Abstract

This section details the public enumerated types belonging to the Object class.

3.4.3.1.1. The `Object::FragmentType` Type

Abstract

This type describes the Object's fragmentation type.

Description. This parameter specifies how data in the table or index is distributed among the cluster's storage nodes, that is, the number of fragments per node. The larger the table, the larger the number of fragments that should be used. Note that all replicas count as a single fragment. For a table, the default is FragAllMedium. For a unique hash index, the default is taken from the underlying table and cannot currently be changed.

Enumeration Values.

Value	Description
`FragUndefined`	The fragmentation type is undefined or the default
`FragAllMedium`	Two fragments per node
`FragAllLarge`	Four fragments per node

3.4.3.1.2. The `Object::State` Type

Abstract

This type describes the state of the Object.

Description. This parameter provides us with the object's state. By state, we mean whether or not the object is defined and is in a usable condition.

Enumeration Values.

Value	Description
`StateUndefined`	Undefined
`StateOffline`	Offline, not useable
`StateBuilding`	Building (e.g. restore?), not useable(?)
`StateDropping`	Going offline or being dropped; not usable
`StateOnline`	Online, usable
`StateBackup`	Online, being backed up, usable
`StateBroken`	Broken; should be dropped and re-created

3.4.3.1.3. The `Object::Status` Type

Abstract

This type describes the Object's status.

Description. Reading an object's Status tells whether or not it is available in the NDB kernel.

Enumeration Values.

Value	Description
`New`	The object exists only in memory, and has not yet been created in the `NDB` kernel
`Changed`	The object has been modified in memory, and must be committed in the `NDB` Kernel for changes to take effect
`Retrieved`	The object exists, and has been read into main memory from the `NDB` Kernel
`Invalid`	The object has been invalidated, and should no longer be used
`Altered`	The table has been altered in the `NDB` kernel, but is still available for use

3.4.3.1.4. The `Object::Store` Type

Abstract

This type describes the Object's persistence.

Description. Reading this value tells us is the object is temporary or permanent.

Enumeration Values.

Value	Description
`StoreUndefined`	The object is undefined
`StoreTemporary`	Temporary storage; the object or data will be deleted on system restart
`StorePermanent`	The object or data is permanent; it has been logged to disk

3.4.3.1.5. The `Object::Type` Type

Abstract

This type describes the Object's type.

Description. The Type of the object can be one of several different sorts of index, trigger, tablespace, and so on.

Enumeration Values.

Value	Description
`TypeUndefined`	Undefined
`SystemTable`	System table
`UserTable`	User table (may be temporary)
`UniqueHashIndex`	Unique (but unordered) hash index
`OrderedIndex`	Ordered (but not unique) index
`HashIndexTrigger`	Index maintenance (internal)
`IndexTrigger`	Index maintenance (internal)
`SubscriptionTrigger`	Backup or replication (internal)
`ReadOnlyConstraint`	Trigger (internal)
`Tablespace`	Tablespace
`LogfileGroup`	Logfile group
`Datafile`	Datafile
`Undofile`	Undofile

3.4.3.2. `Object` Class Methods

3.4.3.2.1. Object::getObjectStatus()
3.4.3.2.2. Object::getObjectVersion()
3.4.3.2.3. Object::getObjectId()

Abstract

The sections that follow describe each of the public methods of the Object class.

Important

All 3 of these methods are pure virtual methods, and are reimplemented in the Table, Index, and Event subclasses where needed. See Section 3.4.3.7, “The Table Class”, Section 3.4.3.5, “The Index Class”, and Section 3.4.3.4, “The Event Class”.

3.4.3.2.1. `Object::getObjectStatus()`

Description. This method retrieves the status of the object for which it is invoked.

Signature.

virtual Status getObjectStatus
    (
      void
    ) const

Parameters. None.

Return Value. The current Status of the Object. For possible values, see Section 3.4.3.1.3, “The Object::Status Type”.

3.4.3.2.2. `Object::getObjectVersion()`

Description. The method gets the current version of the object.

Signature.

virtual int getObjectVersion
    (
      void
    ) const

Parameters. None.

Return Value. The object's version number, an integer.

3.4.3.2.3. `Object::getObjectId()`

Description. This method retrieves the object's ID.

Signature.

virtual int getObjectId
    (
      void
    ) const

Parameters. None.

Return Value. The object ID, an integer.

3.4.3.3. The `Datafile` Class

3.4.3.3.1. Datafile Class Methods

Abstract

This section covers the Datafile class.

Description. The Datafile class models a Cluster Disk Data datafile, which is used to store Disk Data table data.

Note

In MySQL 5.1, only unindexed column data can be stored on disk. Indexes and indexes columns continue to be stored in memory as with previous versions of MySQL Cluster.

Versions of MySQL prior to 5.1 do not support Disk Data storage and so do not support datafiles; thus the Datafile class is unavailable for NDB API applications written against these MySQL versions.

Public Methods. The following table lists the public methods of this class and the purpose or use of each method:

Method	Purpose / Use
`Datafile()`	Class constructor
`~Datafile()`	Destructor
`getPath()`	Gets the filesystem path to the datafile
`getSize()`	Gets the size of the datafile
`getFree()`	Gets the amount of free space in the datafile
`getNode()`	Gets the ID of the node where the datafile is located
`getTablespace()`	Gets the name of the tablespace to which the datafile belongs
`getTablespaceId()`	Gets the ID of the tablespace to which the datafile belongs
`getFileNo()`	Gets the number of the datafile in the table space
`getObjectStatus()`	Gets the datafile's object status
`getObjectVersion()`	Gets the datafile's object version
`getObjectId()`	Gets the datafile's object ID
`setPath()`	Sets the name and location of the datafile on the filesystem
`setSize()`	Sets the datafile's size
`setTablespace()`	Sets the tablespace to which the datafile belongs
`setNode()`	Sets the Cluster node where the datafile is to be located

For detailed descriptions, signatures, and examples of use for each of these methods, see Section 3.4.3.3.1, “Datafile Class Methods”.

Public Types. The Datafile class defines no public types.

Class Diagram. This diagram shows all the available methods of the Datafile class:

3.4.3.3.1. `Datafile` Class Methods

3.4.3.3.1.1. Datafile Class Constructor
3.4.3.3.1.2. Datafile::getPath()
3.4.3.3.1.3. Datafile::getSize()
3.4.3.3.1.4. Datafile::getFree()
3.4.3.3.1.5. Datafile::getTablespace()
3.4.3.3.1.6. Datafile::getTablespaceId()
3.4.3.3.1.7. Datafile::getNode()
3.4.3.3.1.8. Datafile::getFileNo()
3.4.3.3.1.9. Datafile::getObjectStatus()
3.4.3.3.1.10. Datafile::getObjectVersion()
3.4.3.3.1.11. Datafile::getObjectId()
3.4.3.3.1.12. Datafile::setPath()
3.4.3.3.1.13. Datafile::setSize()
3.4.3.3.1.14. Datafile::setTablespace()
3.4.3.3.1.15. Datafile::setNode()

Abstract

This section provides descriptions of the public methods of the Datafile class.

3.4.3.3.1.1. `Datafile` Class Constructor

Description. This method creates a new instance of Datafile, or a copy of an existing one.

Signature. To create a new instance:

Datafile
    (
      void
    )

To create a copy of an existing Datafile instance:

Datafile
    (
      const Datafile& datafile
    )

Parameters. New instance: None. Copy constructor: a reference to the Datafile instance to be copied.

Return Value. A Datafile object.

3.4.3.3.1.2. `Datafile::getPath()`

Description. This method returns the filesystem path to the datafile.

Signature.

const char* getPath
    (
      void
    ) const

Parameters. None.

Return Value. The path to the datafile on the data node's filesystem, a string (character pointer).

3.4.3.3.1.3. `Datafile::getSize()`

Description. This method gets the size of the datafile in bytes.

Signature.

Uint64 getSize
    (
      void
    ) const

Parameters. None.

Return Value. The size of the data file, in bytes, as an unsigned 64-bit integer.

3.4.3.3.1.4. `Datafile::getFree()`

Description. This method gets the free space available in the datafile.

Signature.

Uint64 getFree
    (
      void
    ) const

Parameters. None.

Return Value. The number of bytes free in the datafile, as an unsigned 64-bit integer.

3.4.3.3.1.5. `Datafile::getTablespace()`

Description. This method can be used to obtain the name of the tablespace to which the datafile belongs.

Note

You can also access the associated tablespace's ID directly. See Section 3.4.3.3.1.6, “Datafile::getTablespaceId()”.

Signature.

const char* getTablespace
    (
      void
    ) const

Parameters. None.

Return Value. The name of the associated tablespace (as a character pointer).

3.4.3.3.1.6. `Datafile::getTablespaceId()`

Description. This method gets the ID of the tablespace to which the datafile belongs.

Note

You can also access the name of the associated tablespace directly. See Section 3.4.3.3.1.5, “Datafile::getTablespace()”.

Signature.

Uint32 getTablespaceId
    (
      void
    ) const

Parameters. None.

Return Value. The is method returns the tablespace ID as an unsigned 32-bit integer.

3.4.3.3.1.7. `Datafile::getNode()`

Description. This method retrieves the ID of the Cluster node on which the datafile resides.

Signature.

Uint32 getNode
    (
      void
    ) const

Parameters. None.

Return Value. The node ID as an unsigned 32-bit integer.

3.4.3.3.1.8. `Datafile::getFileNo()`

Description. This method gets the number of the file within the associated tablespace.

Signature.

Uint32 getFileNo
    (
      void
    ) const

Parameters. None.

Return Value. The file number, as an unsigned 32-bit integer.

3.4.3.3.1.9. `Datafile::getObjectStatus()`

Description. This method is used to obtain the datafile's object status.

Signature.

virtual Object::Status getObjectStatus
    (
      void
    ) const

Parameters. None.

Return Value. The datafile's Status. See Section 3.4.3.1.3, “The Object::Status Type”.

3.4.3.3.1.10. `Datafile::getObjectVersion()`

Description. This method retrieves the datafile's object version.

Signature.

virtual int getObjectVersion
    (
      void
    ) const

Parameters. None.

Return Value. The datafile's object version, as an integer.

3.4.3.3.1.11. `Datafile::getObjectId()`

Description. This method is used to obtain the object ID of the datafile.

Signature.

virtual int getObjectId
    (
      void
    ) const

Parameters. None.

Return Value. The datafile's object ID, as an integer.

3.4.3.3.1.12. `Datafile::setPath()`

Description. This method sets the path to the datafile on the data node's filesystem.

Signature.

const char* getPath
    (
      void
    ) const

Parameters. The path to the file, a string (as a character pointer).

Return Value. None.

3.4.3.3.1.13. `Datafile::setSize()`

Description. This method sets the size of the datafile.

Signature.

void setSize
    (
      Uint64 size
    )

Parameters. This method takes a single parameter — the desired size in bytes for the datafile, as an unsigned 64-bit integer.

Return Value. None.

3.4.3.3.1.14. `Datafile::setTablespace()`

Description. This method is used to associate the datafile with a tablespace.

Signatures. setTablespace() can be invoked with either the name of the tablespace, as shown here:

void setTablespace
    (
      const char* name
    )

Or with a reference to a Tablespace object.

void setTablespace
    (
      const class Tablespace& tablespace
    )

Parameters. This method takes a single parameter, which can be either one of the following:

The name of the tablespace (as a character pointer).
A reference tablespace to the corresponding Tablespace object.

Return Value. None.

3.4.3.3.1.15. `Datafile::setNode()`

Description. Designates the node to which this datafile belongs.

Signature.

void setNode
    (
      Uint32 nodeId
    )

Parameters. The nodeId of the node on which the datafile is to be located (an unsigned 32-bit integer value).

Return Value. None.

3.4.3.4. The `Event` Class

3.4.3.4.1. Event Types
3.4.3.4.2. Event Class Methods

Abstract

This section discusses the Event class, its methods and defined types.

Description. This class represents a database event in a MySQL Cluster.

Public Methods. The following table lists the public methods of the Event class and the purpose or use of each method:

Method	Purpose / Use
`Event()`	Class constructor
`~Event()`	Destructor
`getName()`	Gets the event's name
`getTable()`	Gets the `Table` object on which the event is defined
`getTableName()`	Gets the name of the table on which the event is defined
`getTableEvent()`	Checks whether an event is to be detected
`getDurability()`	Gets the event's durability
`getReport()`	Gets the event's reporting options
`getNoOfEventColumns()`	Gets the number of columns for which an event is defined
`getEventColumn()`	Gets a column for which an event is defined
`getObjectStatus()`	Gets the event's object status
`getObjectVersion()`	Gets the event's object version
`getObjectId()`	Gets the event's object ID
`setName()`	Sets the event's name
`setTable()`	Sets the `Table` object on which the event is defined
`addTableEvent()`	Adds the type of event that should be detected
`setDurability()`	Sets the event's durability
`setReport()`	The the event's reporting options
`addEventColumn()`	Adds a column on which events should be detected
`addEventColumns()`	Adds multiple columns on which events should be detected
`mergeEvents()`	Stes the event's merge flag

For detailed descriptions, signatures, and examples of use for each of these methods, see Section 3.4.3.4.2, “Event Class Methods”.

Public Types. These are the public types of the Event class:

Type	Purpose / Use
`TableEvent`	Represents the type of a table event
`EventDurability`	Specifies an event's scope, accessibility, and lifetime
`EventReport`	Specifies the reporting option for a table event

For a discussion of each of these types, along with its possible values, see Section 3.4.3.4.1, “Event Types”.

Class Diagram. This diagram shows all the available methods and enumerated types of the Event class:

Public methods and enumerated types of
the Event class.

3.4.3.4.1. `Event` Types

3.4.3.4.1.1. The Event::TableEvent Type
3.4.3.4.1.2. The Event::EventDurability Type
3.4.3.4.1.3. The Event::EventReport Type

Abstract

This section details the public types belonging to the Event class.

3.4.3.4.1.1. The `Event::TableEvent` Type

Abstract

This section describes TableEvent, a type defined by the Event class.

Description. TableEvent is used to classify the types of events that may be associated with tables in the NDB API.

Enumeration Values.

Value	Description
`TE_INSERT`	Insert event on a table
`TE_DELETE`	Delete event on a table
`TE_UPDATE`	Update event on a table
`TE_DROP`	Occurs when a table is dropped
`TE_ALTER`	Occurs when a table definition is changed
`TE_CREATE`	Occurs when a table is created
`TE_GCP_COMPLETE`	Occurs on Cluster failures
`TE_CLUSTER_FAILURE`	Occurs on the completion of a global checkpoint
`TE_STOP`	Occurs when an event operation is stopped
`TE_NODE_FAILURE`	Occurs when a Cluster node fails
`TE_SUBSCRIBE`	Occurs when a cluster node subscribes to an event
`TE_UNSUBSCRIBE`	Occurs when a cluster node unsubscribes from an event
`TE_ALL`	Occurs when any event occurs on a table (not relevant when a specific event is received)

3.4.3.4.1.2. The `Event::EventDurability` Type

Abstract

This section discusses EventDurability, a type defined by the Event class.

Description. The values of this type are used to describe an event's lifetime or persistence as well as its scope.

Enumeration Values.

Value	Description
`ED_UNDEFINED`	The event is undefined or of an unsupported type
`ED_SESSION`	This event persists only for the duration of the current session, and is available only to the current application. It is deleted after the application disconnects or following a cluster restart
`ED_TEMPORARY`	Any application may use the event, but it is deleted following a cluster restart
`ED_PERMANENT`	Any application may use the event, and it persists until deleted by an application — even following a cluster restart

3.4.3.4.1.3. The `Event::EventReport` Type

Abstract

This section discusses EventReport, a type defined by the Event class.

Description. The values of this type are used to specify reporting options for table events.

Enumeration Values.

Value	Description
`ER_UPDATED`	Reporting of update events
`ER_ALL`	Reporting of all events, except for those not resulting in any updates to the inline parts of `BLOB` columns
`ER_SUBSCRIBE`	Reporting of subscription events

3.4.3.4.2. `Event` Class Methods

3.4.3.4.2.1. `Event` Constructor

Description. The Event constructor creates a new instance with a given name, and optionally associated with a table.

Signatures. Name only:

Event
    (
      const char* name
    )

Name and associated table:

Event
    (
      const char*                  name, 
      const NdbDictionary::Table& table
    )

Parameters. At a minimum, a name (as a constant character pointer) for the event is required. Optionally, an event may also be associated with a table; this argument, when present, is a reference to a Table object (see Section 3.4.3.7, “The Table Class”).

Return Value. A new instance of Event.

Destructor. A destructor for this class is supplied as a virtual method which takes no arguments and whose return type is void.

3.4.3.4.2.2. `Event::getName()`

Description. This method obtains the name of the event.

Signature.

const char* getName
    (
      void
    ) const

Parameters. None.

Return Value. The name of the event, as a character pointer.

3.4.3.4.2.3. `Event::getTable()`

Description. This method is used to find the table with which an event is associated. It returns a reference to the corresponding Table object. You may also obtain the name of the table directly using getTableName(). (For details, see Section 3.4.3.4.2.4, “Event::getTableName()”.)

Signature.

const NdbDictionary::Table* getTable
    (
      void
    ) const

Parameters. None.

Return Value. The table with which the event is associated — if there is one — as a pointer to a Table object; otherwise, this method returns NULL. (See Section 3.4.3.7, “The Table Class”.)

3.4.3.4.2.4. `Event::getTableName()`

Description. This method obtains the name of the table with which an event is associated, and can serve as a convenient alternative to getTable(). (See Section 3.4.3.4.2.3, “Event::getTable()”.)

Signature.

const char* getTableName
    (
      void
    ) const

Parameters. None.

Return Value. The name of the table associated with this event, as a character pointer.

3.4.3.4.2.5. `Event::getTableEvent()`

Description. This method is used to check whether a given table event will be detected.

Signature.

bool getTableEvent
    (
      const TableEvent te
    ) const

Parameters. This method takes a single parameter - the table event's type, that is, a TableEvent value. See Section 3.4.3.4.1.1, “The Event::TableEvent Type”, for the list of possible values.

Return Value. This method returns true if events of TableEvent type te will be detected. Otherwise, the return value is false.

3.4.3.4.2.6. `Event::getDurability()`

Description. This method gets the event's lifetime and scope (that is, its EventDurability).

Signature.

EventDurability getDurability
    (
      void
    ) const

Parameters. None.

Return Value. An EventDurability value. See Section 3.4.3.4.1.2, “The Event::EventDurability Type”, for possible values.

3.4.3.4.2.7. `Event::getReport()`

Description. This method is used to obtain the reporting option in force for this event.

Signature.

EventReport getReport
    (
      void
    ) const

Parameters. None.

Return Value. One of the reporting options specified in Section 3.4.3.4.1.3, “The Event::EventReport Type”.

3.4.3.4.2.8. `Event::getNoOfEventColumns()`

Description. This method obtains the number of columns on which an event is defined.

Signature.

int getNoOfEventColumns
    (
      void
    ) const

Parameters. None.

Return Value. The number of columns (as an integer), or -1 in the case of an error.

3.4.3.4.2.9. `Event::getEventColumn()`

Description. This method is used to obtain a specific column from among those on which an event is defined.

Signature.

const Column* getEventColumn
    (
      unsigned no
    ) const

Parameters. The number (no) of the column, as obtained using getNoOfColumns() (see Section 3.4.3.4.2.8, “Event::getNoOfEventColumns()”).

Return Value. A pointer to the Column corresponding to no.

3.4.3.4.2.10. `Event::getObjectStatus()`

Description. This method gets the object status of the event.

Signature.

virtual Object::Status getObjectStatus
    (
      void
    ) const

Parameters. None.

Return Value. The object status of the event — for possible values, see Section 3.4.3.1.3, “The Object::Status Type”.

3.4.3.4.2.11. `Event::getObjectVersion()`

Description. This method gets the event's object version.

Signature.

virtual int getObjectVersion
    (
      void
    ) const

Parameters. None.

Return Value. The object version of the event, as an integer.

3.4.3.4.2.12. `Event::getObjectId()`

Description. This method retrieves an event's object ID.

Signature.

virtual int getObjectId
    (
      void
    ) const

Parameters. None.

Return Value. The object ID of the event, as an integer.

3.4.3.4.2.13. `Event::setName()`

Description. This method is used to set the name of an event. The name must be unique among all events visible from the current application (see Section 3.4.3.4.2.6, “Event::getDurability()”).

Note

You can also set the event's name when first creating it. See Section 3.4.3.4.2.1, “Event Constructor”.

Signature.

void setName
    (
      const char* name
    )

Parameters. The name to be given to the event (as a constant character pointer).

Return Value. None.

3.4.3.4.2.14. `Event::setTable()`

Description. This method defines a table on which events are to be detected.

Note

By default, event detection takes place on all columns in the table. Use addEventColumn() to override this behaviour. For details, see Section 3.4.3.4.2.18, “Event::addEventColumn()”.

Signature.

void setTable
    (
      const NdbDictionary::Table& table
    )

Parameters. This method requires a single parameter, a reference to the table (see Section 3.4.3.7, “The Table Class”) on which events are to be detected.

Return Value. None.

3.4.3.4.2.15. `Event::addTableEvent()`

Description. This method is used to add types of events that should be detected.

Signature.

void addTableEvent
    (
      const TableEvent te
    )

Parameters. This method requires a TableEvent value. See Section 3.4.3.4.1.1, “The Event::TableEvent Type” for possible values.

Return Value. None.

3.4.3.4.2.16. `Event::setDurability()`

Description. This method sets an event's durability — that is, its lifetime and scope.

Signature.

void setDurability(EventDurability ed)

Parameters. This method requires a single EventDurability value as a parameter. See Section 3.4.3.4.1.2, “The Event::EventDurability Type”, for possible values.

Return Value. None.

3.4.3.4.2.17. `Event::setReport()`

Description. This method is used to set a reporting option for an event. Possible option values may be found in Section 3.4.3.4.1.3, “The Event::EventReport Type”.

Signature.

void setReport
    (
      EventReport er
    )

Parameters. An EventReport option value.

Return Value. None.

3.4.3.4.2.18. `Event::addEventColumn()`

Description. This method is used to add a column on which events should be detected. The column may be indicated either by its ID or its name.

Important

You must invoke Dictionary::createEvent() before any errors will be detected. See Section 3.4.1.1.12, “Dictionary::createEvent()”.

Note

If you know several columns by name, you can enable event detection on all of them at one time by using addEventColumns(). See Section 3.4.3.4.2.19, “Event::addEventColumns()”.

Signature. Identifying the event using its column ID:

void addEventColumn
    (
      unsigned attrId
    )

Identifying the column by name:

void addEventColumn
    (
      const char* columnName
    )

Parameters. This method takes a single argument, which may be either one of:

The column ID (attrId), which should be an integer greater than or equal to 0, and less than the value returned by getNoOfEventColumns().
The column's name (as a constant character pointer).

Return Value. None.

3.4.3.4.2.19. `Event::addEventColumns()`

Description. This method is used to enable event detection on several columns at the same time. You must use the names of the columns.

Important

As with addEventColumn(), you must invoke Dictionary::createEvent() before any errors will be detected. See Section 3.4.1.1.12, “Dictionary::createEvent()”.

Signature.

void addEventColumns
    (
      int          n, 
      const char** columnNames
    )

Parameters. This method requires two arguments:

The number of columns n (an integer).
The names of the columns columnNames — this must be passed as a pointer to a character pointer.

Return Value. None.

3.4.3.4.2.20. `Event::mergeEvents()`

Description. This method is used to set the merge events flag, which is false by default. Setting it to true implies that events are merged as follows:

For a given NdbEventOperation associated with this event, events on the same primary key within the same global checkpoint index (GCI) are merged into a single event.
A blob table event is created for each blob attribute, and blob events are handled as part of main table events.
Blob post/pre data from blob part events can be read via NdbBlob methods as a single value.

Note

Currently this flag is not inherited by NdbEventOperation, and must be set on NdbEventOperation explicitly. See Section 3.5, “The NdbEventOperation Class”.

Signature.

void mergeEvents
    (
      bool flag
    )

Parameters. A Boolean flag value.

Return Value. None.

3.4.3.5. The `Index` Class

3.4.3.5.1. The Index::Type Type
3.4.3.5.2. Index Class Methods

Abstract

This section provides a reference to the Index class and its public members.

Description. This class represents an index on an NDB Cluster table column. It is a descendant of the NdbDictionary class, via the Object class. For information on these, see Section 3.4, “The NdbDictionary Class”, and Section 3.4.3, “The Object Class”.

Public Methods. The following table lists the public methods of Index and the purpose or use of each method:

Method	Purpose / Use
`Index()`	Class constructor
`~Index()`	Destructor
`getName()`	Gets the name of the index
`getTable()`	Gets the name of the table being indexed
`getNoOfColumns()`	Gets the number of columns belonging to the index
`getColumn()`	Gets a column making up (part of) the index
`getType()`	Gets the index type
`getLogging()`	Checks whether the index is logged to disk
`getObjectStatus()`	Gets the index object status
`getObjectVersion()`	Gets the index object status
`getObjectId()`	Gets the index object ID
`setName()`	Sets the name of the index
`setTable()`	Sets the name of the table to be indexed
`addColumn()`	Adds a `Column` object to the index
`addColumnName()`	Adds a column by name to the index
`addColumnNames()`	Adds multiple columns by name to the index
`setType()`	Set the index type
`setLogging()`	Enable/disable logging of the index to disk

For detailed descriptions, signatures, and examples of use for each of these methods, see Section 3.4.3.5.2, “Index Class Methods”.

Public Types. Index has one public type, the Type type. For a discussion of Type, see Section 3.4.3.5.1, “The Index::Type Type”.

Class Diagram. This diagram shows all the available methods and enumerated types of the Index class:

Public methods and types of the
Index class.

3.4.3.5.1. The `Index::Type` Type

Description. This is an enumerated type which describes the sort of column index represented by a given instance of Index.

Caution

Do not confuse this enumerated type with Object::Type, which is discussed in Section 3.4.3.1.5, “The Object::Type Type”, or with Table::Type or Column::Type.

Enumeration Values.

Value	Description
`Undefined`	Undefined object type (initial/default value)
`UniqueHashIndex`	Unique unordered hash index (only index type currently supported)
`OrderedIndex`	Non-unique, ordered index

3.4.3.5.2. `Index` Class Methods

3.4.3.5.2.1. Index Class Constructor
3.4.3.5.2.2. Index::getName()
3.4.3.5.2.3. Index::getTable()
3.4.3.5.2.4. Index::getNoOfColumns()
3.4.3.5.2.5. Index::getColumn()
3.4.3.5.2.6. Index::getType()
3.4.3.5.2.7. Index::getLogging()
3.4.3.5.2.8. Index::getObjectStatus()
3.4.3.5.2.9. Index::getObjectVersion()
3.4.3.5.2.10. Index::getObjectId()
3.4.3.5.2.11. Index::setName()
3.4.3.5.2.12. Index::setTable()
3.4.3.5.2.13. Index::addColumn()
3.4.3.5.2.14. Index::addColumnName()
3.4.3.5.2.15. Index::addColumnNames()
3.4.3.5.2.16. Index::setType()
3.4.3.5.2.17. Index::setLogging

Abstract

This section contain descriptions of all public methods of the Index class. This class has relatively few methods (compared to, say, Table), which are fairly straightforward to use.

Important

If you create or change indexes using the NDB API, these modifications cannot be seen by MySQL. The only exception to this is renaming the index using Index::setName().

3.4.3.5.2.1. `Index` Class Constructor

Description. This is used to create an new instance of Index.

Important

Indexes created using the NDB API cannot be seen by the MySQL Server.

Signature.

Index
    (
      const char* name = ""
    )

Parameters. The name of the new index. It is possible to create an index without a name, and then assign a name to it later using setName(). See Section 3.4.3.5.2.11, “Index::setName()”.

Return Value. A new instance of Index.

Destructor. The destructor (~Index()) is supplied as a virtual method.

3.4.3.5.2.2. `Index::getName()`

Description. This method is used to obtain the name of an index.

Signature.

const char* getName
    (
      void
    ) const

Parameters. None.

Return Value. The name of the index, as a constant character pointer.

3.4.3.5.2.3. `Index::getTable()`

Description. This method can be used to obtain the name of the table to which the index belongs.

Signature.

const char* getTable
    (
      void
    ) const

Parameters. None.

Return Value. The name of the table, as a constant character pointer.

3.4.3.5.2.4. `Index::getNoOfColumns()`

Description. This method is used to obtain the number of columns making up the index.

Signature.

unsigned getNoOfColumns
    (
      void
    ) const

Parameters. None.

Return Value. An unsigned integer representing the number of columns in the index.

3.4.3.5.2.5. `Index::getColumn()`

Description. This method retrieves the column at the specified position within the index.

Signature.

const Column* getColumn
    (
      unsigned no
    ) const

Parameters. The ordinal position number no of the column, as an unsigned integer. Use the getNoOfColumns() method to determine how many columns make up the index — see Section 3.4.3.5.2.4, “Index::getNoOfColumns()”, for details.

Return Value. The column having position no in the index, as a pointer to an instance of Column. See Section 3.4.2, “The Column Class”.

3.4.3.5.2.6. `Index::getType()`

Description. This method can be used to find the type of index.

Signature.

Type getType
    (
      void
    ) const

Parameters. None.

Return Value. An index type. See Section 3.4.3.5.1, “The Index::Type Type”, for possible values.

3.4.3.5.2.7. `Index::getLogging()`

Description. Use this method to determine whether logging to disk has been enabled for the index.

Note

Indexes which are not logged are rebuilt when the cluster is started or restarted.

Ordered indexes currently do not support logging to disk; they are rebuilt each time the cluster is started. (This includes restarts.)

Signature.

bool getLogging
    (
      void
    ) const

Parameters. None.

Return Value. A Boolean value:

true: The index is being logged to disk.
false: The index is not being logged.

3.4.3.5.2.8. `Index::getObjectStatus()`

Description. This method gets the object status of the index.

Signature.

virtual Object::Status getObjectStatus
    (
      void
    ) const

Parameters. None.

Return Value. A Status value — see Section 3.4.3.1.3, “The Object::Status Type”, for more information.

3.4.3.5.2.9. `Index::getObjectVersion()`

Description. This method gets the object version of the index.

Signature.

virtual int getObjectVersion
    (
      void
    ) const

Parameters. None.

Return Value. The object version for the index, as an integer.

3.4.3.5.2.10. `Index::getObjectId()`

Description. This method is used to obtain the object ID of the index.

Signature.

virtual int getObjectId
    (
      void 
    ) const

Parameters. None.

Return Value. The object ID, as an integer.

3.4.3.5.2.11. `Index::setName()`

Description. This method sets the name of the index.

Note

This is the only Index::set*() method whose result is visible to a MySQL Server.

Signature.

void setName
    (
      const char* name
    )

Parameters. The desired name for the index, as a constant character pointer.

Return Value. None.

3.4.3.5.2.12. `Index::setTable()`

Description. This method sets the table that is to be indexed. The table is referenced by name.

Signature.

void setTable
    (
      const char* name
    )

Parameters. The name of the table to be indexed, as a constant character pointer.

Return Value. None.

3.4.3.5.2.13. `Index::addColumn()`

Description. This method may be used to add a column to an index.

Note

The order of the columns matches the order in which they are added to the index. However, this matters only with ordered indexes.

Signature.

void addColumn
    (
      const Column& c
    )

Parameters. A reference c to the column which is to be added to the index.

Return Value. None.

3.4.3.5.2.14. `Index::addColumnName()`

Description. This method works in the same way as addColumn(), except that it takes the name of the column as a parameter. See Section 3.4.3.5.2.5, “Index::getColumn()”.

Signature.

void addColumnName
    (
      const char* name
    )

Parameters. The name of the column to be added to the index, as a constant character pointer.

Return Value. None.

3.4.3.5.2.15. `Index::addColumnNames()`

Description. This method is used to add several column names to an index definition at one time.

Note

As with the addColumn() and addColumnName() methods, the indexes are numbered in the order in which they were added. (However, this matters only for ordered indexes.)

Signature.

void addColumnNames
    (
      unsigned     noOfNames, 
      const char** names
    )

Parameters. This method takes two parameters:

The number of columns/names noOfNames to be added to the index.
The names to be added (as a pointer to a pointer).

Return Value. None.

3.4.3.5.2.16. `Index::setType()`

Description. This method is used to set the index type.

Signature.

void setType
    (
      Type type
    )

Parameters. The type of index. For possible values, see Section 3.4.3.5.1, “The Index::Type Type”.

Return Value. None.

3.4.3.5.2.17. `Index::setLogging`

Description. This method is used to enable or disable logging of the index to disk.

Signature.

void setLogging
    (
      bool enable
    )

Parameters. setLogging() takes a single Boolean parameter enable. If enable is true, then logging is enabled for the index; if false, then logging of this index is disabled.

Return Value. None.

3.4.3.6. The `LogfileGroup` Class

3.4.3.6.1. LogfileGroup Class Methods

Abstract

This section discusses the LogfileGroup class, which represents a MySQL Cluster Disk Data logfile group.

Description. This class represents a MySQL Cluster Disk Data logfile group, which is used for storing Disk Data undofiles. For general information about logfile groups and undofiles, see the Cluster Disk Data Storage section of the MySQL Manual.

Note

In MySQL 5.1, only unindexed column data can be stored on disk. Indexes and indexes columns continue to be stored in memory as with previous versions of MySQL Cluster.

Versions of MySQL prior to 5.1 do not support Disk Data storage and so do not support logfile groups; thus the LogfileGroup class is unavailable for NDB API applications written against these MySQL versions.

Public Methods. The following table lists the public methods of this class and the purpose or use of each method:

Method	Purpose / Use
`LogfileGroup()`	Class constructor
`~LogfileGroup()`	Virtual destructor
`getName()`	Retrieves the logfile group's name
`getUndoBufferSize()`	Gets the size of the logfile group's `UNDO` buffer
`getAutoGrowSpecification()`	Gets the logfile group's `AutoGrowSpecification` values
`getUndoFreeWords()`	Retrieves the amount of free space in the `UNDO` buffer
`getObjectStatus()`	Gets the logfile group's object status value
`getObjectVersion()`	Retrieves the logfile group's object version
`getObjectId()`	Get the object ID of the logfile group
`setName()`	Sets the name of the logfile group
`setUndoBufferSize()`	Sets the size of the logfile group's `UNDO` buffer.
`setAutoGrowSpecification()`	Sets `AutoGrowSpecification` values for the logfile group

For detailed descriptions, signatures, and examples of use for each of these methods, see Section 3.4.3.6.1, “LogfileGroup Class Methods”.

Public Types. The LogfileGroup class does not itself define any public types. However, two of its methods make use of the AutoGrowSpecification data structure as a parameter or return value. For more information, see Section 3.4.4, “The AutoGrowSpecification Structure”.

Class Diagram. This diagram shows all the available public methods of the LogfileGroup class:

3.4.3.6.1. `LogfileGroup` Class Methods

3.4.3.6.1.1. LogfileGroup Constructor
3.4.3.6.1.2. LogfileGroup::getName()
3.4.3.6.1.3. LogfileGroup::getUndoBufferSize()
3.4.3.6.1.4. LogfileGroup::getAutoGrowSpecification()
3.4.3.6.1.5. LogfileGroup::getUndoFreeWords()
3.4.3.6.1.6. LogfileGroup::getObjectStatus()
3.4.3.6.1.7. LogfileGroup::getObjectVersion()
3.4.3.6.1.8. LogfileGroup::getObjectId()
3.4.3.6.1.9. LogfileGroup::setName()
3.4.3.6.1.10. LogfileGroup::setUndoBufferSize()
3.4.3.6.1.11. LogfileGroup::setAutoGrowSpecification()

Abstract

This section provides descriptions for the public methods of the LogfileGroup class.

3.4.3.6.1.1. `LogfileGroup` Constructor

Description. The LogfileGroup class has two public constructors, one of which takes no arguments and creates a completely new instance. The other is a copy constructor.

Note

The Dictionary class also supplies methods for creating and destroying LogfileGroup objects. See Section 3.4.1, “The Dictionary Class”.

Signatures. New instance:

LogfileGroup
    (
      void
    )

Copy constructor:

LogfileGroup
    (
      const LogfileGroup& logfileGroup
    )

Parameters. When creating a new instance, the constructor takes no parameters. When copying an existing instance, the constructor is passed a reference to the LogfileGroup instance to be copied.

Return Value. A LogfileGroup object.

Destructor.

virtual ~LogfileGroup
    (
      void
    )

Examples.

[To be supplied...]

3.4.3.6.1.2. `LogfileGroup::getName()`

Description. This method gets the name of the logfile group.

Signature.

const char* getName
    (
      void
    ) const

Parameters. None.

Return Value. The logfile group's name, a string (as a character pointer).

3.4.3.6.1.3. `LogfileGroup::getUndoBufferSize()`

Description. This method retrieves the size of the logfile group's UNDO buffer.

Signature.

Uint32 getUndoBufferSize
    (
      void
    ) const

Parameters. None.

Return Value. The size of the UNDO buffer, in bytes.

3.4.3.6.1.4. `LogfileGroup::getAutoGrowSpecification()`

Description. This method retrieves the AutoGrowSpecification associated with the logfile group.

Signature.

const AutoGrowSpecification& getAutoGrowSpecification
    (
      void
    ) const

Parameters. None.

Return Value. An AutoGrowSpecification data structure. See Section 3.4.4, “The AutoGrowSpecification Structure”, for details.

3.4.3.6.1.5. `LogfileGroup::getUndoFreeWords()`

Description. This method retrieves the number of bytes unused in the logfile group's UNDO buffer.

Signature.

Uint64 getUndoFreeWords
    (
      void
    ) const

Parameters. None.

Return Value. The number of bytes free, as a 64-bit integer.

3.4.3.6.1.6. `LogfileGroup::getObjectStatus()`

Description. This method is used to obtain the object status of the LogfileGroup.

Signature.

virtual Object::Status getObjectStatus
    (
      void
    ) const

Parameters. None.

Return Value. The logfile group's Status — see Section 3.4.3.1.3, “The Object::Status Type” for possible values.

3.4.3.6.1.7. `LogfileGroup::getObjectVersion()`

Description. This method gets the logfile group's object version.

Signature.

virtual int getObjectVersion
    (
      void
    ) const

Parameters. None.

Return Value. The object version of the logfile group, as an integer.

3.4.3.6.1.8. `LogfileGroup::getObjectId()`

Description. This method is used to retrieve the object ID of the logfile group.

Signature.

virtual int getObjectId
    (
      void
    ) const

Parameters. None.

Return Value. The logfile group's object ID (an integer value).

3.4.3.6.1.9. `LogfileGroup::setName()`

Description. This method is used to set a name for the logfile group.

Signature.

void setName
    (
      const char* name
    )

Parameters. The name to be given to the logfile group (character pointer).

Return Value. None.

3.4.3.6.1.10. `LogfileGroup::setUndoBufferSize()`

Description. This method can be used to set the size of the logfile group's UNDO buffer.

Signature.

void setUndoBufferSize
    (
      Uint32 size
    )

Parameters. The size in bytes for the UNDO buffer (using a 32-bit unsigned integer value).

Return Value. None.

3.4.3.6.1.11. `LogfileGroup::setAutoGrowSpecification()`

Description. This method sets to the AutoGrowSpecification data for the logfile group.

Signature.

void setAutoGrowSpecification
    (
      const AutoGrowSpecification& autoGrowSpec
    )

Parameters. The data is passed as a single parameter, an AutoGrowSpecification data structure — see Section 3.4.4, “The AutoGrowSpecification Structure”.

Return Value. None.

3.4.3.7. The `Table` Class

3.4.3.7.1. Table Class Methods

Abstract

This section describes the Table class, which models a database table in the NDB API.

Description. The Table class represents a table in a MySQL Cluster database. This class extends the Object class, which in turn is an inner class of the NdbDictionary class.

Important

It is possible using the NDB API to create tables independently of the MySQL server. However, it is usually not advisable to do so, since tables created in this fashion cannot be seen by the MySQL server. Similarly, it is possible using Table methods to modify existing tables, but these changes (except for renaming tables) are not visible to MySQL.

Calculating Table Sizes. When calculating the data storage one should add the size of all attributes (each attribute consuming a minimum of 4 bytes) and well as 12 bytes overhead. Variable size attributes have a size of 12 bytes plus the actual data storage parts, with an additional overhead based on the size of the variable part. For example, consider a table with 5 attributes: one 64-bit attribute, one 32-bit attribute, two 16-bit attributes, and one array of 64 8-bit attributes. The amount of memory consumed per record by this table is the sum of the following:

8 bytes for the 64-bit attribute
4 bytes for the 32-bit attribute
8 bytes for the two 16-bit attributes, each of these taking up 4 bytes due to right-alignment
64 bytes for the array (64 * 1 byte per array element)
12 bytes overhead

This totals 96 bytes per record. In addition, you should assume an overhead of about 2% for the allocation of page headers and wasted space. Thus, 1 million records should consume 96 MB, and the additional page header and other overhead comes to approximately 2 MB. Rounding up yields 100 MB.

Public Methods. The following table lists the public methods of this class and the purpose or use of each method:

Method	Purpose / Use
`Table()`	Class constructor
`~Table()`	Destructor
`getName()`	Gets the table's name
`getTableId()`	Gets the table's ID
`getColumn()`	Gets a column (by name) from the table
`getLogging()`	Checks whether logging to disk is enabled for this table
`getFragmentType()`	Gets the table's `FragmentType`
`getKValue()`	Gets the table's `KValue`
`getMinLoadFactor()`	Gets the table's minimum load factor
`getMaxLoadFactor()`	Gets the table's maximum load factor
`getNoOfColumns()`	Gets the number of columns in the table
`getNoOfPrimaryKeys()`	Gets the number of primary keys in the table
`getPrimaryKey()`	Gets the name of the table's primary key
`equal()`	Compares the table with another table
`getFrmData()`	Gets the data from the table `.FRM` file
`getFrmLength()`	Gets the length of the table's `.FRM` file
`getFragmentData()`	Gets table fragment data (ID, state, and node group)
`getFragmentDataLen()`	Gets the length of the table fragment data
`getRangeListData()`	Gets a `RANGE` or `LIST` array
`getRangeListDataLen()`	Gets the length of the table `RANGE` or `LIST` array
`getTablespaceData()`	Gets the ID and version of the tablespace containing the table
`getTablespaceDataLen()`	Gets the length of the table's tablespace data
`getLinearFlag()`	Gets the current setting for the table's linear hashing flag
`getFragmentCount()`	Gets the number of fragments for this table
`getTablespace()`	Gets the tablespace containing this table
`getTablespaceNames()`
`getObjectType()`	Gets the table's object type (`Object::Type` as opposed to `Table::Type`)
`getObjectStatus()`	Gets the table's object status
`getObjectVersion()`	Gets the table's object version
`getObjectId()`	Gets the table's object ID
`getMaxRows()`	Gets the maximum number of rows that this table may contain
`getDefaultNoPartitionsFlag()`	Checks whether the default number of partitions is being used
`getRowGCIIndicator()`
`getRowChecksumIndicator()`
`setName()`	Sets the table's name
`addColumn()`	Adds a column to the table
`setLogging()`	Toggle logging of the table to disk
`setLinearFlag()`	Sets the table's linear hashing flag
`setFragmentCount()`	Sets the number of fragments for this table
`setFragmentationType()`	Sets the table's `FragmentType`
`setKValue()`	Set the `KValue`
`setMinLoadFactor()`	Set the table's minimum load factor (`MinLoadFactor`)
`setMaxLoadFactor()`	Set the table's maximum load factor (`MaxLoadFactor`)
`setTablespace()`	Set the tablespace to use for this table
`setStatusInvalid()`
`setMaxRows()`	Sets the maximum number of rows in the table
`setNoDefaultPartitionsFlag()`	Toggles whether the default number of partitions should be used for the table
`setFrm()`	Sets the `.FRM` file to be used for this table
`setFragmentData()`	Sets the fragment ID, node group ID, and fragment state
`setTablespaceNames()`	Sets the tablespace names for fragments
`setTablespaceData()`	Sets the tablespace ID and version
`setRangeListData()`	Sets `LIST` and `RANGE` partition data
`setObjectType()`	Sets the table's object type
`setRowGCIIndicator()`
`setRowChecksumIndicator()`

For detailed descriptions, signatures, and examples of use for each of these methods, see Section 3.4.3.7.1, “Table Class Methods”.

Public Types. The Table class defines no public types.

Class Diagram. This diagram shows all the available methods of the Table class:

3.4.3.7.1. `Table` Class Methods

3.4.3.7.1.1. Table Constructor
3.4.3.7.1.2. Table:getName()
3.4.3.7.1.3. Table::getId()
3.4.3.7.1.4. Table::getColumn()
3.4.3.7.1.5. Table::getLogging()
3.4.3.7.1.6. Table::getFragmentationType()
3.4.3.7.1.7. Table::getKValue()
3.4.3.7.1.8. Table::getMinLoadFactor()
3.4.3.7.1.9. Table::getMaxLoadFactor()
3.4.3.7.1.10. Table::getNoOfCOlumns()
3.4.3.7.1.11. Table::getNoOfPrimaryKeys()
3.4.3.7.1.12. Table::getPrimaryKey()
3.4.3.7.1.13. Table::equal()
3.4.3.7.1.14. Table::getFrmData()
3.4.3.7.1.15. Table::getFrmLength()
3.4.3.7.1.16. Table::getFragmentData()
3.4.3.7.1.17. Table::getFragmentDataLen()
3.4.3.7.1.18. Table::getRangeListData()
3.4.3.7.1.19. Table::getRangeListDataLen()
3.4.3.7.1.20. Table::getTablespaceData()
3.4.3.7.1.21. Table::getTablespaceDataLen()
3.4.3.7.1.22. Table::getLinearFlag()
3.4.3.7.1.23. Table::getFragmentCount()
3.4.3.7.1.24. Table::getTablespace()
3.4.3.7.1.25. Table::getObjectType()
3.4.3.7.1.26. Table::getStatus()
3.4.3.7.1.27. Table::getObjectVersion()
3.4.3.7.1.28. Table::getMaxRows()
3.4.3.7.1.29. Table::getDefaultNoPartitionsFlag()
3.4.3.7.1.30. Table::getObjectId()
3.4.3.7.1.31. Table::getTablespaceNames()
3.4.3.7.1.32. Table::getTablespaceNamesLen()
3.4.3.7.1.33. Table::getRowGCIIndicator()
3.4.3.7.1.34. Table::getRowChecksumIndicator()
3.4.3.7.1.35. Table::setName()
3.4.3.7.1.36. Table::addColumn()
3.4.3.7.1.37. Table::setLogging()
3.4.3.7.1.38. Table::setLinearFlag()
3.4.3.7.1.39. Table::setFragmentCount()
3.4.3.7.1.40. Table::setFragmentType()
3.4.3.7.1.41. Table::setKValue()
3.4.3.7.1.42. Table::setMinLoadFactor()
3.4.3.7.1.43. Table::setMaxLoadFactor()
3.4.3.7.1.44. Table::setTablespace()
3.4.3.7.1.45. Table::setMaxRows()
3.4.3.7.1.46. Table::setDefaultNoPartitionsFlag()
3.4.3.7.1.47. Table::setFrm()
3.4.3.7.1.48. Table::setFragmentData()
3.4.3.7.1.49. Table::setTablespaceNames()
3.4.3.7.1.50. Table::setTablespaceData()
3.4.3.7.1.51. Table::setRangeListData()
3.4.3.7.1.52. Table::setObjectType()
3.4.3.7.1.53. Table::setRowGCIIndicator()
3.4.3.7.1.54. Table::setRowChecksumIndicator()

Abstract

This section discusses the public methods of the Table class.

Note

The assignment (=) operator is overloaded for this class, so that it always performs a deep copy.

Warning

As with other database objects, Table object creation and attribute changes to existing tables done using the NDB API are not visible from MySQL. For example, if you add a new column to a table using Table::addColumn(), MySQL will not see the new column. The only exception to this rule with regard to tables is that you can change the name of an existing table using Table::setName().

3.4.3.7.1.1. `Table` Constructor

Description. Creates a Table instance. There are two version of the Table constructor, one for creating a new instance, and a copy constructor.

Important

Tables created in the NDB API using this method are not accessible from MySQL.

Signature. New instance:

Table
    (
      const char* name = ""
    )

Copy constructor:

Table
    (
      const Table& table
    )

Parameters. For a new instance, the name of the table to be created. For a copy, a reference to the table to be copied.

Return Value. A Table object.

Destructor.

virtual ~Table()

3.4.3.7.1.2. `Table:getName()`

Description. Gets the name of a table.

Signature.

const char* getName
    (
      void
    ) const

Parameters. None.

Return Value. The name of the table (a string).

3.4.3.7.1.3. `Table::getId()`

Description. This method gets a table's ID.

Signature.

int getTableId
    (
      void
    ) const

Parameters. None.

Return Value. An integer.

3.4.3.7.1.4. `Table::getColumn()`

Description. This method is used to obtain a column definition, given either the index or the name of the column.

Signature. Using the column ID:

Column* getColumn
    (
      const int AttributeId
    )

Using the column name:

Column* getColumn
    (
      const char* name
    )

Parameters. Either of: the column's index in the table (as would be returned by the column's getColumnNo() method), or the name of the column.

Return Value. A pointer to the column with the specified index or name. If there is no such column, then this method returns NULL.

3.4.3.7.1.5. `Table::getLogging()`

Description. This class is used to check whether a table is logged to disk — that is, whether it is permanent or temporary.

Signature.

bool getLogging
    (
      void
    ) const

Parameters. None.

Return Value. Returns a Boolean value. If this method returns true, then full checkpointing and logging are done on the table. If false, then the table is a temporary table and is not logged to disk; in the event of a system restart the table still exists and retains its definition, but it will be empty. The default logging value is true.

3.4.3.7.1.6. `Table::getFragmentationType()`

Description. This method gets the table's fragmentation type.

Signature.

FragmentType getFragmentType
    (
      void
    ) const

Parameters. None.

Return Value. A FragmentType value, as defined in Section 3.4.3.1.1, “The Object::FragmentType Type”.

3.4.3.7.1.7. `Table::getKValue()`

Description. This method gets the KValue, a hashing parameter which is currently restricted to the value 6. In a future release, it may become feasible to set this parameter to other values.

Signature.

int getKValue
    (
      void
    ) const

Parameters. None.

Return Value. An integer (currently always 6).

3.4.3.7.1.8. `Table::getMinLoadFactor()`

Description. This method gets the value of the load factor when reduction of the hash table begins. This should always be less than the value returned by getMaxLoadFactor().

Signature.

int getMinLoadFactor
    (
      void
    ) const

Parameters. None.

Return Value. An integer (actually, a percentage expressed as an integer — see Section 3.4.3.7.1.9, “Table::getMaxLoadFactor()”).

3.4.3.7.1.9. `Table::getMaxLoadFactor()`

Description. This method returns the load factor (a hashing parameter) when splitting of the containers in the local hash tables begins.

Signature.

int getMaxLoadFactor
    (
      void
    ) const

Parameters. None.

Return Value. An integer whose maximum value is 100. When the maximum value is returned, this means that memory usage is optimised. Smaller values indicate that less data is stored in each container, which means that keys are found more quickly; however, this also consumes more memory.

3.4.3.7.1.10. `Table::getNoOfCOlumns()`

Description. This method is used to obtain the number of columns in a table.

Signature.

int getNoOfColumns
    (
      void
    ) const

Parameters. None.

Return Value. An integer — the number of columns in the table.

3.4.3.7.1.11. `Table::getNoOfPrimaryKeys()`

Description. This method finds the number of primary key columns in the table.

Signature.

int getNoOfPrimaryKeys
    (
      void
    ) const

Parameters. None.

Return Value. An integer.

3.4.3.7.1.12. `Table::getPrimaryKey()`

Description. This method is used to obtain the name of the table's primary key.

Signature.

const char* getPrimaryKey
    (
      int no
    ) const

Parameters. None.

Return Value. The name of the primary key, a string (character pointer).

3.4.3.7.1.13. `Table::equal()`

Description. This method is used to compare one instance of Table with another.

Signature.

bool equal
    (
      const Table& table
    ) const

Parameters. A reference to the Table object with which the current instance is to be compared.

Return Value. true if the two tables are the same, otherwise false.

3.4.3.7.1.14. `Table::getFrmData()`

Description. The the data from the .FRM file associated with the table.

Signature.

const void* getFrmData
    (
      void
    ) const

Parameters. None.

Return Value. A pointer to the .FRM data.

3.4.3.7.1.15. `Table::getFrmLength()`

Description. Gets the length of the table's .FRM file data, in bytes.

Signature.

Uint32 getFrmLength
    (
      void
    ) const

Parameters. None.

Return Value. The length of the .FRM file data (unsigned 32-bit integer).

3.4.3.7.1.16. `Table::getFragmentData()`

Description. This method gets the table's fragment data (ID, state, and node group).

Signature.

const void* getFragmentData
    (
      void
    ) const

Parameters. None.

Return Value. A pointer to the data to be read.

3.4.3.7.1.17. `Table::getFragmentDataLen()`

Description. Gets the length of the table fragment data to be read, in bytes.

Signature.

Uint32 getFragmentDataLen
    (
      void
    ) const

Parameters. None.

Return Value. The number of bytes to be read, as an unsigned 32-bit integer.

3.4.3.7.1.18. `Table::getRangeListData()`

Description. This method gets the range or list data associated with the table.

Signature.

const void* getRangeListData
    (
      void
    ) const

Parameters. None.

Return Value. A pointer to the data.

3.4.3.7.1.19. `Table::getRangeListDataLen()`

Description. This method gets the size of the table's range or list array.

Signature.

Uint32 getRangeListDataLen
    (
      void
    ) const

Parameters. None.

Return Value. The length of the list or range array, as an integer.

3.4.3.7.1.20. `Table::getTablespaceData()`

Description. This method gets the table's tablespace data (ID and version).

Signature.

const void* getTablespaceData
    (
      void
    ) const

Parameters. None.

Return Value. A pointer to the data.

3.4.3.7.1.21. `Table::getTablespaceDataLen()`

Description. This method is used to get the length of the table's tablespace data.

Signature.

Uint32 getTablespaceDataLen
    (
      void
    ) const

Parameters. None.

Return Value. The length of the data, as a 32-bit unsigned integer.

3.4.3.7.1.22. `Table::getLinearFlag()`

Description. This method retrieves the value of the table's linear hashing flag.

Signature.

bool getLinearFlag
    (
      void
    ) const

Parameters. None.

Return Value. true if the flag is set, and false if it is not.

3.4.3.7.1.23. `Table::getFragmentCount()`

Description. This method gets the number of fragments in the table.

Signature.

Uint32 getFragmentCount
    (
      void
    ) const

Parameters. None.

Return Value. The number of table fragments, as a 32-bit unsigned integer.

3.4.3.7.1.24. `Table::getTablespace()`

Description. This method is used in two ways: to obtain the name of the tablespace to which this table is assigned; to verify that a given tablespace is the one being used by this table.

Signatures. To obtain the name of the tablespace:

const char* getTablespace
    (
      void
    ) const

To determine whether the tablespace is the one indicated by the given ID and version:

bool getTablespace
    (
      Uint32* id      = 0, 
      Uint32* version = 0
    ) const

Parameters. The number and types of parameters depend on how this method is being used:

When used to obtain the name of the tablespace in use by the table, it is called without any arguments.
When used to determine whether the given tablespace is the one being used by this table, then getTablespace() takes two parameters:
1. The tablespace id, given as a pointer to a 32-bit unsigned integer
2. The tablespace version, also given as a pointer to a 32-bit unsigned integer
The default value for both id and version is 0.

Return Value. The return type depends on how the method is called.

When getTablespace() is called without any arguments, it returns a Tablespace object instance. See Section 3.4.3.8, “The Tablespace Class”, for more information.
When called with two arguments, it returns true if the tablespace is the same as the one having the ID and version indicated; otherwise, it returns false.

3.4.3.7.1.25. `Table::getObjectType()`

Description. This method is used to obtain the table's type — that is, its Object::Type value

Signature.

Object::Type getObjectType
    (
      void
    ) const

Parameters. None.

Return Value. Returns a Type value. For possible values, see Section 3.4.3.1.5, “The Object::Type Type”.

3.4.3.7.1.26. `Table::getStatus()`

Description. This method gets the table's status — that is, its Object::Status.

Signature.

virtual Object::Status getObjectStatus
    (
      void
    ) const

Parameters. None.

Return Value. A Status value. For possible values, see Section 3.4.3.1.3, “The Object::Status Type”.

3.4.3.7.1.27. `Table::getObjectVersion()`

Description. This method gets the table's object version.

Signature.

virtual int getObjectVersion
    (
      void
    ) const

Parameters. None.

Return Value. The table's object version, as an integer.

3.4.3.7.1.28. `Table::getMaxRows()`

Description. This method gets the maximum number of rows that the table can hold. This is used for calculating the number of partitions.

Signature.

Uint64 getMaxRows
    (
      void
    ) const

Parameters. None.

Return Value. The maximum number of table rows, as a 64-bit unsigned integer.

3.4.3.7.1.29. `Table::getDefaultNoPartitionsFlag()`

Description. This method is used to find out whether the default number of partitions is used for the table.

Signature.

Uint32 getDefaultNoPartitionsFlag
    (
      void
    ) const

Parameters. None.

Return Value. A 32-bit unsigned integer.

3.4.3.7.1.30. `Table::getObjectId()`

Description. This method gets the table's object ID.

Signature.

virtual int getObjectId
    (
      void
    ) const

Parameters. None.

Return Value. The object ID is returned as an integer.

3.4.3.7.1.31. `Table::getTablespaceNames()`

Description. This method gets a pointer to the names of the tablespaces used in the table fragments.

Signature.

const void* getTablespaceNames
    (
      void
    )

Parameters. None.

Return Value. A pointer to the tablespace name data.

3.4.3.7.1.32. `Table::getTablespaceNamesLen()`

Description. This method gets the length of the tablespace name data returned by getTablespaceNames(). (See Section 3.4.3.7.1.31, “Table::getTablespaceNames()”.)

Signature.

Uint32 getTablespaceNamesLen
    (
      void
    ) const

Parameters. None.

Return Value. The length of the names data, in bytes, as a 32-but unsigned integer.

3.4.3.7.1.33. `Table::getRowGCIIndicator()`

Description.

Signature.

bool getRowGCIIndicator
    (
      void
    ) const

Parameters. None.

Return Value. A true/false value.

3.4.3.7.1.34. `Table::getRowChecksumIndicator()`

Description.

Signature.

bool getRowChecksumIndicator
    (
      void
    ) const

Parameters. None.

Return Value. A true/false value.

3.4.3.7.1.35. `Table::setName()`

Description. This method sets the name of the table.

Note

This is the only set*() method of Table whose effects are visible to MySQL.

Signature.

void setName
    (
      const char* name
    )

Parameters. name is the (new) name of the table.

Return Value. None.

3.4.3.7.1.36. `Table::addColumn()`

Description. Adds a column to a table.

Signature.

void addColumn
    (
      const Column& column
    )

Parameters. A reference to the column which is to be added to the table.

Return Value. None; however, it does create a copy of the original Column object.

3.4.3.7.1.37. `Table::setLogging()`

Description. Toggles the table's logging state. See Section 3.4.3.7.1.5, “Table::getLogging()”.

Signature.

void setLogging
    (
      bool enable
    )

Parameters. If enable is true, then logging for this table is enabled; if it is false, then logging is disabled.

Return Value. None.

3.4.3.7.1.38. `Table::setLinearFlag()`

Description.

Signature.

void setLinearFlag
    (
      Uint32 flag
    )

Parameters. The flag is a 32-bit unsigned integer.

Return Value. None.

3.4.3.7.1.39. `Table::setFragmentCount()`

Description. Sets the number of table fragments.

Signature.

void setFragmentCount
    (
      Uint32 count
    )

Parameters. count is the number of fragments to be used for the table.

Return Value. None.

3.4.3.7.1.40. `Table::setFragmentType()`

Description. This method sets the table's fragmentation type.

Signature.

void setFragmentType
    (
      FragmentType fragmentType
    )

Parameters. This method takes one argument, a FragmentType value. See Section 3.4.3.1.1, “The Object::FragmentType Type”, for more information.

Return Value. None.

3.4.3.7.1.41. `Table::setKValue()`

Description. This sets the KValue, a hashing parameter.

Signature.

void setKValue
    (
      int kValue
    )

Parameters. kValue is an integer. Currently the only permitted value is 6. In a future version this may become a variable parameter.

Return Value. None.

3.4.3.7.1.42. `Table::setMinLoadFactor()`

Description. This method sets the minimum load factor when reduction of the hash table begins.

Signature.

void setMinLoadFactor
    (
      int min
    )

Parameters. This method takes a single parameter min, an integer representation of a percentage (for example, 45 represents 45 percent). For more information, see Section 3.4.3.7.1.8, “Table::getMinLoadFactor()”.

Return Value. None.

3.4.3.7.1.43. `Table::setMaxLoadFactor()`

Description. This method sets the maximum load factor when splitting the containers in the local hash tables.

Signature.

void setMaxLoadFactor
    (
      int max
    )

Parameters. This method takes a single parameter max, an integer representation of a percentage (for example, 45 represents 45 percent). For more information, see Section 3.4.3.7.1.9, “Table::getMaxLoadFactor()”.

Caution

This should never be greater than the minimum load factor.

Return Value. None.

3.4.3.7.1.44. `Table::setTablespace()`

Description. This method sets the tablespace for the table.

Signatures. Using the name of the tablespace:

void setTablespace
    (
      const char* name
    )

Using a Tablespace object:

void setTablespace
    (
      const class Tablespace& tablespace
    )

Parameters. This method can be called with a single argument of either of two types:

The name of the tablespace (a string).
A reference to an existing Tablespace instance.

See Section 3.4.3.8, “The Tablespace Class”.

Return Value. None.

3.4.3.7.1.45. `Table::setMaxRows()`

Description. This method sets the maximum number of rows that can be held by the table.

Signature.

void setMaxRows
    (
      Uint64 maxRows
    )

Parameters. maxRows is a 64-bit unsigned integer that represents the maximum number of rows to be held in the table.

Return Value. None.

3.4.3.7.1.46. `Table::setDefaultNoPartitionsFlag()`

Description. This method sets an indicator that determines whether the default number of partitions is used for the table.

Signature.

void setDefaultNoPartitionsFlag
    (
      Uint32 indicator
    ) const

Parameters. This method takes a single argument indicator, a 32-bit unsigned integer.

Return Value. None.

3.4.3.7.1.47. `Table::setFrm()`

Description. This method is used to write data to this table's .FRM file.

Signature.

void setFrm
    (
      const void* data, 
      Uint32      len
    )

Parameters. This method takes two arguments:

A pointer to the data to be written.
The length (len) of the data.

Return Value. None.

3.4.3.7.1.48. `Table::setFragmentData()`

Description. This method writes an array of fragment information containing the following information:

Fragment ID
Node group ID
Fragment State

Signature.

void setFragmentData
    (
      const void* data, 
      Uint32      len
    )

Parameters. This method takes two parameters:

A pointer to the fragment data to be written
The length (len) of this data, in bytes, as a 32-bit unsigned integer

Return Value. None.

3.4.3.7.1.49. `Table::setTablespaceNames()`

Description. Sets the names of the tablespaces used by the table fragments.

Signature.

void setTablespaceNames
    (
      const void* data 
      Uint32      len
    )

Parameters. This method takes two parameters:

A pointer to the tablespace names data
The length (len) of the names data, as a 32-bit unsigned integer.

Return Value. None.

3.4.3.7.1.50. `Table::setTablespaceData()`

Description. This method sets the tablespace information for each fragment, and includes a tablespace ID and a tablespace version.

Signature.

void setTablespaceData
    (
      const void* data, 
      Uint32      len
    )

Parameters. This method requires two parameters:

A pointer to the data containing the tablespace ID and version
The length (len) of this data, as a 32-bit unsigned integer.

Return Value. None.

3.4.3.7.1.51. `Table::setRangeListData()`

Description. This method sets an array containing information that maps range values and list values to fragments. This is essentially a sorted map consisting of fragment ID/value pairs. For range partitions there is one pair per fragment. For list partitions it could be any number of pairs, but at least as many pairs as there are fragments.

Signature.

void setRangeListData
    (
      const void* data, 
      Uint32      len
    )

Parameters. This method requires two parameters:

A pointer to the range or list data containing the ID/value pairs
The length (len) of this data, as a 32-bit unsigned integer.

Return Value. None.

3.4.3.7.1.52. `Table::setObjectType()`

Description. This method sets the table's object type.

Signature.

void setObjectType
    (
      Object::Type type
    )

Parameters. The desired object type. This must be one of the Type values listed in Section 3.4.3.1.5, “The Object::Type Type”.

Return Value. None.

3.4.3.7.1.53. `Table::setRowGCIIndicator()`

Description.

Signature.

void setRowGCIIndicator
    (
      bool value
    ) const

Parameters. A true/false value.

Return Value. None.

3.4.3.7.1.54. `Table::setRowChecksumIndicator()`

Description.

Signature.

void setRowChecksumIndicator
    (
      bool value
    ) const

Parameters. A true/false value.

Return Value. None.

3.4.3.8. The `Tablespace` Class

3.4.3.8.1. Tablespace Class Methods

Abstract

This section discusses the Tablespace class and its public members.

Description. The Tablespace class models a MySQL Cluster Disk Data tablespace, which contains the datafiles used to store Cluster Disk Data. For an overview of Cluster Disk Data and their characteristics, see CREATE TABLESPACE, in the MySQL Manual.

Note

In MySQL 5.1, only unindexed column data can be stored on disk. Indexes and indexes columns continue to be stored in memory as with previous versions of MySQL Cluster.

Versions of MySQL prior to 5.1 do not support Disk Data storage and so do not support tablespaces; thus the Tablespace class is unavailable for NDB API applications written against these MySQL versions.

Public Methods. The following table lists the public methods of this class and the purpose or use of each method:

Method	Purpose / Use
`Tablespace()`	Class constructor
`~Tablespace()`	Virtual destructor method
`getName()`	Gets the name of the tablespace
`getExtentSize()`	Gets the extent size used by the tablespace
`getAutoGrowSpecification()`	Used to obtain the AutoGrowSpecification structure associated with the tablespace
`getDefaultLogfileGroup()`	Gets the name of the tablespace's default logfile group
`getDefaultLogfileGroupId()`	Gets the ID of the tablespace's default logfile group
`getObjectStatus()`	Used to obtain the `Object::Status` of the `Tablespace` instance for which it is called
`getObjectVersion()`	Gets the object version of the `Tablespace` object for which it is invoked
`getObjectId()`	Gets the object ID of a `Tablespace` instance
`setName()`	Sets the name for the tablespace
`setExtentSize()`	Sets the size of the extents used by the tablespace
`setAutoGrowSpecification()`	Used to set the auto-grow characteristics of the tablespace
`setDefaultLogfileGroup()`	Sets the tablespace's default logfile group

For detailed descriptions, signatures, and examples of use for each of these methods, see Section 3.4.3.8.1, “Tablespace Class Methods”.

Public Types. The Tablespace class defines no public types of its own; however, two of its methods make use of the AutoGrowSpecification data structure. Information about this structure can be found in Section 3.4.4, “The AutoGrowSpecification Structure”.

Class Diagram. This diagram shows all the available methods and enumerated types of the Tablespace class:

3.4.3.8.1. `Tablespace` Class Methods

3.4.3.8.1.1. Tablespace Constructor
3.4.3.8.1.2. Tablespace::getName()
3.4.3.8.1.3. Tablespace::getExtentSize()
3.4.3.8.1.4. Tablespace::getAutoGrowSpecification()
3.4.3.8.1.5. Tablespace::getDefaultLogfileGroup()
3.4.3.8.1.6. Tablespace::getDefaultLogfileGroupId()
3.4.3.8.1.7. Tablespace::getObjectStatus()
3.4.3.8.1.8. Tablespace::getObjectVersion()
3.4.3.8.1.9. Tablespace::getObjectId()
3.4.3.8.1.10. Tablespace::setName()
3.4.3.8.1.11. Tablespace::setExtentSize()
3.4.3.8.1.12. Tablespace::setAutoGrowSpecification()
3.4.3.8.1.13. Tablespace::setDefaultLogfileGroup()

Abstract

This section provides details of the public members of the NDB API's Tablespace class.

3.4.3.8.1.1. `Tablespace` Constructor

Description. These methods are used to create a new instance of Tablespace, or to copy an existing one.

Note

The NdbDictionary::Dictionary class also supplies methods for creating and dropping tablespaces. See Section 3.4.1, “The Dictionary Class”.

Signatures. New instance:

Tablespace
    (
      void
    )

Copy constructor:

Tablespace
    (
      const Tablespace& tablespace
    )

Parameters. New instance: None. Copy constructor: a reference tablespace to an existing Tablespace instance.

Return Value. A Tablespace object.

Destructor. The class defines a virtual destructor ~Tablespace() which takes no arguments and returns no value.

3.4.3.8.1.2. `Tablespace::getName()`

Description. This method retrieves the name of the tablespace.

Signature.

const char* getName
    (
      void
    ) const

Parameters. None.

Return Value. The name of the tablespace, a string value (as a character pointer).

3.4.3.8.1.3. `Tablespace::getExtentSize()`

Description. This method is used to retrieve the extent size — that is the size of the memory allocation units — used by the tablespace.

Note

The same extent size is used for all datafiles contained in a given tablespace.

Signature.

Uint32 getExtentSize
    (
      void
    ) const

Parameters. None.

Return Value. The tablespace's extent size in bytes, as an unsigned 32-bit integer.

3.4.3.8.1.4. `Tablespace::getAutoGrowSpecification()`

Description.

Signature.

const AutoGrowSpecification& getAutoGrowSpecification
    (
      void
    ) const

Parameters. None.

Return Value. A reference to the structure which describes the tablespace auto-grow characteristics — for details, see Section 3.4.4, “The AutoGrowSpecification Structure”.

3.4.3.8.1.5. `Tablespace::getDefaultLogfileGroup()`

Description. This method retrieves the name of the tablespace's default logfile group.

Note

Alternatively, you may wish to obtain the ID of the default logfile group — see Section 3.4.3.8.1.6, “Tablespace::getDefaultLogfileGroupId()”.

Signature.

const char* getDefaultLogfileGroup
    (
      void
    ) const

Parameters. None.

Return Value. The name of the logfile group (string value as character pointer).

3.4.3.8.1.6. `Tablespace::getDefaultLogfileGroupId()`

Description. This method retrieves the ID of the tablespace's default logfile group.

Note

You can also obtain directly the name of the default logfile group rather than its ID — see Section 3.4.3.8.1.5, “Tablespace::getDefaultLogfileGroup()”.

Signature.

Uint32 getDefaultLogfileGroupId
    (
      void
    ) const

Parameters. None.

Return Value. The ID of the logfile group, as an unsigned 32-bit integer.

3.4.3.8.1.7. `Tablespace::getObjectStatus()`

Description. This method is used to retrieve the object status of a tablespace.

Signature.

virtual Object::Status getObjectStatus
    (
      void
    ) const

Parameters. None.

Return Value. An Object::Status value — see Section 3.4.3.1.3, “The Object::Status Type”, for details.

3.4.3.8.1.8. `Tablespace::getObjectVersion()`

Description. This method gets the tablespace object version.

Signature.

virtual int getObjectVersion
  (
    void
  ) const

Parameters. None.

Return Value. The object version, as an integer.

3.4.3.8.1.9. `Tablespace::getObjectId()`

Description. This method retrieves the tablespace's object ID.

Signature.

virtual int getObjectId
    (
      void
    ) const

Parameters. None.

Return Value. The object ID, as an integer.

3.4.3.8.1.10. `Tablespace::setName()`

Description. This method sets the name of the tablespace.

Signature.

void setName
    (
      const char* name
    ) const

Parameters. The name of the tablespace, a string (character pointer).

Return Value. None.

3.4.3.8.1.11. `Tablespace::setExtentSize()`

Description. This method sets the tablespace's extent size.

Signature.

void setExtentSize
    (
      Uint32 size
    )

Parameters. The size to be used for this tablespace's extents, in bytes.

Return Value. None.

3.4.3.8.1.12. `Tablespace::setAutoGrowSpecification()`

Description. This method is used to set the auto-grow characteristics of the tablespace.

Signature.

void setAutoGrowSpecification
    (
      const AutoGrowSpecification& autoGrowSpec
    )

Parameters. This method takes a single parameter, an AutoGrowSpecification data structure. See Section 3.4.4, “The AutoGrowSpecification Structure”.

Return Value. None.

3.4.3.8.1.13. `Tablespace::setDefaultLogfileGroup()`

Description. This method is used to set a tablespace's default logfile group.

Signature. This method can be called in two different ways. The first of these uses the name of the logfile group, as shown here:

void setDefaultLogfileGroup
    (
      const char* name
    )

This method can also be called by passing it a reference to a LogfileGroup object:

void setDefaultLogfileGroup
    (
      const class LogfileGroup& lGroup
    )

Note

There is no method for setting a logfile group as the the default for a tablespace by referencing the logfile group's ID. (In other words, there is no set*() method corresponding to getDefaultLogfileGroupId().)

Parameters. Either the name of the logfile group to be assigned to the tablespace, or a reference lGroup to this logfile group.

Return Value. None.

3.4.3.9. The `Undofile` Class

3.4.3.9.1. Undofile Class Methods

Abstract

The section discusses the Undofile class and its public methods.

Description. The Undofile class models a Cluster Disk Data undofile, which stores data used for rolling back transactions.

Note

In MySQL 5.1, only unindexed column data can be stored on disk. Indexes and indexes columns continue to be stored in memory as with previous versions of MySQL Cluster.

Versions of MySQL prior to 5.1 do not support Disk Data storage and so do not support undofile; thus the Undofile class is unavailable for NDB API applications written against these MySQL versions.

Public Methods. The following table lists the public methods of this class and the purpose or use of each method:

Method	Purpose / Use
`Undofile()`	Class constructor
`~Undofile()`	Virtual destructor
`getPath()`	Gets the undofile's filesystem path
`getSize()`	Gets the size of the undofile
`getLogfileGroup()`	Gets the name of the logfile group to which the undofile belongs
`getLogfileGroupId()`	Gets the ID of the logfile group to which the undofile belongs
`getNode()`	Gets the node where the undofile is located
`getFileNo()`	Gets the number of the undofile in the logfile group
`getObjectStatus()`	Gets the undofile's `Status`
`getObjectVersion()`	Gets the undofile's object version
`getObjectId()`	Gets the undofile's object ID
`setPath()`	Sets the filesystem path for the undofile
`setSize()`	Sets the undofile's size
`setLogfileGroup()`	Sets the undofile's logfile group using the name of the logfile group or a reference to the corresponding `LogfileGroup` object
`setNode()`	Sets the node on which the undofile is located

For detailed descriptions, signatures, and examples of use for each of these methods, see Section 3.4.3.9.1, “Undofile Class Methods”.

Public Types. The Undofile class defines no public types.

Class Diagram. This diagram shows all the available methods of the Undofile class:

3.4.3.9.1. `Undofile` Class Methods

3.4.3.9.1.1.
3.4.3.9.1.2. Undofile::getPath()
3.4.3.9.1.3. Undofile::getSize()
3.4.3.9.1.4. Undofile::getLogfileGroup()
3.4.3.9.1.5. Undofile::getLogfileGroupId()
3.4.3.9.1.6. Undofile::getNode()
3.4.3.9.1.7. Undofile::getFileNo()
3.4.3.9.1.8. Undofile::getObjectStatus()
3.4.3.9.1.9. Undofile::getObjectVersion()
3.4.3.9.1.10. Undofile::getObjectId()
3.4.3.9.1.11. Undofile::setPath()
3.4.3.9.1.12. Undofile::setSize()
3.4.3.9.1.13. Undofile::setLogfileGroup()
3.4.3.9.1.14. Undofile::setNode()

Abstract

This section details the public methods of the Undofile class.

3.4.3.9.1.1.

Description. The class constructor can be used to create a new Undofile instance, or to copy an existing one.

Signatures. Creates a new instance:

Undofile
    (
      void
    )

Copy constructor:

Undofile
    (
      const Undofile& undoFile
    )

Parameters. New instance: None. The copy constructor takes a single argument — a reference to the Undofile object to be copied.

Return Value. An Undofile object.

Destructor. The class defines a virtual destructor which takes no arguments and has the return type void.

3.4.3.9.1.2. `Undofile::getPath()`

Description. This method retrieves the path matching the location of the undofile on the data node's filesystem.

Signature.

const char* getPath
    (
      void
    ) const

Parameters. None.

Return Value. The filesystem path, a string (as a character pointer).

3.4.3.9.1.3. `Undofile::getSize()`

Description. This method gets the size of the undofile in bytes.

Signature.

Uint64 getSize
    (
      void
    ) const

Parameters. None.

Return Value. The size in bytes of the undofile, as an unsigned 64-bit integer.

3.4.3.9.1.4. `Undofile::getLogfileGroup()`

Description. This method retrieves the name of the logfile group to which the undofile belongs.

Signature.

const char* getLogfileGroup
    (
      void
    ) const

Parameters. None.

Return Value. The name of the logfile group, a string value (as a character pointer).

3.4.3.9.1.5. `Undofile::getLogfileGroupId()`

Description. This method retrieves the ID of the logfile group to which the undofile belongs.

Note

It is also possible to obtain the name of the logfile group directly. See Section 3.4.3.9.1.4, “Undofile::getLogfileGroup()”

Signature.

Uint32 getLogfileGroupId
    (
      void
    ) const

Parameters. None.

Return Value. The ID of the logfile group, as an unsigned 32-bit integer.

3.4.3.9.1.6. `Undofile::getNode()`

Description. This method is used to retrieve the node ID of the node where the undofile is located.

Signature.

Uint32 getNode
    (
      void
    ) const

Parameters. None.

Return Value. The node ID, as an unsigned 32-bit integer.

3.4.3.9.1.7. `Undofile::getFileNo()`

Description. The getFileNo() method gets the number of the undofile in the logfile group to which it belongs.

Signature.

Uint32 getFileNo
    (
      void
    ) const

Parameters. None.

Return Value. The number of the undofile, as an unsigned 32-bit integer.

3.4.3.9.1.8. `Undofile::getObjectStatus()`

Description. This method is used to retrieve the object status of an undofile.

Signature.

virtual Object::Status getObjectStatus
    (
      void
    ) const

Parameters. None.

Return Value. An Object::Status value — see Section 3.4.3.1.3, “The Object::Status Type”, for details.

3.4.3.9.1.9. `Undofile::getObjectVersion()`

Description. This method gets the undofile's object version.

Signature.

virtual int getObjectVersion
  (
    void
  ) const

Parameters. None.

Return Value. The object version, as an integer.

3.4.3.9.1.10. `Undofile::getObjectId()`

Description. This method retrieves the undofile's object ID.

Signature.

virtual int getObjectId
    (
      void
    ) const

Parameters. None.

Return Value. The object ID, as an integer.

3.4.3.9.1.11. `Undofile::setPath()`

Description. This method is used to set the filesystem path of the undofile on the data node where it resides.

Signature.

void setPath
    (
      const char* path
    )

Parameters. The desired path to the undofile.

Return Value. None.

3.4.3.9.1.12. `Undofile::setSize()`

Description. Sets the size of the undofile in bytes.

Signature.

void setSize
    (
      Uint64 size
    )

Parameters. The intended size of the undofile in bytes, as an unsigned 64-bit integer.

Return Value. None.

3.4.3.9.1.13. `Undofile::setLogfileGroup()`

Description. Given either a name or an object reference to a logfile group, the setLogfileGroup() method assigns the undofile to that logfile group.

Signature. Using a logfile group name:

void setLogfileGroup
    (
      const char* name
    )

Using a reference to a LogfileGroup instance:

void setLogfileGroup
    (
      const class LogfileGroup & logfileGroup
    )

Parameters. The name of the logfile group (a character pointer), or a reference to a LogfileGroup instance.

Return Value. None.

3.4.3.9.1.14. `Undofile::setNode()`

Description. Sets the node on which the logfile group is to reside.

Signature.

 void setNode
    (
      Uint32 nodeId
    )

Parameters. The nodeId of the data node where the undofile is to be placed; this is an unsigned 32-bit integer.

Return Value. None.

3.4.4. The `AutoGrowSpecification` Structure

Abstract

This section describes the AutoGrowSpecification structure.

Description. The AutoGrowSpecification is a data structure defined in the NdbDictionary class, and is used as a parameter to or return value of some of the methods of the Tablespace and LogfileGroup classes. See Section 3.4.3.8, “The Tablespace Class”, and Section 3.4.3.6, “The LogfileGroup Class”, for more information.

Public Methods. AutoGrowSpecification has the following members, whose types are as shown in the following diagram:

Members of the data structure
AutoGrowSpecification.

The purpose and use of each member can be found in the following table:

Name	Description
`min_free`	???
`max_size`	???
`file_size`	???
`filename_pattern`	???

3.5. The `NdbEventOperation` Class

3.5.1. The NdbEventOperation::State Type
3.5.2. NdbEventOperation Class Methods

Abstract

This section describes the NdbEventOperation class, which is used to monitor changes (events) in a database.

Description. NdbEventOperation represents a database event.

Creating an Instance of NdbEventOperation. This class has no public constructor or destructor. Instead, instances of NdbEventOperation are created as the result of method calls on Ndb and NdbDictionary objects:

There must exist an event which was created using Dictionary::createEvent(). This method returns an instance of the NdbDictionary::Event class. See Section 3.4.1.1.12, “Dictionary::createEvent()”.
An NdbEventOperation object is instantiated using Ndb::createEventOperation(), which acts on instance of NdbDictionary::Event. See Section 3.1.1.9, “Ndb::createEventOperation”.

An instance of this class is removed by invoking Ndb::dropEventOperation. See Section 3.1.1.10, “Ndb::dropEventOperation()”, for more information.

Tip

A detailed example demonstrating creation and removal of event operations is provided in Section 6.5, “NDB API Event Handling Example”.

Limitations. The following limitations apply to this class:

The maximum number of active NdbEventOperation objects is currently fixed at compile time at 100. This may become a configurable parameter in a future release.
The maximum number of NdbEventOperation objects associated with a single event in one process is 16.

Known Issues. The following issues may be encountered when working with event operations in the NDB API:

When several instances of NdbEventOperation are tied to the same event in the same process, they share the circular buffer (set as the bufferLength parameter to Ndb::createEventOperation()), which is therefore the same for all such instances and determined when the first one is instantiated. For this reason, you should make sure to instantiate the “largest” instance first.
Currently, all INSERT, DELETE, and UPDATE events — as well as all attribute changes — are sent to the API, even if only some attributes have been specified. However, these are hidden from the user and only relevant data is shown after calling Ndb::nextEvent().
Note that false exits from Ndb::pollEvents() may occur, and thus the following nextEvent() call returns zero, since there was no available data. In such cases, simply call pollEvents() again.
See Section 3.1.1.11, “Ndb::pollEvents()”, and Section 3.1.1.12, “Ndb::nextEvent()”.
Event code does not check the table schema version. When a table is dropped, make sure that you drop any associated events.
On a replicated Cluster, each event is received multiple times — once for each replica. However, if a node fails, events are no longer received multiple times for data in the corresponding fragment.
Following the failure of a node, not all events will be received any longer. You should drop any associated NdbEventOperation objects and re-create them after once the node is running again.

We intend to remedy these issues in future releases of MySQL Cluster and the NDB API.

Tip

To view the contents of the system table containing created events, you can use the ndb_select_all utility as shown here:

ndb_select_all -d sys 'NDB$EVENTS_0'

Public Methods. The following table lists the public methods of this class and the purpose or use of each method:

Method	Purpose / Use
`getState()`	Gets the current state of the event operation
`getEventType()`	Gets the event type
`getValue()`	Retrieves an attribute value
`getPreValue()`	Retrieves an attribute's previous value
`getBlobHandle()`	Gets a handle for reading blob attributes
`getPreBlobHandle()`	Gets a handle for reading the previous blob attribute
`getGCI()`	Retrieves the GCI of the most recently retrieved event
`getLatestGCI()`	Retrieves the most recent GCI (whether or not the corresponding event has been retrieved)
`getNdbError()`	Gets the most recent error
`isConsistent()`	Detects event loss caused by node failure
`tableNameChanged()`	Checks to see whether the name of a table has changed
`tableFrmChanged()`	Checks to see whether a table `.FRM` file has changed
`tableFragmentationChanged()`	Checks to see whether the fragmentation for a table has changed
`tableRangeListChanged()`	Checks to see whether a table range partition list name has changed
`mergeEvents()`	Allows for events to be merged
`execute()`	Activates the `NdbEventOperation`

For detailed descriptions, signatures, and examples of use for each of these methods, see Section 3.5.2, “NdbEventOperation Class Methods”.

Public Types. NdbEventOperation defines one enumerated type. See Section 3.5.1, “The NdbEventOperation::State Type”, for details.

Class Diagram. This diagram shows all the available methods and enumerated types of the NdbEventOperation class:

Public methods of the
NdbEventOperation class.

3.5.1. The `NdbEventOperation::State` Type

Description. This type describes the event operation's state.

Enumeration Values.

Value	Description
`EO_CREATED`	The event operation has been created, but `execute()` has not yet been called.
`EO_EXECUTING`	The `execute()` method has been invoked for this event operation.
`EO_DROPPED`	The event operation is waiting to be deleted, and is no longer usable.
`EO_ERROR`	An error has occurred, and the event operation is unusable.

A State value is returned by the getState() method. See Section 3.5.2.1, “NdbEventOperation::getState()”, for more information.

3.5.2. `NdbEventOperation` Class Methods

3.5.2.1. NdbEventOperation::getState()
3.5.2.2. NdbEventOperation::getEventType()
3.5.2.3. NdbEventOperation::getValue()
3.5.2.4. NdbEventOperation::getPreValue()
3.5.2.5. NdbEventOperation::getBlobHandle()
3.5.2.6. NdbEventOperation::getPreBlobHandle()
3.5.2.7. NdbEventOperation::getGCI()
3.5.2.8. NdbEventOperation::getLatestGCI()
3.5.2.9. NdbEventOperation::getNdbError()
3.5.2.10. NdbEventOperation::isConsistent()
3.5.2.11. NdbEventOperation::tableNameChanged()
3.5.2.12. NdbEventOperation::tableFrmChanged()
3.5.2.13. NdbEventOperation::tableFragmentationChanged()
3.5.2.14. NdbEventOperation::tableRangeListChanged()
3.5.2.15. NdbEventOperation::mergeEvents()
3.5.2.16. NdbEventOperation::execute()

Abstract

This section contains definitions and descriptions of the public methods of the NdbEventOperation class.

3.5.2.1. `NdbEventOperation::getState()`

Description. This method gets the event operation's current state.

Signature.

State getState
    (
      void
    )

Parameters. None.

Return Value. A State value. See Section 3.5.1, “The NdbEventOperation::State Type”.

3.5.2.2. `NdbEventOperation::getEventType()`

Description. This method is used to obtain the event's type (TableEvent).

Signature.

NdbDictionary::Event::TableEvent getEventType
    (
      void
    ) const

Parameters. None.

Return Value. A TableEvent value. See Section 3.4.3.4.1.1, “The Event::TableEvent Type”.

3.5.2.3. `NdbEventOperation::getValue()`

Description. This method defines the retrieval of an attribute value. The NDB API allocates memory for the NdbRecAttr object that is to hold the returned attribute value.

Important

This method does not fetch the attribute value from the database, and the NdbRecAttr object returned by this method is not readable or printable before calling the execute() method and Ndb::nextEvent() has returned not NULL.

If a specific attribute has not changed, the corresponding NdbRecAttr will be in the state UNDEFINED. This can be checked by using NdbRecAttr::isNULL() which in such cases returns -1.

value Buffer Memory Allocation. It is the application's responsibility to allocate sufficient memory for the value buffer (if not NULL), and this buffer must be aligned appropriately. The buffer is used directly (thus avoiding a copy penalty) only if it is aligned on a 4-byte boundary and the attribute size in bytes (calculated as NdbRecAttr::attrSize() times NdbRecAttr::arraySize()) is a multiple of 4.

Note

getValue() retrieves the current value. Use getPreValue() for retrieving the previous value. See Section 3.5.2.4, “NdbEventOperation::getPreValue()”.

Signature.

NdbRecAttr* getValue
    (
      const char* name, 
      char*       value = 0
    )

Parameters. This method takes two parameters:

The name of the attribute (as a constant character pointer).
A pointer to a value:
- If the attribute value is not NULL, then the attribute value is returned in this parameter.
- If the attribute value is NULL, then the attribute value is stored only in the NdbRecAttr object returned by this method.
See value Buffer Memory Allocation for more information regarding this parameter.

Return Value. An NdbRecAttr object to hold the value of the attribute, or a NULL pointer indicating that an error has occurred. See Section 3.7, “The NdbRecAttr Class”.

3.5.2.4. `NdbEventOperation::getPreValue()`

Description. This method performs identically to getValue(), except that it is used to define a retrieval operation of an attribute's previous value rather than the current value. See Section 3.5.2.3, “NdbEventOperation::getValue()”, for details.

Signature.

NdbRecAttr* getPreValue
    (
      const char* name, 
      char*       value = 0
    )

Parameters. This method takes two parameters:

The name of the attribute (as a constant character pointer).
A pointer to a value:
- If the attribute value is not NULL, then the attribute value is returned in this parameter.
- If the attribute value is NULL, then the attribute value is stored only in the NdbRecAttr object returned by this method.
See value Buffer Memory Allocation for more information regarding this parameter.

Return Value. An NdbRecAttr object to hold the value of the attribute, or a NULL pointer indicating that an error has occurred. See Section 3.7, “The NdbRecAttr Class”.

3.5.2.5. `NdbEventOperation::getBlobHandle()`

Description. This method is used in place of getValue() for blob attributes. The blob handle (NdbBlob)returned by this method supports read operations only.

Note

To obtain the previous value for a blob attribute, use getPreBlobHandle. See Section 3.5.2.6, “NdbEventOperation::getPreBlobHandle()”.

Signature.

NdbBlob* getBlobHandle
    (
      const char* name
    )

Parameters. The name of the blob attribute.

Return Value. A pointer to an NdbBlob object. See Section 3.3, “The NdbBlob Class”.

3.5.2.6. `NdbEventOperation::getPreBlobHandle()`

Description. This function is the same as getBlobHandle(), except that it is used to access the previous value of the blob attribute. See Section 3.5.2.5, “NdbEventOperation::getBlobHandle()”.

Signature.

NdbBlob* getPreBlobHandle
  (
    const char* name
  )

Parameters. The name of the blob attribute.

Return Value. A pointer to an NdbBlob. See Section 3.3, “The NdbBlob Class”.

3.5.2.7. `NdbEventOperation::getGCI()`

Description. This method retrieves the GCI for the most recently retrieved event.

Signature.

Uint64 getGCI
    (
      void
    ) const

Parameters. None.

Return Value. The global checkpoint index of the most recently retrieved event (an integer).

3.5.2.8. `NdbEventOperation::getLatestGCI()`

Description. This method retrieves the most recent GCI.

Note

The GCI obtained using this method is not necessarily associated with an event.

Signature.

Uint64 getLatestGCI
    (
      void
    ) const

Parameters. None.

Return Value. The index of the latest global checkpoint, an integer.

3.5.2.9. `NdbEventOperation::getNdbError()`

Description. This method retrieves the most recent error.

Signature.

const struct NdbError& getNdbError
    (
      void
    ) const

Parameters. None.

Return Value. A reference to an NdbError structure. See Section 4.1, “The NdbError Structure”.

3.5.2.10. `NdbEventOperation::isConsistent()`

Description. This method is used to determine whether event loss has taken place following the failure of a node.

Signature.

bool isConsistent
    (
      void
    ) const

Parameters. None.

Return Value. If event loss has taken place, then this method returns false; otherwise, it returns true.

3.5.2.11. `NdbEventOperation::tableNameChanged()`

Description. This method tests whether a table name has changed as the result of a TE_ALTER table event. (See Section 3.4.3.4.1.1, “The Event::TableEvent Type”.)

Signature.

const bool tableNameChanged
    (
      void
    ) const

Parameters. None.

Return Value. Returns true if the name of the table has changed; otherwise, the method returns false.

3.5.2.12. `NdbEventOperation::tableFrmChanged()`

Description. Use this method to determine whether a table .FRM file has changed in connection with a TE_ALTER event. (See Section 3.4.3.4.1.1, “The Event::TableEvent Type”.)

Signature.

const bool tableFrmChanged
    (
      void
    ) const

Parameters. None.

Return Value. Returns true if the table .FRM file has changed; otherwise, the method returns false.

3.5.2.13. `NdbEventOperation::tableFragmentationChanged()`

Description. This method is used to test whether a table's fragmentation has changed in connection with a TE_ALTER event. (See Section 3.4.3.4.1.1, “The Event::TableEvent Type”.)

Signature.

const bool tableFragmentationChanged
    (
      void
    ) const

Parameters. None.

Return Value. Returns true if the table's fragmentation has changed; otherwise, the method returns false.

3.5.2.14. `NdbEventOperation::tableRangeListChanged()`

Description. Use this method to check whether a table range partition list name has changed in connection with a TE_ALTER event.

Signature.

const bool tableRangeListChanged
    (
      void
    ) const

Parameters. None.

Return Value. This method returns true if range or list partition name has changed; otherwise it returns false.

3.5.2.15. `NdbEventOperation::mergeEvents()`

Description. This method is used to set the merge events flag. For information about event merging, see Section 3.4.3.4.2.20, “Event::mergeEvents()”.

Note

The merge events flag is false by default.

Signature.

void mergeEvents
    (
      bool flag
    )

Parameters. A Boolean flag.

Return Value. None.

3.5.2.16. `NdbEventOperation::execute()`

Description. Activates the NdbEventOperation, so that it can begin receiving events. Changed attribute values may be retrieved after Ndb::nextEvent() has returned not NULL. getValue() or getPreValue() must be called before invoking execute().

Important

Before attempting to use this method, you should have read the explanations provided in Section 3.1.1.12, “Ndb::nextEvent()”, and Section 3.5.2.3, “NdbEventOperation::getValue()”. Also see Section 3.5, “The NdbEventOperation Class”.

Signature.

int execute
    (
      void
    )

Parameters. None.

Return Value. This method returns 0 on success and -1 on failure.

3.6. The `NdbOperation` Class

3.6.1. NdbOperation Types
3.6.2. NdbOperation Class Methods
3.6.3. The NdbIndexOperation Class
3.6.4. The NdbScanOperation Class

Abstract

This section discusses the NdbOperation class. Its subclasses NdbIndexOperation, NdbScanOperation, and NdbIndexScanOperation are described in subsections of this section.

NdbOperation Subclasses. This diagram shows the relationships of NdbOperation, it subclasses, and their public types:

The NdbOperation class
and its subclasses.

Description. NdbOperation represents a “generic” data operation. Its subclasses represent more specific types of operations. See Section 3.6.1.1, “The NdbOperation::Type Type” for a listing of operation types and their corresponding NdbOperation subclasses.

Public Methods. The following table lists the public methods of this class and the purpose or use of each method:

Method	Purpose / Use
`getValue()`	Prepares an attribute value for access
`getBlobHandle()`	Used to access blob attributes
`getTableName()`	Gets the name of the table used for this operation
`getTable()`	Gets the table object used for this operation
`getNdbError()`	Gets the latest error
`getNdbErrorLine()`	Gets the number of the method where the latest error occurred
`getType()`	Gets the type of operation
`getLockMode()`	Gets the operation's lock mode
`equal()`	Defines a search condition using equality
`setValue()`	Defines an attribute to set or update
`insertTuple()`	Adds a new tuple to a table
`updateTuple()`	Updates an existing tuple in a table
`readTuple()`	Reads a tuple from a table
`writeTuple()`	Inserts or updates a tuple
`deleteTuple()`	Removes a tuple from a table

For detailed descriptions, signatures, and examples of use for each of these methods, see Section 3.6.2, “NdbOperation Class Methods”.

Public Types. The NdbOperation class defines two public types, as shown in the following table:

Type	Purpose / Use
`Type`	Operation access types
`LockMode`	The type of lock used when performing a read operation

For a discussion of each of these types, along with its possible values, see Section 3.6.1, “NdbOperation Types”.

Class Diagram. This diagram shows all the available methods and enumerated types of the NdbOperation class:

Public methods and types of the
NdbOperation class.

Note

For more information about the use of NdbOperation, see Section 1.3.2.3.1, “Single-row operations”.

3.6.1. `NdbOperation` Types

3.6.1.1. The NdbOperation::Type Type
3.6.1.2. The NdbOperation::LockMode Type

Abstract

This section details the public types belonging to the NdbOperation class.

3.6.1.1. The `NdbOperation::Type` Type

Description. Type is used to describe the operation access type. Each access type is supported by NdbOperation or one of its subclasses, as shown in the following table:

Enumeration Values.

Value	Description	Class
`PrimaryKeyAccess`	A read, insert, update, or delete operation using the table's primary key	`NdbOperation`
`UniqueIndexAccess`	A read, update, or delete operation using a unique index	`NdbIndexOperation`
`TableScan`	A full table scan	`NdbScanOperation`
`OrderedIndexScan`	An ordered index scan	`NdbIndexScanOperation`

3.6.1.2. The `NdbOperation::LockMode` Type

Description. This type describes the lock mode used when performing a read operation.

Enumeration Values.

Value	Description
`LM_Read`	Read with shared lock
`LM_Exclusive`	Read with exclusive lock
`LM_CommittedRead`	Ignore locks; read last committed

Note

There is also support for dirty reads (LM_Dirty), but this is normally for internal purposes only, and should not be used for applications deployed in a production setting.

3.6.2. `NdbOperation` Class Methods

3.6.2.1. NdbOperation::getValue()
3.6.2.2. NdbOperation::getBlobHandle()
3.6.2.3. NdbOperation::getTableName()
3.6.2.4. NdbOperation::getTable()
3.6.2.5. NdbOperation::getNdbError()
3.6.2.6. NdbOperation::getNdbErrorLine()
3.6.2.7. NdbOperation::getType()
3.6.2.8. NdbOperation::getLockMode()
3.6.2.9. NdbOperation::equal()
3.6.2.10. NdbOperation::setValue()
3.6.2.11. NdbOperation::insertTuple()
3.6.2.12. NdbOperation::readTuple()
3.6.2.13. NdbOperation::writeTuple()
3.6.2.14. NdbOperation::updateTuple()
3.6.2.15. NdbOperation::deleteTuple()

Abstract

This section lists and describes the public methods of the NdbOperation class.

Note

This class has no public constructor. To create an instance of NdbOperation, you must use NdbTransaction::getNdbOperation(). See Section 3.9.2.1, “NdbTransaction::getNdbOperation()”, for more information.

3.6.2.1. `NdbOperation::getValue()`

Description. This method defines the retrieval of an attribute value. The NDB API allocates memory for the NdbRecAttr object that is to hold the returned attribute value.

Important

This method does not fetch the attribute value from the database, and the NdbRecAttr object returned by this method is not readable or printable before calling NdbTransaction::execute().

If a specific attribute has not changed, the corresponding NdbRecAttr will be in the state UNDEFINED. This can be checked by using NdbRecAttr::isNULL() which in such cases returns -1.

See Section 3.9.2.5, “NdbTransaction::execute()”, and Section 3.7.1.4, “NdbRecAttr::isNULL()”.

Signature. There are three versions of this method, each having different parameters:

NdbRecAttr* getValue
    (
      const char* name, 
      char*       value = 0
    )

NdbRecAttr* getValue
    (
      Uint32 id, 
      char*  value = 0
    )

NdbRecAttr* getValue
    (
      const NdbDictionary::Column* col, 
      char*                        value = 0
    )

Parameters. All three forms of this method require two parameters. They differ with regard to the type of the first parameter, which can be any one of the following:

The attribute name
The attribute id
The column on which the attribute is defined

In all three cases, the second parameter is a character buffer in which a non-NULL attribute value is returned. In the event that the attribute is NULL, is it stored only in the NdbRecAttr object returned by this method.

Return Value. An NdbRecAttr object to hold the value of the attribute, or a NULL pointer, indicating an error.

3.6.2.2. `NdbOperation::getBlobHandle()`

Description. This method is used in place of getValue() or setValue() for blob attributes. It creates a blob handle (NdbBlob object). A second call with the same argument returns the previously created handle. The handle is linked to the operation and is maintained automatically. See Section 3.3, “The NdbBlob Class”, for details.

Signature. This method has two forms, depending on whether it is called with the name or the ID of the blob attribute:

virtual NdbBlob* getBlobHandle
    (
      const char* name
    )

virtual NdbBlob* getBlobHandle
    (
      Uint32 id
    )

Parameters. This method takes a single parameter, which can be either one of the following:

The name of the attribute
The id of the attribute

Return Value. Regardless of parameter type used, this method return a pointer to an instance of NdbBlob.

3.6.2.3. `NdbOperation::getTableName()`

Description. This method retrieves the name of the table used for the operation.

Signature.

const char* getTableName
    (
      void
    ) const

Parameters. None.

Return Value. The name of the table.

3.6.2.4. `NdbOperation::getTable()`

Description. This method is used to retrieve the table object associated with the operation.

Signature.

const NdbDictionary::Table* getTable
    (
      void
    ) const

Parameters. None.

Return Value. An instance of Table. For more information, see Section 3.4.3.7, “The Table Class”.

3.6.2.5. `NdbOperation::getNdbError()`

Description. This method gets the most recent error (an NdbError object).

Signature.

const NdbError& getNdbError
    (
      void
    ) const

Parameters. None.

Return Value. An NdbError object. See Section 4.1, “The NdbError Structure”.

3.6.2.6. `NdbOperation::getNdbErrorLine()`

Description. This method retrieves the method number in which the latest error occurred.

Signature.

int getNdbErrorLine
    (
      void
    )

Parameters. None.

Return Value. The method number (an integer).

3.6.2.7. `NdbOperation::getType()`

Description. This method is used to retrieve the access type for this operation.

Signature.

const Type getType
    (
      void
    ) const

Parameters. None.

Return Value. A Type value. See Section 3.6.1.1, “The NdbOperation::Type Type”.

3.6.2.8. `NdbOperation::getLockMode()`

Description. This method gets the operation's lock mode.

Signature.

LockMode getLockMode
    (
      void
    ) const

Parameters. None.

Return Value. A LockMode value. See Section 3.6.1.2, “The NdbOperation::LockMode Type”.

3.6.2.9. `NdbOperation::equal()`

Description. This method define a search condition with an equality. The condition is true if the attribute has the given value. To set search conditions on multiple attributes, use several calls to equal(); in such cases all of them must be satisfied for the tuple to be selected.

Important

If the attribute is of a fixed size, its value must include all bytes. In particular a Char value must be native-blank padded. If the attribute is of variable size, its value must start with 1 or 2 little-endian length bytes (2 if its type is Long*).

Note

When using insertTuple(), you may also define the search key with setValue(). See Section 3.6.2.10, “NdbOperation::setValue()”.

Signature. There are 10 versions of equal(), each having slightly different parameters. All of these are listed here:

int  equal
    (
      const char* name, 
      const char* value
    )

int  equal
    (
      const char* name, 
      Int32       value
    )

int  equal
    (
      const char* name, 
      Uint32      value
    )
  
int  equal
    (
      const char* name, 
      Int64       value
    )

int  equal
    (
      const char* name, 
      Uint64      value
    )
  
int  equal
    (
      Uint32      id, 
      const char* value
    )

int  equal
    (
      Uint32 id, 
      Int32  value
    )

int  equal
    (
      Uint32 id, 
      Uint32 value
    )
  
int  equal
    (
      Uint32 id, 
      Int64  value
    )
  
int  equal
    (
      Uint32 id, 
      Uint64 value
    )

Parameters. This method requires two parameters:

The first parameter can be either of the following:
- The name of the attribute (a string)
- The id of the attribute (an unsigned 32-bit integer)
The second parameter is the attribute value to be tested; it can be any one of the following 5 types:
- String
- 32-bit integer
- Unsigned 32-bit integer
- 64-bit integer
- Unsigned 64-bit integer

Return Value. Returns -1 in the event of an error.

3.6.2.10. `NdbOperation::setValue()`

Description. This method defines an attribute to be set or updated.

Important

There are a number of NdbOperation::setValue() methods that take a certain type as input (pass by value rather than passing a pointer). It is the responsibility of the application programmer to use the correct types.

However, the NDB API does check that the application sends a correct length to the interface as given in the length parameter. A char* value can contain any datatype or any type of array. If the length is not provided, or if it is set to zero, then the API assumes that the pointer is correct, and does not check it.

Tip

To set a NULL value, use the following construct:

setValue("ATTR_NAME", (char*)NULL);

Note

When you use insertTuple(), the NDB API will automatically detect that it is supposed to use equal() instead.

In addition, it is not necessary when using insertTuple() to use setValue() on key attributes before other attributes.

Signature. There are 14 versions of NdbOperation::setValue(), each with slightly different parameters, as listed here (and summarised in the Parameters section following):

int setValue
    (
      const char* name, 
      const char* value
)

int setValue
    (
      const char* name, 
      Int32       value
    )

int setValue
    (
      const char* name, 
      Uint32      value
    )

int setValue
    (
      const char* name, 
      Int64       value
    )

int setValue
    (
      const char* name, 
      Uint64      value
    )

int setValue
    (
      const char* name, 
      float       value
    )

int setValue
    (
      const char* name, 
      double      value
    )

int setValue
    (
      Uint32      id, 
      const char* value
    )

int setValue
    (
      Uint32 id, 
      Int32  value
    )

int setValue
    (
      Uint32 id, 
      Uint32 value
    )

int setValue
    (
      Uint32 id, 
      Int64  value
    )

int setValue
    (
      Uint32 id, 
      Uint64 value
    )

int setValue
    (
      Uint32 id, 
      float  value
    )

int setValue
    (
      Uint32 id, 
      double value
    )

Parameters. This method requires two parameters:

The first parameter identified the attribute to be set, and may be either one of:
- The attribute name (a string)
- The attribute id (an unsigned 32-bit integer)
The second parameter is the value to which the attribute is to be set; its type may be any one of the following 7 types:
- String (const char*)
- 32-bit integer
- Unsigned 32-bit integer
- 64-bit integer
- Unsigned 64-bit integer
- Double
- Float

See Section 3.6.2.9, “NdbOperation::equal()”, for important information regarding the value's format and length.

Return Value. Returns -1 in the event of failure.

3.6.2.11. `NdbOperation::insertTuple()`

Description. This method defines the NdbOperation to be an INSERT operation. When the NdbTransaction::execute() method is called, this operation adds a new tuple to the table. See Section 3.9.2.5, “NdbTransaction::execute()”.

Signature.

virtual int insertTuple
    (
      void
    )

Parameters. None.

Return Value. 0 on success, -1 on failure.

3.6.2.12. `NdbOperation::readTuple()`

Description. This method define the NdbOperation as a READ operation. When the NdbTransaction::execute() method is invoked, the operation reads a tuple. See Section 3.9.2.5, “NdbTransaction::execute()”.

Signature.

virtual int readTuple
    (
      LockMode mode
    )

Parameters. mode specifies the locking mode used by the read operation. See Section 3.6.1.2, “The NdbOperation::LockMode Type”, for possible values.

Return Value. 0 on success, -1 on failure.

3.6.2.13. `NdbOperation::writeTuple()`

Description. This method defines the NdbOperation as a WRITE operation. When the NdbTransaction::execute() method is invoked, the operation writes a tuple to the table. If the tuple already exists, it is updated; otherwise an insert takes place. See Section 3.9.2.5, “NdbTransaction::execute()”.

Signature.

virtual int writeTuple
    (
      void
    )

Parameters. None.

Return Value. 0 on success, -1 on failure.

3.6.2.14. `NdbOperation::updateTuple()`

Description. This method defines the NdbOperation as an UPDATE operation. When the NdbTransaction::execute() method is invoked, the operation updates a tuple found in the table. See Section 3.9.2.5, “NdbTransaction::execute()”.

Signature.

virtual int writeTuple
    (
      void
    )

Parameters. None.

Return Value. 0 on success, -1 on failure.

3.6.2.15. `NdbOperation::deleteTuple()`

Description. This method defines the NdbOperation as a DELETE operation. When the NdbTransaction::execute() method is invoked, the operation deletes a tuple from the table. See Section 3.9.2.5, “NdbTransaction::execute()”.

Signature.

virtual int deleteTuple
    (
      void
    )

Parameters. None.

Return Value. 0 on success, -1 on failure.

3.6.3. The `NdbIndexOperation` Class

3.6.3.1. NdbIndexOperation Class Methods

Abstract

This section describes the NdbIndexOperation class and its public methods.

Description. NdbIndexOperation represents an index operation for use in transactions. This class inherits from NdbOperation; see Section 3.6, “The NdbOperation Class”, for more information.

Public Methods. The following table lists the public methods of this class and the purpose or use of each method:

Method	Purpose / Use
`getIndex()`	Gets the index used by the operation
`readTuple()`	Reads a tuple from a table
`updateTuple()`	Updates an existing tuple in a table
`deleteTuple()`	Removes a tuple from a table

Note

Index operations are not permitted to insert tuples.

For detailed descriptions, signatures, and examples of use for each of these methods, see Section 3.6.2, “NdbOperation Class Methods”.

Public Types. The NdbIndexOperation class defines no public types of its own.

Class Diagram. This diagram shows all the available methods of the NdbIndexOperation class:

Public methods and enumerated types of
the NdbIndexOperation class.

Note

For more information about the use of NdbIndexOperation, see Section 1.3.2.3.1, “Single-row operations”.

3.6.3.1. `NdbIndexOperation` Class Methods

3.6.3.1.1. NdbIndexOperation::getIndex()
3.6.3.1.2. NdbIndexOperation::readTuple()
3.6.3.1.3. NdbIndexOperation::updateTuple()
3.6.3.1.4. NdbIndexOperation::deleteTuple()

Abstract

This section lists and describes the public methods of the NdbIndexOperation class.

Note

This class has no public constructor. To create an instance of NdbIndexOperation, it is necessary to use the NdbTransaction::getNdbIndexOperation() method. See Section 3.9.2.4, “NdbTransaction::getNdbIndexOperation()”.

3.6.3.1.1. `NdbIndexOperation::getIndex()`

Description.

Signature.

const NdbDictionary::Index* getIndex
    (
      void
    ) const

Parameters. None.

Return Value. A pointer to an Index object. See Section 3.4.3.5, “The Index Class”.

3.6.3.1.2. `NdbIndexOperation::readTuple()`

Description. This method define the NdbIndexOperation as a READ operation. When the NdbTransaction::execute() method is invoked, the operation reads a tuple. See Section 3.9.2.5, “NdbTransaction::execute()”.

Signature.

int readTuple
    (
      LockMode mode
    )

Parameters. mode specifies the locking mode used by the read operation. See Section 3.6.1.2, “The NdbOperation::LockMode Type”, for possible values.

Return Value. 0 on success, -1 on failure.

3.6.3.1.3. `NdbIndexOperation::updateTuple()`

Description. This method defines the NdbIndexOperation as an UPDATE operation. When the NdbTransaction::execute() method is invoked, the operation updates a tuple found in the table. See Section 3.9.2.5, “NdbTransaction::execute()”.

Signature.

int writeTuple
    (
      void
    )

Parameters. None.

Return Value. 0 on success, -1 on failure.

3.6.3.1.4. `NdbIndexOperation::deleteTuple()`

Description. This method defines the NdbIndexOperation as a DELETE operation. When the NdbTransaction::execute() method is invoked, the operation deletes a tuple from the table. See Section 3.9.2.5, “NdbTransaction::execute()”.

Signature.

int deleteTuple
    (
      void
    )

Parameters. None.

Return Value. 0 on success, -1 on failure.

3.6.4. The `NdbScanOperation` Class

3.6.4.1. The NdbScanOperation::ScanFlag Type
3.6.4.2. NdbScanOperation Class Methods
3.6.4.3. The NdbIndexScanOperation Class

Abstract

This section describes the NdbScanOperation class and its class members.

Description. The NdbScanOperation class represents a scanning operation used in a transaction. This class inherits from NdbOperation. For more information, see Section 3.6, “The NdbOperation Class”.

Public Methods. The following table lists the public methods of this class and the purpose or use of each method:

Method	Purpose / Use
`readTuples()`	Reads tuples
`nextResult()`	Gets the next tuple
`close()`	Closes the scan
`lockCurrentTuple()`	Locks the current tuple
`updateCurrentTuple()`	Updates the current tuple
`deleteCurrentTuple()`	Deletes the current tuple
`restart()`	Restarts the scan

For detailed descriptions, signatures, and examples of use for each of these methods, see Section 3.6.4.2, “NdbScanOperation Class Methods”.

Public Types. This class defines a single public type ScanFlag. See Section 3.6.4.1, “The NdbScanOperation::ScanFlag Type”, for details.

Class Diagram. This diagram shows all the available members of the NdbScanOperation class:

Public members of the
NdbScanOperation class.

Note

For more information about the use of NdbScanOperation, see Section 1.3.2.3.2, “Scan Operations”, and Section 1.3.2.3.3, “Using Scans to Update or Delete Rows”

3.6.4.1. The `NdbScanOperation::ScanFlag` Type

Description. Values of this type are the scan flags used with the readTuples() method. More than one may be used, in which case, they are OR'ed together as the second argument to that method. See Section 3.6.4.2.1, “NdbScanOperation::readTuples()”, for more information.

Enumeration Values.

Value	Description
`SF_TupScan`	TUP scan
`SF_OrderBy`	Ordered index scan (ascending)
`SF_Descending`	Ordered index scan (descending)
`SF_ReadRangeNo`	Enables `NdbIndexScanOperation::get_range_no()`
`SF_KeyInfo`	Requests `KeyInfo` to be sent back to the caller

3.6.4.2. `NdbScanOperation` Class Methods

3.6.4.2.1. NdbScanOperation::readTuples()
3.6.4.2.2. NdbScanOperation::nextResult()
3.6.4.2.3. NdbScanOperation::close()
3.6.4.2.4. NdbScanOperation::lockCurrentTuple()
3.6.4.2.5. NdbScanOperation::updateCurrentTuple()
3.6.4.2.6. NdbScanOperation::deleteCurrentTuple()
3.6.4.2.7. NdbScanOperation::restart()

Abstract

This section lists and describes the public methods of the NdbScanOperation class.

Note

This class has no public constructor. To create an instance of NdbScanOperation, it is necessary to use the NdbTransaction::getNdbScanOperation() method. See Section 3.9.2.2, “NdbTransaction::getNdbScanOperation()”.

3.6.4.2.1. `NdbScanOperation::readTuples()`

Description. This method is used to perform a scan.

Signature.

virtual int readTuples
    (
      LockMode mode = LM_Read, 
      Uint32   flags = 0, 
      Uint32   parallel = 0,
      Uint32   batch = 0
    )

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

The lock mode; this is a LockMode value as described in Section 3.6.1.2, “The NdbOperation::LockMode Type”.
One or more ScanFlag values. Multiple values are OR'ed together
The number of fragments to scan in parallel; use 0 to require that the maximum possible number be used.
The batch parameter specifies how many records will be returned to the client from the server by the next NdbScanOperation::nextResult(true) method call. Use 0 to specify the maximum automatically.
Note
This parameter was ignored prior to MySQL 5.1.12, and the maximum was used. (Bug#20252)

Return Value. 0 on success, -1 on failure.

3.6.4.2.2. `NdbScanOperation::nextResult()`

Description. This method is used to fetch the next tuple in a scan transaction. Following each call to nextResult(), the buffers and NdbRecAttr objects defined in NdbOperation::getValue() are updated with values from the scanned tuple.

Signature.

int nextResult
    (
      bool fetchAllowed = true, 
      bool forceSend = false
    )

Parameters. This method takes two parameters:

Normally, the NDB API contacts the NDB kernel for more tuples whenever it is necessary; setting fetchAllowed to false keeps this from happening.
Disabling fetchAllowed by setting it to false forces NDB to process any records it already has in its caches. When there are no more cached records it returns 2. You must then call nextResult() with fetchAllowed equal to true in order to contact NDB for more records.
While nextResult(false) returns 0, you should transfer the record to another transaction. When nextResult(false) returns 2, you must execute and commit the other transaction. This causes any locks to be transferred to the other transaction, updates or deletes to be made, and then, the locks to be released. Following this, call nextResult(true) — this fetches more records and caches them in the NDB API.
Note
If you do not transfer the records to another transaction, the locks on those records will be released the next time that the NDB Kernel is contacted for more records.
Disabling fetchAllowed can be useful when you want to update or delete all of the records obtained in a given transaction, as doing so saves time and speeds up updates or deletes of scanned records.
forceSend defaults to false, and can normally be omitted. However, setting this parameter to true means that transactions are sent immediately. See Section 1.3.4, “The Adaptive Send Algorithm”, for more information.

Return Value. This method returns one of the following 4 integer values:

-1: Indicates that an error has occurred.
0: Another tuple has been received.
1: There are no more tuples to scan.
2: There are no more cached records (invoke nextResult(true) to fetch more records).

3.6.4.2.3. `NdbScanOperation::close()`

Description. Calling this method closes a scan.

Signature.

void close
    (
      bool forceSend = false, 
      bool releaseOp = false
    )

Parameters. This method takes two parameters:

forceSend defaults to false; call close() with this parameter set to true in order to force transactions to be sent.
releaseOp also defaults to false; set to true in order to release the operation.

Return Value. None.

3.6.4.2.4. `NdbScanOperation::lockCurrentTuple()`

Description. This method locks the current tuple.

Signature.

NdbOperation* lockCurrentTuple
    (
      void
    )

NdbOperation* lockCurrentTuple
    (
      NdbTransaction* lockTrans
    )

Parameters. This method takes a single, optional parameter — the transaction that should perform the lock. If this is omitted, the transaction is the current one.

Return Value. This method returns an NdbTransaction object or NULL. (See Section 3.9, “The NdbTransaction Class”.)

3.6.4.2.5. `NdbScanOperation::updateCurrentTuple()`

Description. This method is used to update the current tuple.

Signature.

NdbOperation* updateCurrentTuple
    (
      void
    )

NdbOperation* updateCurrentTuple
    (
      NdbTransaction* updateTrans
    )

Parameters. This method takes a single, optional parameter — the transaction that should perform the lock. If this is omitted, the transaction is the current one.

Return Value. This method returns an NdbTransaction object or NULL. (See Section 3.9, “The NdbTransaction Class”.)

3.6.4.2.6. `NdbScanOperation::deleteCurrentTuple()`

Description. This method is used to delete the current tuple.

Signature.

int deleteCurrentTuple
    (
      void
    )

int deleteCurrentTuple
    (
      NdbTransaction* takeOverTransaction
    )

Parameters. This method takes a single, optional parameter — the transaction that should perform the lock. If this is omitted, the transaction is the current one.

Return Value. 0 on success, -1 on failure.

3.6.4.2.7. `NdbScanOperation::restart()`

Description. Use this method to restart a scan without changing any of its getValue() calls or search conditions.

Signature.

int restart
    (
      bool forceSend = false
    )

Parameters. Call this method with forceSend set to true in order to force the transaction to be sent.

Return Value. 0 on success, -1 on failure.

3.6.4.3. The `NdbIndexScanOperation` Class

3.6.4.3.1. The NdbIndexScanOperation::BoundType Type
3.6.4.3.2. NdbIndexScanOperation Class Methods

Abstract

This section discusses the NdbIndexScanOperation class and its public members.

Description. The NdbIndexScanOperation class represents a scan operation using an ordered index. This class inherits from NdbScanOperation and NdbOperation. See Section 3.6.4, “The NdbScanOperation Class”, and Section 3.6, “The NdbOperation Class”, for more information about these classes.

Public Methods. The following table lists the public methods of this class and the purpose or use of each method:

Method	Purpose / Use
`get_range_no()`	Gets the range number for the current row
`getSorted()`	Checks whether the current scan is sorted
`getDescending()`	Checks whether the current scan is sorted
`readTuples()`	Reads tuples using an ordered index
`setBound()`	Defines a bound on the index key for a range scan
`reset_bounds()`	Resets bounds, puts the operation in the send queue
`end_of_bound()`	Marks the end of a bound

For detailed descriptions, signatures, and examples of use for each of these methods, see Section 3.6.4.3.2, “NdbIndexScanOperation Class Methods”.

Public Types. The NdbIndexScanOperation class defines one public type. See Section 3.6.4.3.1, “The NdbIndexScanOperation::BoundType Type”.

Class Diagram. This diagram shows all the public members of the NdbIndexScanOperation class:

Note

For more information about the use of NdbIndexScanOperation, see Section 1.3.2.3.2, “Scan Operations”, and Section 1.3.2.3.3, “Using Scans to Update or Delete Rows”

3.6.4.3.1. The `NdbIndexScanOperation::BoundType` Type

Description. This type is used to describe an ordered key bound.

Tip

The numeric values are fixed in the API and can be used explicitly — in other words, it is “safe” to calculate the values and use them.

Enumeration Values.

Value	Numeric Value	Description
`BoundLE`	`0`	Lower bound
`BoundLT`	`1`	Strict lower bound
`BoundGE`	`2`	Upper bound
`BoundGT`	`3`	Strict upper bound
`BoundEQ`	`4`	Equality

3.6.4.3.2. `NdbIndexScanOperation` Class Methods

3.6.4.3.2.1. NdbIndexScanOperation::get_range_no()
3.6.4.3.2.2. NdbIndexScanOperation::getSorted()
3.6.4.3.2.3. NdbIndexScanOperation::getDescending()
3.6.4.3.2.4. NdbIndexScanOperation::readTuples()
3.6.4.3.2.5. NdbIndexScanOperation::setBound
3.6.4.3.2.6. NdbIndexScanOperation::reset_bounds()
3.6.4.3.2.7. NdbIndexScanOperation::end_of_bound()

Abstract

This section lists and describes the public methods of the NdbIndexScanOperation class.

3.6.4.3.2.1. `NdbIndexScanOperation::get_range_no()`

Description. This method returns the range number for the current row.

Signature.

int get_range_no
    (
      void
    )

Parameters. None.

Return Value. The range number (an integer).

3.6.4.3.2.2. `NdbIndexScanOperation::getSorted()`

Description. This method is used to check whether the scan is sorted.

Signature.

bool getSorted
    (
      void
    ) const

Parameters. None.

Return Value. true if the scan is sorted, otherwise false.

3.6.4.3.2.3. `NdbIndexScanOperation::getDescending()`

Description. This method is used to check whether the scan is descending.

Signature.

bool getDescending
    (
      void
    ) const

Parameters. None.

Return Value. This method returns true if the scan is sorted in descending order; otherwise, it returns false.

3.6.4.3.2.4. `NdbIndexScanOperation::readTuples()`

Description. This method is used to read tuples, using an ordered index.

Signature.

virtual int readTuples
    (
      LockMode mode = LM_Read, 
      Uint32   flags = 0, 
      Uint32   parallel = 0,
      Uint32   batch = 0
      
    )

Parameters. The readTuples() method takes 3 parameters, as listed here:

The lock mode used for the scan. This is a LockMode value; see Section 3.6.1.2, “The NdbOperation::LockMode Type” for more information, including permitted values.
One or more scan flags; multiple flags are OR'ed together as they are when used with NdbScanOperation::readTuples(). See Section 3.6.4.1, “The NdbScanOperation::ScanFlag Type” for possible values.
The number of fragments to scan in parallel; use 0 to specify the maximum automatically.
The batch parameter specifies how many records will be returned to the client from the server by the next NdbScanOperation::nextResult(true) method call. Use 0 to specify the maximum automatically.
Note
This parameter was ignored prior to MySQL 5.1.12, and the maximum was used.(Bug#20252)

Return Value. An integer: 0 indicates success; -1 indicates failure.

3.6.4.3.2.5. `NdbIndexScanOperation::setBound`

Description. This method defines a bound on an index key used in a range scan.

Each index key can have a lower bound, upper bound, or both. Setting the key equal to a value defines both upper and lower bounds. Bounds can be defined in any order. Conflicting definitions gives rise to an error.

Bounds must be set on initial sequences of index keys, and all but possibly the last bound must be non-strict. This means, for example, that “a >= 2 AND b > 3” is permissible, but “a > 2 AND b >= 3” is not.

The scan may currently return tuples for which the bounds are not satisfied. For example, a <= 2 && b <= 3 not only scans the index up to (a=2, b=3), but also returns any (a=1, b=4) as well.

When setting bounds based on equality, it is better to use BoundEQ instead of the equivalent pair BoundLE and BoundGE. This is especially true when the table partition key is a prefix of the index key.

NULL is considered less than any non-NULL value and equal to another NULL value. To perform comparisons with NULL, use setBound() with a null pointer (0).

An index also stores all-NULL keys as well, and performing an index scan with an empty bound set returns all tuples from the table.

Signature.

int setBound
    (
      const char* name, 
      int         type, 
      const void* value
    )

int setBound
    (
      Uint32      id, 
      int         type, 
      const void* value
    )

Parameters. This method takes 3 parameters:

Either the name or the id of the attribute on which the bound is to be set.
The bound type — see Section 3.6.4.3.1, “The NdbIndexScanOperation::BoundType Type”.
A pointer to the bound value (use 0 for NULL).

Return Value. Returns 0 on success, -1 on failure.

3.6.4.3.2.6. `NdbIndexScanOperation::reset_bounds()`

Description. Reset the bounds, and put the operation into the list that will be sent on the next NdbTransaction::execute() call.

Signature.

int reset_bounds
    (
      bool forceSend = false
    )

Parameters. Set forceSend to true in order to force the operation to be sent immediately.

Return Value. 0 on success, -1 on failure.

3.6.4.3.2.7. `NdbIndexScanOperation::end_of_bound()`

Description. This method is used to mark the end of a bound; used when batching index reads (that is, when employing multiple ranges).

Signature.

int end_of_bound
    (
      Uint32 range_no
    )

Parameters. The number of the range on which the bound occurs.

Return Value. 0 indicates success; -1 indicates failure.

3.7. The `NdbRecAttr` Class

3.7.1. NdbRecAttr Class Methods

Abstract

The section describes the NdbRecAttr class and its public methods.

Description. NdbRecAttr contains the value of an attribute. An NdbRecAttr object is used to store an attribute value after it has been retrieved the NDB Cluster using the NdbOperation::getValue(). This object is allocated by the NDB API. A brief example is shown here:

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

if(MyRecAttr == NULL) goto error;
 
if(MyTransaction->execute(Commit) == -1)
  goto error;

ndbout << MyRecAttr->u_32_value();

For more examples, see Section 6.1, “Using Synchronous Transactions”.

Note

An NdbRecAttr object is instantiated with its value when NdbTransaction::execute() is invoked. Prior to this, the value is undefined. (Use NdbRecAttr::isNULL() to check whether the value is defined.) This means that an NdbRecAttr object has valid information only between the times that NdbTransaction::execute() and Ndb::closeTransaction() are called. The value of the null indicator is -1 until NdbTransaction::execute() method is invoked.

Public Methods. NdbRecAttr has a number of methods for retrieving values of various simple types directly from an instance of this class. To obtain a reference to the value, use NdbRecAttr::aRef(). The following table lists all of the public methods of this class and the purpose or use of each method:

Method	Purpose / Use
`getColumn()`	Gets the column to which the attribute belongs
`getType()`	Gets the attribute's type (`Column::Type`)
`get_size_in_bytes()`	Gets the size of the attribute, in bytes
`isNULL()`	Tests whether the attribute is `NULL`
`int64_value()`	Retrieves the attribute value, as a 64-bit integer
`int32_value()`	Retrieves the attribute value, as a 32-bit integer
`short_value()`	Retrieves the attribute value, as a short integer
`char_value()`	Retrieves the attribute value, as a `char`
`u_64_value()`	Retrieves the attribute value, as an unsigned 64-bit integer
`u_32_value()`	Retrieves the attribute value, as an unsigned 32-bit integer
`u_short_value()`	Retrieves the attribute value, as an unsigned short integer
`u_char_value()`	Retrieves the attribute value, as an unsigned `char`
`float_value()`	Retrieves the attribute value, as a float
`double_value()`	Retrieves the attribute value, as a double
`aRef()`	Gets a pointer to the attribute value
`clone()`	Makes a deep copy of the `RecAttr` object
`~NdbRecAttr()`	Destructor method

For detailed descriptions, signatures, and examples of use for each of these methods, see Section 3.7.1, “NdbRecAttr Class Methods”.

Public Types. The NdbRecAttr class defines no public types.

Class Diagram. This diagram shows all the available methods of the NdbRecAttr class:

3.7.1. `NdbRecAttr` Class Methods

3.7.1.1. NdbRecAttr::getColumn()
3.7.1.2. NdbRecAttr::getType()
3.7.1.3. NdbRecAttr::get_size_in_bytes()
3.7.1.4. NdbRecAttr::isNULL()
3.7.1.5. NdbRecAttr::in64_value()
3.7.1.6. NdbRecAttr::int32_value()
3.7.1.7. NdbRecAttr::short_value()
3.7.1.8. NdbRecAttr::char_value()
3.7.1.9. NdbRecAttr::u_64_value()
3.7.1.10. NdbRecAttr::in64_value()
3.7.1.11. NdbRecAttr::u_short_value()
3.7.1.12. NdbRecAttr::u_char_value()
3.7.1.13. NdbRecAttr::float_value()
3.7.1.14. NdbRecAttr::double_value()
3.7.1.15. NdbRecAttr::aRef()
3.7.1.16. NdbRecAttr::clone()
3.7.1.17. ~NdbRecAttr()

Abstract

This section lists and describes the public methods of the NdbRecAttr class.

Constructor and Destructor. The NdbRecAttr class has no public constructor; an instance of this object is created using NdbTransaction::execute(). The destructor method, which is public, is discussed in Section 3.7.1.17, “~NdbRecAttr()”.

3.7.1.1. `NdbRecAttr::getColumn()`

Description. This method is used to obtain the column to which the attribute belongs.

Signature.

const NdbDictionary::Column* getColumn
    (
      void
    ) const

Parameters. None.

Return Value. A pointer to a Column object. See Section 3.4.2, “The Column Class”.

3.7.1.2. `NdbRecAttr::getType()`

Description. This method is used to obtain the column's datatype.

Signature.

NdbDictionary::Column::Type getType
    (
      void
    ) const

Parameters. None.

Return Value. An NdbDictionary::Column::Type value. See Section 3.4.2.1.3, “Column::Type” for more information, including permitted values.

3.7.1.3. `NdbRecAttr::get_size_in_bytes()`

Description. You can use this method to obtain the size of an attribute (element).

Signature.

Uint32 get_size_in_bytes
    (
      void
    ) const

Parameters. None.

Return Value. The attribute size in bytes, as an unsigned 32-bit integer.

3.7.1.4. `NdbRecAttr::isNULL()`

Description. This method checks whether an attribute value is NULL.

Signature.

int isNULL
    (
      void
    ) const

Parameters. None.

Return Value. One of the following 3 values:

-1: The attribute value is not defined, either due to an error, or because NdbTransaction::execute() has not yet been used.
0: The attribute value is defined, but is not NULL.
1: The attribute value is defined and is NULL.

3.7.1.5. `NdbRecAttr::in64_value()`

Description. This method gets the value stored in an NdbRecAttr object, and returns it as a 64-bit integer.

Signature.

Int64 int64_value
    (
      void
    ) const

Parameters. None.

Return Value. A 64-bit integer.

3.7.1.6. `NdbRecAttr::int32_value()`

Description. This method gets the value stored in an NdbRecAttr object, and returns it as a 32-bit integer.

Signature.

Int32 int32_value
    (
      void
    ) const

Parameters. None.

Return Value. A 32-bit integer.

3.7.1.7. `NdbRecAttr::short_value()`

Description. This method gets the value stored in an NdbRecAttr object, and returns it as a 16-bit integer (short).

Signature.

short short_value
    (
      void
    ) const

Parameters. None.

Return Value. A 16-bit integer.

3.7.1.8. `NdbRecAttr::char_value()`

Description. This method gets the value stored in an NdbRecAttr object, and returns it as a char.

Signature.

char char_value
    (
      void
    ) const

Parameters. None.

Return Value. A char value.

3.7.1.9. `NdbRecAttr::u_64_value()`

Description. This method gets the value stored in an NdbRecAttr object, and returns it as an unsigned 64-bit integer.

Signature.

Uint64 u_64_value
    (
      void
    ) const

Parameters. None.

Return Value. An unsigned 64-bit integer.

3.7.1.10. `NdbRecAttr::in64_value()`

Description. This method gets the value stored in an NdbRecAttr object, and returns it as an unsigned 32-bit integer.

Signature.

Uint32 u_32_value
    (
      void
    ) const

Parameters. None.

Return Value. An unsigned 32-bit integer.

3.7.1.11. `NdbRecAttr::u_short_value()`

Description. This method gets the value stored in an NdbRecAttr object, and returns it as an unsigned 16-bit (short) integer.

Signature.

Uint16 u_short_value
    (
      void
    ) const

Parameters. None.

Return Value. An unsigned short (16-bit) integer.

3.7.1.12. `NdbRecAttr::u_char_value()`

Description. This method gets the value stored in an NdbRecAttr object, and returns it as an unsigned char.

Signature.

Uint8 u_char_value
    (
      void
    ) const

Parameters. None.

Return Value. An unsigned 8-bit char value.

3.7.1.13. `NdbRecAttr::float_value()`

Description. This method gets the value stored in an NdbRecAttr object, and returns it as a float.

Signature.

float float_value
    (
      void
    ) const

Parameters. None.

Return Value. A float.

3.7.1.14. `NdbRecAttr::double_value()`

Description. This method gets the value stored in an NdbRecAttr object, and returns it as a double.

Signature.

double double_value
    (
      void
    ) const

Parameters. None.

Return Value. A double.

3.7.1.15. `NdbRecAttr::aRef()`

Description. This method is used to obtain a reference to an attribute value, as a char pointer. This pointer is aligned appropriately for the datatype. The memory is released by the NDB API when NdbTransaction::closeTransaction() is executed on the transaction which read the value.

Signature.

char* aRef
    (
      void
    ) const

Parameters. A pointer to the attribute value. Because this pointer is constant, this method can be called anytime after NdbOperation::getValue() has been called.

Return Value. None.

3.7.1.16. `NdbRecAttr::clone()`

Description. This method creates a deep copy of an NdbRecAttr object.

Note

The copy created by this method should be deleted by the application when no longer needed.

Signature.

NdbRecAttr* clone
    (
      void
    ) const

Parameters. None.

Return Value. An NdbRecAttr object. This is a complete copy of the original, including all data.

3.7.1.17. `~NdbRecAttr()`

Description. The NdbRecAttr class destructor method.

Important

You should delete only copies of NdbRecAttr objects that were created in your application using the clone() method. See Section 3.7.1.16, “NdbRecAttr::clone()”.

Signature.

~NdbRecAttr
    (
      void
    )

Parameters. None.

Return Value. None.

3.8. The `NdbScanFilter` Class

3.8.1. NdbScanFilter Types
3.8.2. NdbScanFilter Class Methods

Abstract

This section discusses the NdbScanFliter class and it public members.

Description. NdbScanFilter provides an alternative means of specifying filters for scan operations.

Important

This interface is still under development and is likely to change in future releases.

Public Methods. The following table lists the public methods of this class and the purpose or use of each method:

Method	Purpose / Use
`NdbScanFilter()`	Constructor method
`~NdbScanFilter()`	Destructor method
`begin()`	Begins a compound (set of conditions)
`end()`	Ends a compound
`cmp()`	Compares a column value with an arbitrary value
`eq()`	Tests for equality
`ne()`	Tests for inequality
`lt()`	Tests for a less-than condition
`le()`	Tests for a less-than-or-equal condition
`gt()`	Tests for a greater-than condition
`ge()`	Tests for a greater-than-or-equal condition
`isnull()`	Tests whether a column value is `NULL`
`isnotnull()`	Tests whether a column value is not `NULL`

For detailed descriptions, signatures, and examples of use for each of these methods, see Section 3.8.2, “NdbScanFilter Class Methods”.

Public Types. The NdbScanFilter class defines two public types:

BinaryCondition: The type of condition, such as lower bound or upper bound.
Group: A logical grouping operator, such as AND or OR.

For a discussion of each of these types, along with its possible values, see Section 3.8.1, “NdbScanFilter Types”.

Class Diagram. This diagram shows all the public members of the NdbScanFilter class:

3.8.1. `NdbScanFilter` Types

3.8.1.1. The NdbScanFilter::BinaryCondition Type
3.8.1.2. The NdbScanFilter::Group Type

Abstract

This section details the public types belonging to the NdbScanFilter class.

3.8.1.1. The `NdbScanFilter::BinaryCondition` Type

Description. This type represents a condition based on the comparison of a column value with some integer value — that is, a bound condition.

Enumeration Values.

Value	Description
`COND_LE`	Lower bound (`<=`)
`COND_LT`	Strict lower bound (`<`)
`COND_GE`	Upper bound (`>=`)
`COND_GT`	Strict upper bound (>)
`COND_EQ`	Equality (`=`)
`COND_NE`	Inequality (`<>` or `!=`)
`COND_LIKE`	`LIKE` condition
`COND_NOTLIKE`	`NOT LIKE` condition

3.8.1.2. The `NdbScanFilter::Group` Type

Description. This type is used to describe logical (grouping) operators, and is used with the begin() method. (See Section 3.8.2.2, “NdbScanFilter::begin()”.)

Enumeration Values.

Value	Description
`AND`	Logical `AND`: `A AND B AND C`
`OR`	Logical `OR`: `A OR B OR C`
`NAND`	Logical `NOT AND`: `NOT (A AND B AND C)`
`NOR`	Logical `NOT OR`: `NOT (A OR B OR C)`

3.8.2. `NdbScanFilter` Class Methods

3.8.2.1. NdbScanFilter Class Constructor
3.8.2.2. NdbScanFilter::begin()
3.8.2.3. NdbScanFilter::end()
3.8.2.4. NdbScanFilter::eq()
3.8.2.5. NdbScanFilter::ne()
3.8.2.6. NdbScanFilter::lt()
3.8.2.7. NdbScanFilter::le()
3.8.2.8. NdbScanFilter::gt()
3.8.2.9. NdbScanFilter::ge()
3.8.2.10. NdbScanFilter::isnull()
3.8.2.11. NdbScanFilter::isnotnull()

Abstract

This section lists and describes the public methods of the NdbScanFilter class.

3.8.2.1. `NdbScanFilter` Class Constructor

Description. This is the constructor method for NdbScanFilter, and creates a new instance of the class.

Signature.

NdbScanFilter
    (
      class NdbOperation* op
    )

Parameters. This method takes a single parameter: a pointer to the NdbOperation to which the filter applies.

Return Value. A new instance of NdbScanFilter.

Destructor. The destructor takes no arguments and does not return a value. It should be called to remove the NdbScanFilter object when it is no longer needed.

3.8.2.2. `NdbScanFilter::begin()`

Description. This method is used to start a compound, and specifies the logical operator used to group together the conditions making up the compound. The default is AND.

Signature.

int begin
    (
      Group group = AND
    )

Parameters. A Group value: one of AND, OR, NAND, or NOR. See Section 3.8.1.2, “The NdbScanFilter::Group Type”, for additional information.

Return Value. 0 on success, -1 on failure.

3.8.2.3. `NdbScanFilter::end()`

Description. This method completes a compound, signalling that there are no more conditions to be added to it.

Signature.

int end
    (
      void
    )

Parameters. None.

Return Value. 0 on success, -1 on failure.

3.8.2.4. `NdbScanFilter::eq()`

Description. This method is used to perform an equality test on a column value and an integer.

Signature.

int eq
    (
      int    ColId, 
      Uint32 value
    )

int eq
    (
      int    ColId, 
      Uint64 value
    )

Parameters. This method takes two parameters:

The ID (ColId) of the column whose value is to be tested
An integer with which to compare the column value; this integer may be either 32-bit or 64-bit, and is unsigned in either case.

Return Value. 0 on success, -1 on failure.

3.8.2.5. `NdbScanFilter::ne()`

Description. This method is used to perform an inequality test on a column value and an integer.

Signature.

int ne
    (
      int    ColId, 
      Uint32 value
    )

int ne
    (
      int    ColId, 
      Uint64 value
    )

Parameters. Like eq() and the other NdbScanFilter methods of this type, this method takes two parameters:

The ID (ColId) of the column whose value is to be tested
An integer with which to compare the column value; this integer may be either 32-bit or 64-bit, and is unsigned in either case.

Return Value. 0 on success, -1 on failure.

3.8.2.6. `NdbScanFilter::lt()`

Description. This method is used to perform a less-than (strict lower bound) test on a column value and an integer.

Signature.

int lt
    (
      int    ColId, 
      Uint32 value
    )

int lt
    (
      int    ColId, 
      Uint64 value
    )

Parameters. Like eq(), ne(), and the other NdbScanFilter methods of this type, this method takes two parameters:

The ID (ColId) of the column whose value is to be tested
An integer with which to compare the column value; this integer may be either 32-bit or 64-bit, and is unsigned in either case.

Return Value. 0 on success, -1 on failure.

3.8.2.7. `NdbScanFilter::le()`

Description. This method is used to perform a less-than-or-equal test on a column value and an integer.

Signature.

int le
    (
      int    ColId, 
      Uint32 value
    )

int le
    (
      int    ColId, 
      Uint64 value
    )

Parameters. Like the other NdbScanFilter methods of this type, this method takes two parameters:

The ID (ColId) of the column whose value is to be tested
An integer with which to compare the column value; this integer may be either 32-bit or 64-bit, and is unsigned in either case.

Return Value. 0 on success, -1 on failure.

3.8.2.8. `NdbScanFilter::gt()`

Description. This method is used to perform a greater-than (strict upper bound) test on a column value and an integer.

Signature.

int gt
    (
      int    ColId, 
      Uint32 value
    )

int gt
    (
      int    ColId, 
      Uint64 value
    )

Parameters. Like the other NdbScanFilter methods of this type, this method takes two parameters:

The ID (ColId) of the column whose value is to be tested
An integer with which to compare the column value; this integer may be either 32-bit or 64-bit, and is unsigned in either case.

Return Value. 0 on success, -1 on failure.

3.8.2.9. `NdbScanFilter::ge()`

Description. This method is used to perform a greater-than-or-equal test on a column value and an integer.

Signature.

int ge
    (
      int    ColId, 
      Uint32 value
    )

int ge
    (
      int    ColId, 
      Uint64 value
    )

Parameters. Like eq(), lt(), le(), and the other NdbScanFilter methods of this type, this method takes two parameters:

The ID (ColId) of the column whose value is to be tested
An integer with which to compare the column value; this integer may be either 32-bit or 64-bit, and is unsigned in either case.

Return Value. 0 on success, -1 on failure.

3.8.2.10. `NdbScanFilter::isnull()`

Description. This method is used to check whether a column value is NULL.

Signature.

int isnull
    (
      int ColId
    )

Parameters. The ID of the column whose value is to be tested.

Return Value. 0 if the value is NULL.

3.8.2.11. `NdbScanFilter::isnotnull()`

Description. This method is used to check whether a column value is not NULL.

Signature.

int isnotnull
    (
      int ColId
    )

Parameters. The ID of the column whose value is to be tested.

Return Value. 0 if the value is not NULL.

3.9. The `NdbTransaction` Class

3.9.1. NdbTransaction Types
3.9.2. NdbTransaction Class Methods

Abstract

This section describes the NdbTransaction class and its public members.

Description. A transaction is represented in the NDB API by an NdbTransaction object, which belongs to an Ndb object and is created using Ndb::startTransaction(). A transaction consists of a list of operations represented by the NdbOperation class, or by one of its subclasses — NdbScanOperation, NdbIndexOperation, or NdbIndexScanOperation (see Section 3.6, “The NdbOperation Class”). Each operation access exactly one table.

Using Transactions. After obtaining an NdbTransaction object, it is employed as follows:

An operation is allocated to the transaction using one of these methods:
- getNdbOperation()
- getNdbScanOperation()
- getNdbIndexOperation()
- getNdbIndexScanOperation()
Calling one of these methods defines the operation. Several operations can be defined on the same NdbTransaction object, in which case they are executed in parallel. When all operations are defined, the execute() method sends them to the NDB kernel for execution.
The execute() method returns when the NDB kernel has completed execution of all operations previously defined.
Important
All allocated operations should be properly defined before calling the execute() method.
execute() performs its task in one of 3 modes, listed here:
- NdbTransaction::NoCommit: Executes operations without committing them.
- NdbTransaction::Commit: Executes any remaining operation and then commits the complete transaction.
- NdbTransaction::Rollback: Rolls back the entire transaction.
execute() is also equipped with an extra error handling parameter, which provides two alternatives:
- NdbTransaction::AbortOnError: Any error causes the transaction to be aborted. This is the default behaviour.
- NdbTransaction::AO_IgnoreError: The transaction continues to be executed even if one or more of the operations defined for that transaction fails.

Public Methods. The following table lists the public methods of this class and the purpose or use of each method:

Method	Purpose / Use
`getNdbOperation()`	Gets an `NdbOperation`
`getNdbScanOperation()`	Gets an `NdbScanOperation`
`getNdbIndexScanOperation()`	Gets an `NdbIndexScanOperation`
`getNdbIndexOperation()`	Gets an `NdbIndexOperation`
`execute`	Executes a transaction
`refresh()`	Keeps a transaction from timing out
`close()`	Closes a transaction
`getGCI()`	Gets a transaction's global checkpoint ID (GCI)
`getTransactionId()`	Gets the transaction ID
`commitStatus()`	Gets the transaction's commit status
`getNdbError()`	Gets the most recent error
`getNdbErrorOperation()`	Gets the most recent operation which caused an error
`getNdbErrorLine()`	Gets the line number where the most recent error occurred
`getNextCompletedOperation()`	Gets operations that have been executed; used for finding errors

For detailed descriptions, signatures, and examples of use for each of these methods, see Section 3.9.2, “NdbTransaction Class Methods”.

Public Types. NdbTransaction defines 3 public types as shown in the following table:

Type	Purpose / Use
`AbortOption`	Determines whether failed operations cause a transaction to abort
`CommitStatusType`	Describes the transaction's commit status
`ExecType`	Determines whether the transaction should be committed or rolled back

For a discussion of each of these types, along with its possible values, see Section 3.9.1, “NdbTransaction Types”.

Class Diagram. This diagram shows all the available methods and enumerated types of the ... class:

Public members of the
NdbTransaction class.

3.9.1. `NdbTransaction` Types

3.9.1.1. The NdbTransaction::AbortOption Type
3.9.1.2. The NdbTransaction::CommitStatusType Type
3.9.1.3. The NdbTransaction::ExecType Type

Abstract

This section details the public types belonging to the NdbTransaction class.

3.9.1.1. The `NdbTransaction::AbortOption` Type

Description. This type is used to determine whether failed operations should force a transaction to be aborted. It is used as an argument to the execute() method — see Section 3.9.2.5, “NdbTransaction::execute()”, for more information.

Enumeration Values.

Value	Description
`AbortOnError`	A failed operation causes the transaction to abort.
`AO_IgnoreOnError`	Failed operations are ignored; the transaction continues to execute.

3.9.1.2. The `NdbTransaction::CommitStatusType` Type

Description. This type is used to describe a transaction's commit status.

Enumeration Values.

Value	Description
`NotStarted`	The transaction has not yet been started.
`Started`	The transaction has started, but is not yet committed.
`Committed`	The transaction has completed, and has been committed.
`Aborted`	The transaction was aborted.
`NeedAbort`	The transaction has encountered an error, but has not yet been aborted.

A transaction's commit status ca be read using the commitStatus() method. See Section 3.9.2.10, “NdbTransaction::commitStatus()”.

3.9.1.3. The `NdbTransaction::ExecType` Type

Description. This type sets the transaction's execution type — that is, whether it should execute, execute and commit, or abort. It is used as a parameter to the execute() method. (See Section 3.9.2.5, “NdbTransaction::execute()”.)

Enumeration Values.

Value	Description
`NoCommit`	The transaction should execute, but not commit.
`Commit`	The transaction should execute and be committed.
`Rollback`	The transaction should be rolled back.

3.9.2. `NdbTransaction` Class Methods

3.9.2.1. NdbTransaction::getNdbOperation()
3.9.2.2. NdbTransaction::getNdbScanOperation()
3.9.2.3. NdbTransaction::getNdbIndexScanOperation()
3.9.2.4. NdbTransaction::getNdbIndexOperation()
3.9.2.5. NdbTransaction::execute()
3.9.2.6. NdbTransaction::refresh()
3.9.2.7. NdbTransaction::close()
3.9.2.8. NdbTransaction::getGCI()
3.9.2.9. NdbTransaction::getTransactionId()
3.9.2.10. NdbTransaction::commitStatus()
3.9.2.11. NdbTransaction::getNdbError()
3.9.2.12. NdbTransaction::getNdbErrorOperation()
3.9.2.13. NdbTransaction::getNdbErrorLine()
3.9.2.14. NdbTransaction::getNextCompleteOperation()

Abstract

This section lists and describes the public methods of the NdbTransaction class.

3.9.2.1. `NdbTransaction::getNdbOperation()`

Description. This method is used to create an NdbOperation associated with a given table.

Note

All operations within the same transaction must be initialised with this method. Operations must be defined before they are executed.

Signature.

NdbOperation* getNdbOperation
    (
      const NdbDictionary::Table* table
    )

Parameters. The Table object on which the operation is to be performed. See Section 3.4.3.7, “The Table Class”.

Return Value. A pointer to the new NdbOperation. See Section 3.6, “The NdbOperation Class”.

3.9.2.2. `NdbTransaction::getNdbScanOperation()`

Description. This method is used to create an NdbScanOperation associated with a given table.

Note

All scan operations within the same transaction must be initialised with this method. Operations must be defined before they are executed.

Signature.

NdbScanOperation* getNdbScanOperation
    (
      const NdbDictionary::Table* table
    )

Parameters. The Table object on which the operation is to be performed. See Section 3.4.3.7, “The Table Class”.

Return Value. A pointer to the new NdbScanOperation. See Section 3.6.4, “The NdbScanOperation Class”.

3.9.2.3. `NdbTransaction::getNdbIndexScanOperation()`

Description. This method is used to create an NdbIndexScanOperation associated with a given table.

Note

All index scan operations within the same transaction must be initialised with this method. Operations must be defined before they are executed.

Signature.

NdbIndexScanOperation* getNdbIndexScanOperation
    (
      const NdbDictionary::Table* table
    )

Parameters. The Table object on which the operation is to be performed. See Section 3.4.3.7, “The Table Class”.

Return Value. A pointer to the new NdbIndexScanOperation. See Section 3.6.4.3, “The NdbIndexScanOperation Class”.

3.9.2.4. `NdbTransaction::getNdbIndexOperation()`

Description. This method is used to create an NdbIndexOperation associated with a given table.

Note

All index operations within the same transaction must be initialised with this method. Operations must be defined before they are executed.

Signature.

NdbIndexOperation* getNdbIndexOperation
    (
      const NdbDictionary::Table* table
    )

Parameters. The Table object on which the operation is to be performed. See Section 3.4.3.7, “The Table Class”.

Return Value. A pointer to the new NdbIndexOperation. See Section 3.6.3, “The NdbIndexOperation Class”.

3.9.2.5. `NdbTransaction::execute()`

Description. This method is used to execute a transaction.

Signature.

int execute
    (
      ExecType execType,
      AbortOption abortOption = AbortOnError,
      int force = 0 
    )

Parameters. The execute method takes 3 parameters, as described here:

The execution type (ExecType value); see Section 3.9.1.3, “The NdbTransaction::ExecType Type”, for more information and possible values.
An abort option (AbortOption value); see Section 3.9.1.3, “The NdbTransaction::ExecType Type”, for more information and possible values.
A force parameter, which determines when operations should be sent to the NDB Kernel:
- 0: Non-forced; detected by the adaptive send algorithm.
- 1: Forced; detected by the adaptive send algorithm.
- 2: Non-forced; not detected by the adaptive send algorithm.
See Section 1.3.4, “The Adaptive Send Algorithm”.

Return Value. 0 on success, -1 on failure.

3.9.2.6. `NdbTransaction::refresh()`

Description. This method updates the transaction's timeout counter, and thus avoids aborting due to transaction timeout.

Note

It is not advisable to take a lock on a record and maintain it for a extended time since this can impact other transactions.

Signature.

int refresh
    (
      void
    )

Parameters. None.

Return Value. 0 on success, -1 on failure.

3.9.2.7. `NdbTransaction::close()`

Description. This method closes a transaction. It is equivalent to calling Ndb::closeTransaction() (see Section 3.1.1.8, “Ndb::closeTransaction()”).

Signature.

void close
    (
      void
    )

Parameters. None.

Return Value. None.

3.9.2.8. `NdbTransaction::getGCI()`

Description. This method retrieves the transaction's global checkpoint ID (GCI).

Each committed transaction belongs to a GCI. The log for the committed transaction is saved on disk when a global checkpoint occurs.

By comparing the GCI of a transaction with the value of the latest GCI restored in a restarted NDB Cluster, you can determine whether or not the transaction was restored.

Note

Whether or not the global checkpoint with this GCI has been saved on disk cannot be determined by this method.

Important

The GCI for a scan transaction is undefined, since no updates are performed in scan transactions.

Signature.

int getGCI
    (
      void
    )

Parameters. None.

Return Value. The transaction's GCI, or -1 if none is available.

Note

No GCI is available until execute() has been called with ExecType::Commit.

3.9.2.9. `NdbTransaction::getTransactionId()`

Description. This method is used to obtain the transaction ID.

Signature.

Uint64 getTransactionId
    (
      void
    )

Parameters. None.

Return Value. The transaction ID, as an unsigned 64-bit integer.

3.9.2.10. `NdbTransaction::commitStatus()`

Description. This method gets the transaction's commit status.

Signature.

CommitStatusType commitStatus
    (
      void
    )

Parameters. None.

Return Value. The commit status of the transaction, a CommitStatusType value. See Section 3.9.1.2, “The NdbTransaction::CommitStatusType Type”.

3.9.2.11. `NdbTransaction::getNdbError()`

Description. This method is used to obtain the most recent error (NdbError).

Signature.

const NdbError& getNdbError
    (
      void
    ) const

Parameters. None.

Return Value. A reference to an NdbError object. See Section 4.1, “The NdbError Structure”.

Note

For additional information about handling errors in transactions, see Section 1.3.2.3.5, “Error Handling”.

3.9.2.12. `NdbTransaction::getNdbErrorOperation()`

Description. This method retrieves the operation that caused an error.

Tip

To obtain more information about the actual error, use the NdbOperation::getNdbError() method of the NdbOperation object returned by getNdbErrorOperation(). (See Section 3.6.2.5, “NdbOperation::getNdbError()”.)

Signature.

NdbOperation* getNdbErrorOperation
    (
      void
    )

Parameters. None.

Return Value. A pointer to an NdbOperation.

Note

For additional information about handling errors in transactions, see Section 1.3.2.3.5, “Error Handling”.

3.9.2.13. `NdbTransaction::getNdbErrorLine()`

Description. This method return the line number where the most recent error occurred.

Signature.

int getNdbErrorLine
    (
      void
    )

Parameters. None.

Return Value. The line number of the most recent error.

Note

For additional information about handling errors in transactions, see Section 1.3.2.3.5, “Error Handling”.

3.9.2.14. `NdbTransaction::getNextCompleteOperation()`

Description. This method is used to retrieve a transaction's completed operations. It is typically used to fetch all operations belonging to a given transaction to check for errors.

NdbTransaction::getNextCompletedOperation(NULL) returns the transaction's first NdbOperation object; NdbTransaction::getNextCompletedOperation(myOp) returns the NdbOperation object defined after NdbOperation myOp.

Important

This method should only be used after the transaction has been executed, but before the transaction has been closed.

Signature.

const NdbOperation* getNextCompletedOperation
    (
      const NdbOperation* op
    ) const

Parameters. This method requires a single parameter op, which is an operation (NdbOperation object), or NULL.

Return Value. The operation following op, or the first operation defined for the transaction if getNextCompletedOperation() was called using NULL.

Prev		Next
Chapter 2. GETTING STARTED WITH THE `NDB` API	Home	Chapter 4. NDB API ERRORS