Chapter 2. The NDB API

Chapter 2. The NDB API
Prev		Next

Chapter 2. The NDB API

Table of Contents

2.1. Getting Started with the NDB API

2.1.1. Compiling and Linking NDB API Programs
2.1.2. Connecting to the Cluster
2.1.3. Mapping MySQL Database Object Names and Types to NDB

2.2. The NDB API Object Hierarachy

2.3. NDB API Classes, Interfaces, and Structures

2.3.1. The Column Class
2.3.2. The Datafile Class
2.3.3. The Dictionary Class
2.3.4. The Event Class
2.3.5. The Index Class
2.3.6. The LogfileGroup Class
2.3.7. The List Class
2.3.8. The Ndb Class
2.3.9. The NdbBlob Class
2.3.10. The NdbDictionary Class
2.3.11. The NdbEventOperation Class
2.3.12. The NdbIndexOperation Class
2.3.13. The NdbIndexScanOperation Class
2.3.14. The NdbInterpretedCode Class
2.3.15. The NdbOperation Class
2.3.16. The NdbRecAttr Class
2.3.17. The NdbScanFilter Class
2.3.18. The NdbScanOperation Class
2.3.19. The NdbTransaction Class
2.3.20. The Object Class
2.3.21. The Table Class
2.3.22. The Tablespace Class
2.3.23. The Undofile Class
2.3.24. The Ndb_cluster_connection Class
2.3.25. The NdbRecord Interface
2.3.26. The AutoGrowSpecification Structure
2.3.27. The Element Structure
2.3.28. The IndexBound Structure
2.3.29. The Key_part_ptr Structure
2.3.30. The NdbError Structure
2.3.31. The PartitionSpec Structure
2.3.32. The RecordSpecification Structure

2.4. Practical Examples

2.4.1. Using Synchronous Transactions
2.4.2. Using Synchronous Transactions and Multiple Clusters
2.4.3. Handling Errors and Retrying Transactions
2.4.4. Basic Scanning Example
2.4.5. Using Secondary Indexes in Scans
2.4.6. Using NdbRecord with Hash Indexes
2.4.7. NDB API Event Handling Example
2.4.8. Event Handling with Multiple Clusters
2.4.9. Basic BLOB Handling Example
2.4.10. Handling BLOBs Using NdbRecord

Abstract

This chapter contains information about the NDB API, which is used to write applications that access data in the NDBCLUSTER storage engine.

2.1. Getting Started with the NDB API

2.1.1. Compiling and Linking NDB API Programs
2.1.2. Connecting to the Cluster
2.1.3. Mapping MySQL Database Object Names and Types to NDB

This section discusses preparations necessary for writing and compiling an NDB API application.

2.1.1. Compiling and Linking NDB API Programs

2.1.1.1. General Requirements
2.1.1.2. Compiler Options
2.1.1.3. Linker Options
2.1.1.4. Using Autotools

Abstract

This section provides information on compiling and linking NDB API applications, including requirements and compiler and linker options.

2.1.1.1. General Requirements

To use the NDB API with MySQL, you must have the NDB client library and its header files installed alongside the regular MySQL client libraries and headers. These are automatically installed when you build MySQL using the --with-ndbcluster configure option or when using a MySQL binary package that supports the NDBCLUSTER storage engine.

Note

MySQL 4.1 does not install the required NDB-specific header files. You should use MySQL 5.0 or later when writing NDB API applications, and this Guide is targeted for use with MySQL 5.1.

The library and header files were not included in MySQL 5.1 binary distributions prior to MySQL 5.1.12; beginning with 5.1.12, you can find them in /usr/include/storage/ndb. This issue did not occur when compiling MySQL 5.1 from source.

2.1.1.2. Compiler Options

Header Files. In order to compile source files that use the NDB API, you must ensure that the necessary header files can be found. Header files specific to the NDB API are installed in the following subdirectories of the MySQL include directory:

include/mysql/storage/ndb/ndbapi
include/mysql/storage/ndb/mgmapi

Compiler Flags. The MySQL-specific compiler flags needed can be determined using the mysql_config utility that is part of the MySQL installation:

$ mysql_config --cflags
-I/usr/local/mysql/include/mysql -Wreturn-type -Wtrigraphs -W -Wformat
-Wsign-compare -Wunused  -mcpu=pentium4 -march=pentium4

This sets the include path for the MySQL header files but not for those specific to the NDB API. The --include option to mysql_config returns the generic include path switch:

shell> mysql_config --include
-I/usr/local/mysql/include/mysql

It is necessary to add the subdirectory paths explicitly, so that adding all the needed compile flags to the CXXFLAGS shell variable should look something like this:

CFLAGS="$CFLAGS "`mysql_config --cflags`
CFLAGS="$CFLAGS "`mysql_config --include`/storage/ndb
CFLAGS="$CFLAGS "`mysql_config --include`/storage/ndb/ndbapi
CFLAGS="$CFLAGS "`mysql_config --include`/storage/ndb/mgmapi

Tip

If you do not intend to use the Cluster management functions, the last line in the previous example can be omitted. However, if you are interested in the management functions only, and do not want or need to access Cluster data except from MySQL, then you can omit the line referencing the ndbapi directory.

2.1.1.3. Linker Options

NDB API applications must be linked against both the MySQL and NDB client libraries. The NDB client library also requires some functions from the mystrings library, so this must be linked in as well.

The necessary linker flags for the MySQL client library are returned by mysql_config --libs. For multithreaded applications you should use the --libs_r instead:

$ mysql_config --libs_r
-L/usr/local/mysql-5.1/lib/mysql -lmysqlclient_r -lz -lpthread -lcrypt
-lnsl -lm -lpthread -L/usr/lib -lssl -lcrypto

Formerly, to link an NDB API application, it was necessary to add -lndbclient, -lmysys, and -lmystrings to these options, in the order shown, and adding all the required linker flags to the LDFLAGS variable looked something like this:

LDFLAGS="$LDFLAGS "`mysql_config --libs_r`
LDFLAGS="$LDFLAGS -lndbclient -lmysys -lmystrings"

Beginning with MySQL 5.1.24-ndb-6.2.16 and MySQL 5.1.24-ndb-6.3.14, it is necessary only to add -lndbclient to LD_FLAGS, as shown here:

LDFLAGS="$LDFLAGS "`mysql_config --libs_r`
LDFLAGS="$LDFLAGS -lndbclient"

(For more information about this change, see Bug#29791.)

2.1.1.4. Using Autotools

It is often faster and simpler to use GNU autotools than to write your own makefiles. In this section, we provide an autoconf macro WITH_MYSQL that can be used to add a --with-mysql option to a configure file, and that automatically sets the correct compiler and linker flags for given MySQL installation.

All of the examples in this chapter include a common mysql.m4 file defining WITH_MYSQL. A typical complete example consists of the actual source file and the following helper files:

acinclude
configure.in
Makefile.m4

automake also requires that you provide README, NEWS, AUTHORS, and ChangeLog files; however, these can be left empty.

To create all necessary build files, run the following:

aclocal
autoconf
automake -a -c
configure --with-mysql=/mysql/prefix/path

Normally, this needs to be done only once, after which make will accommodate any file changes.

Example 1-1: acinclude.m4.

m4_include([../mysql.m4])

Example 1-2: configure.in.

AC_INIT(example, 1.0)
AM_INIT_AUTOMAKE(example, 1.0)
WITH_MYSQL()
AC_OUTPUT(Makefile)

Example 1-3: Makefile.am.

bin_PROGRAMS = example
example_SOURCES = example.cc

Example 1-4: WITH_MYSQL source for inclusion in acinclude.m4.

dnl
dnl configure.in helper macros
dnl

AC_DEFUN([WITH_MYSQL], [
  AC_MSG_CHECKING(for mysql_config executable)

  AC_ARG_WITH(mysql, [  --with-mysql=PATH path to mysql_config binary or mysql prefix dir], [
  if test -x $withval -a -f $withval
    then
      MYSQL_CONFIG=$withval
    elif test -x $withval/bin/mysql_config -a -f $withval/bin/mysql_config
    then
     MYSQL_CONFIG=$withval/bin/mysql_config
    fi
  ], [
  if test -x /usr/local/mysql/bin/mysql_config -a -f /usr/local/mysql/bin/mysql_config
    then
      MYSQL_CONFIG=/usr/local/mysql/bin/mysql_config
    elif test -x /usr/bin/mysql_config -a -f /usr/bin/mysql_config
    then
      MYSQL_CONFIG=/usr/bin/mysql_config
    fi
  ])

  if test "x$MYSQL_CONFIG" = "x"
  then
    AC_MSG_RESULT(not found)
    exit 3
  else
    AC_PROG_CC
    AC_PROG_CXX

    # add regular MySQL C flags
    ADDFLAGS=`$MYSQL_CONFIG --cflags`

    # add NDB API specific C flags
    IBASE=`$MYSQL_CONFIG --include`
    ADDFLAGS="$ADDFLAGS $IBASE/storage/ndb"
    ADDFLAGS="$ADDFLAGS $IBASE/storage/ndb/ndbapi"
    ADDFLAGS="$ADDFLAGS $IBASE/storage/ndb/mgmapi"

    CFLAGS="$CFLAGS $ADDFLAGS"
    CXXFLAGS="$CXXFLAGS $ADDFLAGS"

    LDFLAGS="$LDFLAGS "`$MYSQL_CONFIG --libs_r`" -lndbclient -lmystrings -lmysys"
    LDFLAGS="$LDFLAGS "`$MYSQL_CONFIG --libs_r`" -lndbclient -lmystrings"

    AC_MSG_RESULT($MYSQL_CONFIG)
  fi
])

2.1.2. Connecting to the Cluster

2.1.2.1. Include Files
2.1.2.2. API Initialisation and Cleanup
2.1.2.3. Establishing the Connection

Abstract

This section covers connecting an NDB API application to a MySQL cluster.

2.1.2.1. Include Files

NDB API applications require one or more of the following include files:

Applications accessing Cluster data via the NDB API must include the file NdbApi.hpp.
Applications making use of both the NDB API and the regular MySQL client API also need to include mysql.h.
Applications that use cluster management functions need the include file mgmapi.h.

2.1.2.2. API Initialisation and Cleanup

Before using the NDB API, it must first be initialised by calling the ndb_init() function. Once an NDB API application is complete, call ndb_end(0) to perform a cleanup.

2.1.2.3. Establishing the Connection

To establish a connection to the server, it is necessary to create an instance of Ndb_cluster_connection, whose constructor takes as its argument a cluster connectstring; if no connectstring is given, localhost is assumed.

The cluster connection is not actually initiated until the Ndb_cluster_connection::connect() method is called. When invoked without any arguments, the connection attempt is retried each 1 second indefinitely until successful, and no reporting is done. See Section 2.3.24, “The Ndb_cluster_connection Class”, for details.

By default an API node will connect to the “nearest” data node — usually a data node running on the same machine, due to the fact that shared memory transport can be used instead of the slower TCP/IP. This may lead to poor load distribution in some cases, so it is possible to enforce a round-robin node connection scheme by calling the set_optimized_node_selection() method with 0 as its argument prior to calling connect(). (See Section 2.3.24.1.6, “Ndb_cluster_connection::set_optimized_node_selection()”.)

The connect() method initiates a connection to a cluster management node only — it does not wait for any connections to data nodes to be made. This can be accomplished by using wait_until_ready() after calling connect(). The wait_until_ready() method waits up to a given number of seconds for a connection to a data node to be established.

In the following example, initialisation and connection are handled in the two functions example_init() and example_end(), which will be included in subsequent examples via the file example_connection.h.

Example 2-1: Connection example.

#include <stdio.h>
#include <stdlib.h>
#include <NdbApi.hpp>
#include <mysql.h>
#include <mgmapi.h>

Ndb_cluster_connection* connect_to_cluster();
void disconnect_from_cluster(Ndb_cluster_connection *c);

Ndb_cluster_connection* connect_to_cluster()
{
  Ndb_cluster_connection* c;

  if(ndb_init())
    exit(EXIT_FAILURE);

  c= new Ndb_cluster_connection();

  if(c->connect(4, 5, 1))
  {
    fprintf(stderr, "Unable to connect to cluster within 30 seconds.\n\n");
    exit(EXIT_FAILURE);
  }

  if(c->wait_until_ready(30, 0) < 0)
  {
    fprintf(stderr, "Cluster was not ready within 30 seconds.\n\n");
    exit(EXIT_FAILURE);
  }
}

void disconnect_from_cluster(Ndb_cluster_connection *c)
{
  delete c;

  ndb_end(2);
}

int main(int argc, char* argv[])
{
  Ndb_cluster_connection *ndb_connection= connect_to_cluster();

  printf("Connection Established.\n\n");

  disconnect_from_cluster(ndb_connection);

  return EXIT_SUCCESS;
}

2.1.3. Mapping MySQL Database Object Names and Types to `NDB`

Abstract

This section discusses NDB naming and other conventions with regard to database objects.

Databases and Schemas. Databases and schemas are not represented by objects as such in the NDB API. Instead, they are modelled as attributes of Table and Index objects. The value of the database attribute of one of these objects is always the same as the name of the MySQL database to which the table or index belongs. The value of the schema attribute of a Table or Index object is always 'def' (for “default”).

Tables. MySQL table names are directly mapped to NDB table names without modification. Table names starting with 'NDB$' are reserved for internal use>, as is the SYSTAB_0 table in the sys database.

Indexes. There are two different type of NDB indexes:

Hash indexes are unique, but not ordered.
B-tree indexes are ordered, but allow duplicate values.

Names of unique indexes and primary keys are handled as follows:

For a MySQL UNIQUE index, both a B-tree and a hash index are created. The B-tree index uses the MySQL name for the index; the name for the hash index is generated by appending '$unique' to the index name.
For a MySQL primary key only a B-tree index is created. This index is given the name PRIMARY. There is no extra hash; however, the uniqueness of the primary key is guaranteed by making the MySQL key the internal primary key of the NDB table.

Column Names and Values. NDB column names are the same as their MySQL names.

Datatypes. MySQL datatypes are stored in NDB columns as follows:

The MySQL TINYINT, SMALLINT, INT, and BIGINT datatypes map to NDB types having the same names and storage requirements as their MySQL counterparts.
The MySQL FLOAT and DOUBLE datatypes are mapped to NDB types having the same names and storage requirements.
The storage space required for a MySQL CHAR column is determined by the maximum number of characters and the column's character set. For most (but not all) character sets, each character takes one byte of storage. When using UTF-8, each character requires three bytes. You can find the number of bytes needed per character in a given character set by checking the Maxlen column in the output of SHOW CHARACTER SET.
In MySQL 5.1, the storage requirements for a VARCHAR or VARBINARY column depend on whether the column is stored in memory or on disk:
- For in-memory columns, the NDBCLUSTER storage engine supports variable-width columns with 4-byte alignment. This means that (for example) a the string 'abcde' stored in a VARCHAR(50) column using the latin1 character set requires 12 bytes — in this case, 2 bytes times 5 characters is 10, rounded up to the next even multiple of 4 yields 12. (This represents a change in behaviour from Cluster in MySQL 5.0 and 4.1, where a column having the same definition required 52 bytes storage per row regardless of the length of the string being stored in the row.)
- In Disk Data columns, VARCHAR and VARBINARY are stored as fixed-width columns. This means that each of these types requires the same amount of storage as a CHAR of the same size.
Each row in a Cluster BLOB or TEXT column is made up of two separate parts. One of these is of fixed size (256 bytes), and is actually stored in the original table. The other consists of any data in excess of 256 bytes, which stored in a hidden table. The rows in this second table are always 2000 bytes long. This means that record of size bytes in a TEXT or BLOB column requires
- 256 bytes, if size <= 256
- 256 + 2000 * ((size – 256) \ 2000) + 1) bytes otherwise

2.2. The NDB API Object Hierarachy

This section provides a hierarchical listing of all classes, interfaces, and structures exposed by the NDB API.

2.3. NDB API Classes, Interfaces, and Structures

2.3.1. The Column Class
2.3.2. The Datafile Class
2.3.3. The Dictionary Class
2.3.4. The Event Class
2.3.5. The Index Class
2.3.6. The LogfileGroup Class
2.3.7. The List Class
2.3.8. The Ndb Class
2.3.9. The NdbBlob Class
2.3.10. The NdbDictionary Class
2.3.11. The NdbEventOperation Class
2.3.12. The NdbIndexOperation Class
2.3.13. The NdbIndexScanOperation Class
2.3.14. The NdbInterpretedCode Class
2.3.15. The NdbOperation Class
2.3.16. The NdbRecAttr Class
2.3.17. The NdbScanFilter Class
2.3.18. The NdbScanOperation Class
2.3.19. The NdbTransaction Class
2.3.20. The Object Class
2.3.21. The Table Class
2.3.22. The Tablespace Class
2.3.23. The Undofile Class
2.3.24. The Ndb_cluster_connection Class
2.3.25. The NdbRecord Interface
2.3.26. The AutoGrowSpecification Structure
2.3.27. The Element Structure
2.3.28. The IndexBound Structure
2.3.29. The Key_part_ptr Structure
2.3.30. The NdbError Structure
2.3.31. The PartitionSpec Structure
2.3.32. The RecordSpecification Structure

This section provides a detailed listing of all classes, interfaces, and stuctures defined in the NDB API.

Each listing includes:

Description and purpose of the class, interface, or structure.
Pointers, where applicable, to parent and child classes.
A diagram of the class and its members.
Note
The sections covering the NdbDictionary and NdbOperation classes also include entity-relationship diagrams showing the hierarchy of inner classes, subclasses, and public type descending from them.
Detailed listings of all public members, including descriptions of all method parameters and type values.

Class, interface, and structure descriptions are provided in alphabetical order. For a hierarchical listing, see Section 2.2, “The NDB API Object Hierarachy”.

2.3.1. The `Column` Class

2.3.1.1. Column Types
2.3.1.2. Column Methods

Abstract

This class represents a column in an NDB Cluster table.

Parent class. NdbDictionary

Child classes. None

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.

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 nontextual 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
`setPrecision()`	Sets the column's precision (used for decimal types only)
`setScale()`	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 2.3.1.2, “Column Methods”.

Important

In the NDB API, column names are handled in case-sensitive fashion. (This differs from the MySQL C API.) To reduce the possibility for error, it is recommended that you name all columns consistently using uppercase or lowercase.

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

2.3.1.1. `Column` Types

2.3.1.1.1. The Column::ArrayType Type
2.3.1.1.2. The Column::StorageType Type
2.3.1.1.3. Column::Type

Abstract

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

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

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

2.3.1.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 2.3.9, “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.

2.3.1.2. `Column` Methods

2.3.1.2.1. Column Constructor
2.3.1.2.2. Column::getName()
2.3.1.2.3. Column::getNullable()
2.3.1.2.4. Column::getPrimaryKey()
2.3.1.2.5. Column::getColumnNo()
2.3.1.2.6. Column::equal()
2.3.1.2.7. Column::getType()
2.3.1.2.8. Column::getPrecision()
2.3.1.2.9. Column::getScale()
2.3.1.2.10. Column::getLength()
2.3.1.2.11. Column::getCharset()
2.3.1.2.12. Column::getInlineSize()
2.3.1.2.13. Column::getPartSize()
2.3.1.2.14. Column::getStripeSize()
2.3.1.2.15. Column::getSize()
2.3.1.2.16. Column::getPartitionKey()
2.3.1.2.17. Column::getArrayType()
2.3.1.2.18. Column::getStorageType()
2.3.1.2.19. Column::setName()
2.3.1.2.20. Column::setNullable()
2.3.1.2.21. Column::setPrimaryKey()
2.3.1.2.22. Column::setType()
2.3.1.2.23. Column::setPrecision()
2.3.1.2.24. Column::setScale()
2.3.1.2.25. Column::setLength()
2.3.1.2.26. Column::setCharset()
2.3.1.2.27. Column::setInlineSize
2.3.1.2.28. Column::setPartSize()
2.3.1.2.29. Column::setStripeSize()
2.3.1.2.30. Column::setPartitionKey()
2.3.1.2.31. Column::setArrayType()
2.3.1.2.32. Column::setStorageType()

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

Also remember that the NDB API handles column names in case-sensitive fashion.

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

The NDB API handles column names in case-sensitive fashion. For example, if you create a column named “myColumn”, you will not be able to access it later using “Mycolumn” for the name. You can reduce the possibility for error, by naming all columns consistently using only uppercase or only lowercase.

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.

2.3.1.2.2. `Column::getName()`

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

Important

The NDB API handles column names in case-sensitive fashion. For example, if you retrieve the name “myColumn” for a given column, attempting to access this column using “Mycolumn” for the name fails with an error such as Column is NULL or Table definition has undefined column. You can reduce the possibility for error, by naming all columns consistently using only uppercase or only lowercase.

Signature.

const char* getName
    (
      void
    ) const

Parameters. None.

Return Value. The name of the column.

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

2.3.1.2.4. `Column::getPrimaryKey()`

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

Important

The NDB API handles column names in case-sensitive fashion; “myColumn” and “Mycolumn” are not considered to refer to the same column. It is recommended that you minimize the possibility of errors from using the wrong lettercase for column names by naming all columns consistently using only uppercase or only lowercase.

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.

2.3.1.2.5. `Column::getColumnNo()`

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

Important

The NDB API handles column names in case-sensitive fashion, “myColumn” and “Mycolumn” are not considered to be the same column. It is recommended that you minimize the possibility of errors from using the wrong lettercase by naming all columns consistently using only uppercase or only lowercase.

Signature.

int getColumnNo
    (
      void
    ) const

Parameters. None.

Return Value. The column number as an integer.

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

2.3.1.2.7. `Column::getType()`

Description. This method gets the column's datatype.

Important

Signature.

Type getType
    (
      void
    ) const

Parameters. None.

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

2.3.1.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 Numeric Types, in the MySQL Manual.

2.3.1.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 Numeric Types, in the MySQL Manual.

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

Important

Signature.

int getLength
    (
      void
    ) const

Parameters. None.

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

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

Important

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 mysql_get_character_set_info(),in the MySQL Manual.

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

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

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

2.3.1.2.15. `Column::getSize()`

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

Important

Signature.

int getSize
    (
      void
    ) const

Parameters. None.

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

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

2.3.1.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 2.3.1.1.1, “The Column::ArrayType Type” for possible values.

2.3.1.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 2.3.1.1.2, “The Column::StorageType Type”.

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

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

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

2.3.1.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 2.3.1.1.3, “Column::Type”.

Return Value. No return value.

2.3.1.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 2.3.1.2.8, “Column::getPrecision()”, and Section 2.3.1.2.9, “Column::getScale()”.

Return Value. No return value.

2.3.1.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 2.3.1.2.8, “Column::getPrecision()”, and Section 2.3.1.2.9, “Column::getScale()”.

Return Value. No return value.

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

The NDB API handles column names in case-sensitive fashion; “myColumn” and “Mycolumn” are not considered to refer to the same column. It is recommended that you minimize the possibility of errors from using the wrong lettercase by naming all columns consistently using only uppercase or only lowercase.

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.

2.3.1.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 2.3.1.2.11, “Column::getCharset()”.

Return Value. No return value.

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

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

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

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

2.3.1.2.31. `Column::setArrayType()`

Description. Sets the array type for the column.

Signature.

void setArrayType
    (
      ArrayType type
    )

Parameters. A Column::ArrayType value. See Section 2.3.1.1.1, “The Column::ArrayType Type”, for more information.

Return Value. None.

2.3.1.2.32. `Column::setStorageType()`

Description. Sets the storage type for the column.

Signature.

void setStorageType
    (
      StorageType type
    )

Parameters. A Column::StorageType value. See Section 2.3.1.1.2, “The Column::StorageType Type”, for more information.

Return Value. None.

2.3.2. The `Datafile` Class

2.3.2.1. Datafile Methods

Abstract

This section covers the Datafile class.

Parent class. Object

Child classes. None

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.

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 file system 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 tablespace
`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 file system
`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 2.3.2.1, “Datafile Methods”.

Types. The Datafile class defines no public types.

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

2.3.2.1. `Datafile` Methods

2.3.2.1.1. Datafile Class Constructor
2.3.2.1.2. Datafile::getPath()
2.3.2.1.3. Datafile::getSize()
2.3.2.1.4. Datafile::getFree()
2.3.2.1.5. Datafile::getTablespace()
2.3.2.1.6. Datafile::getTablespaceId()
2.3.2.1.7. Datafile::getNode()
2.3.2.1.8. Datafile::getFileNo()
2.3.2.1.9. Datafile::getObjectStatus()
2.3.2.1.10. Datafile::getObjectVersion()
2.3.2.1.11. Datafile::getObjectId()
2.3.2.1.12. Datafile::setPath()
2.3.2.1.13. Datafile::setSize()
2.3.2.1.14. Datafile::setTablespace()
2.3.2.1.15. Datafile::setNode()

Abstract

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

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

2.3.2.1.2. `Datafile::getPath()`

Description. This method returns the file system path to the datafile.

Signature.

const char* getPath
    (
      void
    ) const

Parameters. None.

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

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

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

2.3.2.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 2.3.2.1.6, “Datafile::getTablespaceId()”.

Signature.

const char* getTablespace
    (
      void
    ) const

Parameters. None.

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

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

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

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

2.3.2.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 2.3.20.1.3, “The Object::Status Type”.

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

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

2.3.2.1.12. `Datafile::setPath()`

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

Signature.

const char* getPath
    (
      void
    ) const

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

Return Value. None.

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

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

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

2.3.3. The `Dictionary` Class

2.3.3.1. Dictionary Methods

Abstract

This section describes the Dictionary class.

Parent class. NdbDictionary

Child classes. List

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

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
`listEvents()`	Fetches a list of the events defined in the dictionary
`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 2.3.3.1, “Dictionary 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 2.3.1, “The Column Class”, for details.

Types. See Section 2.3.7, “The List Class”, and Section 2.3.27, “The Element Structure”.

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

2.3.3.1. `Dictionary` Methods

2.3.3.1.1. Dictionary Class Constructor
2.3.3.1.2. Dictionary::getTable()
2.3.3.1.3. Dictionary::getIndex()
2.3.3.1.4. Dictionary::getEvent()
2.3.3.1.5. Dictionary::getTablespace()
2.3.3.1.6. Dictionary::getLogfileGroup()
2.3.3.1.7. Dictionary::getDatafile()
2.3.3.1.8. Dictionary::getUndofile()
2.3.3.1.9. Dictionary::getNdbError()
2.3.3.1.10. Dictionary::createTable()
2.3.3.1.11. Dictionary::createIndex()
2.3.3.1.12. Dictionary::createEvent()
2.3.3.1.13. Dictionary::createTablespace()
2.3.3.1.14. Dictionary::createLogfileGroup()
2.3.3.1.15. Dictionary::createDatafile()
2.3.3.1.16. Dictionary::createRecord()
2.3.3.1.17. Dictionary::createUndofile()
2.3.3.1.18. Dictionary::dropTable()
2.3.3.1.19. Dictionary::dropIndex()
2.3.3.1.20. Dictionary::dropEvent()
2.3.3.1.21. Dictionary::dropTablespace()
2.3.3.1.22. Dictionary::dropLogfileGroup()
2.3.3.1.23. Dictionary::dropDatafile()
2.3.3.1.24. Dictionary::dropUndofile()
2.3.3.1.25. DIctionary::invalidateTable()
2.3.3.1.26. Dictionary::listObjects()
2.3.3.1.27. Dictionary::listIndexes()
2.3.3.1.28. Dictionary::listEvents()
2.3.3.1.29. Dictionary::releaseRecord()
2.3.3.1.30. Dictionary::removeCachedTable()
2.3.3.1.31. Dictionary::removeCachedIndex()

Abstract

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

2.3.3.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 2.3.8, “The Ndb Class”.

Return Value. A Dictionary object.

Destructor. The destructor takes no parameters and returns nothing.

protected ~Dictionary
    (
      void
    )

2.3.3.1.2. `Dictionary::getTable()`

Description. This method can be used to access the table with a known name. See Section 2.3.21, “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.

2.3.3.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 2.3.5, “The Index Class”, for information about this object.

2.3.3.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 2.3.4, “The Event Class”, for more information.

2.3.3.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 2.3.22, “The Tablespace Class”.

2.3.3.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 2.3.6, “The LogfileGroup Class”, for more information.

2.3.3.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 file system.

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 file system (string as character pointer)

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

2.3.3.1.8. `Dictionary::getUndofile()`

Description. This method gets an Undofile object, given the ID of the node where an undofile is located and the file system 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 file system (string as character pointer)

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

2.3.3.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 2.3.30, “The NdbError Structure”.

2.3.3.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 2.3.21, “The Table Class”, for more information.

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

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

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

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

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

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

2.3.3.1.16. `Dictionary::createRecord()`

Description. This method is used to create an NdbRecord object for use in table or index scanning operations. (See Section 2.3.25, “The NdbRecord Interface”.)

Dctionary::createRecord() is available beginning with MySQL Cluster NDB 6.2.3.

Signature. To create an NdbRecord for use in table operations:

NdbRecord* createRecord
    (
      const Table* table,
      const RecordSpecification* recordSpec,
      Uint32 length,
      Uint32 elementSize
    )

To create an NdbRecord for use in index operations, you can use either of the following:

NdbRecord* createRecord
    (
      const Index* index,
      const Table* table,
      const RecordSpecification* recordSpec,
      Uint32 length,
      Uint32 elementSize
    )

NdbRecord* createRecord
    (
      const Index* index,
      const RecordSpecification* recordSpec,
      Uint32 length,
      Uint32 elementSize
    )

Parameters. Dictionary::createRecord() takes the following parameters:

If this NdbRecord is to be used with an index, a pointer to the corresponding Index object. If the NdbRecord is to be used with a table, this parameter is omitted. (See Section 2.3.5, “The Index Class”.)
A pointer to a Table object representing the table to be scanned. If the Ndbrecord produced is to be used with an index, then this optionally specifies the table containing that index. (See Section 2.3.21, “The Table Class”.)
A RecordSpecification used to describe a column. (See Section 2.3.32, “The RecordSpecification Structure”.
The length of the record.
The size of the elements making up this record.

Return Value. An NdbRecord for use in operations involving the given table or index.

Example. See Section 2.3.25, “The NdbRecord Interface”.

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

2.3.3.1.18. `Dictionary::dropTable()`

Description. Drops a table given an instance of Table.

Signature.

int dropTable
    (
      const Table& table
    )

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

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

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

2.3.3.1.20. `Dictionary::dropEvent()`

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

Signature.

int dropEvent
    (
      const char* name,
      int         force = 0
    )

Parameters. This method takes two parameters:

The name of the event to be dropped, as a string.
By default, dropEvent() fails if the event specified does not exist. You can override this behavior by passing any nonzero value for the (optional) force argument; in this case no check is made as to whether there actually is such an event, and an error is returned only if the event exists but it was for whatever reason not possible to drop it.

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

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

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

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

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

2.3.3.1.25. `DIctionary::invalidateTable()`

Description. This method is used to invalidate a cached table object.

Signature.

void invalidateTable
    (
      const char* name
    )

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

Return Value. None.

2.3.3.1.26. `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 2.3.7, “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 2.3.20.1.5, “The Object::Type Type”.) If type is not given, then the list contains all of the dictionary's objects.

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

2.3.3.1.27. `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 2.3.7, “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.

2.3.3.1.28. `Dictionary::listEvents()`

Description. This method returns a list of all events defined within the dictionary.

This method was added in MySQL Cluster NDB 6.1.13.

Signature.

int listEvents
    (
      List& list
    )

int listEvents
    (
      List& list
    ) const

Parameters. A reference to a List object. (See Section 2.3.7, “The List Class”.)

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

2.3.3.1.29. `Dictionary::releaseRecord()`

Description. This method is used to free an NdbRecord after it is no longer needed.

Signature.

void releaseRecord
    (
      NdbRecord* record
    )

Parameters. The NdbRecord to be cleaned up.

Return Value. None.

Example. See Section 2.3.25, “The NdbRecord Interface”.

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

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

2.3.4. The `Event` Class

2.3.4.1. Event Types
2.3.4.2. Event Methods

Abstract

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

Parent class. NdbDictionary

Child classes. None

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

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 2.3.4.2, “Event Methods”.

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

2.3.4.1. `Event` Types

2.3.4.1.1. The Event::TableEvent Type
2.3.4.1.2. The Event::EventDurability Type
2.3.4.1.3. The Event::EventReport Type

Abstract

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

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

2.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. Important The value `ED_SESSION` is reserved for future use and is not yet supported in any MySQL Cluster release.
`ED_TEMPORARY`	Any application may use the event, but it is deleted following a cluster restart. Important The value `ED_TEMPORARY` is reserved for future use and is not yet supported in any MySQL Cluster release.
`ED_PERMANENT`	Any application may use the event, and it persists until deleted by an application — even following a cluster. restart

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

2.3.4.2. `Event` Methods

2.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 2.3.21, “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.

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

2.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 2.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 2.3.21, “The Table Class”.)

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

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

2.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 2.3.4.1.2, “The Event::EventDurability Type”, for possible values.

2.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 2.3.4.1.3, “The Event::EventReport Type”.

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

2.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 2.3.4.2.8, “Event::getNoOfEventColumns()”).

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

2.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 2.3.20.1.3, “The Object::Status Type”.

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

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

2.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 2.3.4.2.6, “Event::getDurability()”).

Note

You can also set the event's name when first creating it. See Section 2.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.

2.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 2.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 2.3.21, “The Table Class”) on which events are to be detected.

Return Value. None.

2.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 2.3.4.1.1, “The Event::TableEvent Type” for possible values.

Return Value. None.

2.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 2.3.4.1.2, “The Event::EventDurability Type”, for possible values.

Return Value. None.

2.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 2.3.4.1.3, “The Event::EventReport Type”.

Signature.

void setReport
    (
      EventReport er
    )

Parameters. An EventReport option value.

Return Value. None.

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

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

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

Signature.

void mergeEvents
    (
      bool flag
    )

Parameters. A Boolean flag value.

Return Value. None.

2.3.5. The `Index` Class

2.3.5.1. The Index::Type Type
2.3.5.2. Index Methods

Abstract

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

Parent class. NdbDictionary

Child classes. None

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 2.3.10, “The NdbDictionary Class”, and Section 2.3.20, “The Object Class”.

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 2.3.5.2, “Index Methods”.

Types. Index has one public type, the Type type. For a discussion of Type, see Section 2.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.

2.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 2.3.20.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`	Nonunique, ordered index

2.3.5.2. `Index` Methods

2.3.5.2.1. Index Class Constructor
2.3.5.2.2. Index::getName()
2.3.5.2.3. Index::getTable()
2.3.5.2.4. Index::getNoOfColumns()
2.3.5.2.5. Index::getColumn()
2.3.5.2.6. Index::getType()
2.3.5.2.7. Index::getLogging()
2.3.5.2.8. Index::getObjectStatus()
2.3.5.2.9. Index::getObjectVersion()
2.3.5.2.10. Index::getObjectId()
2.3.5.2.11. Index::setName()
2.3.5.2.12. Index::setTable()
2.3.5.2.13. Index::addColumn()
2.3.5.2.14. Index::addColumnName()
2.3.5.2.15. Index::addColumnNames()
2.3.5.2.16. Index::setType()
2.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().

2.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 2.3.5.2.11, “Index::setName()”.

Return Value. A new instance of Index.

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

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

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

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

2.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 2.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 2.3.1, “The Column Class”.

2.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 2.3.5.1, “The Index::Type Type”, for possible values.

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

2.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 2.3.20.1.3, “The Object::Status Type”, for more information.

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

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

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

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

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

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

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

2.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 2.3.5.1, “The Index::Type Type”.

Return Value. None.

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

2.3.6. The `LogfileGroup` Class

2.3.6.1. LogfileGroup Methods

Abstract

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

Parent class. NdbDictionary

Child classes. None

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 MySQL Cluster Disk Data Tables, 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 logfile groups; thus the LogfileGroup class is unavailable for NDB API applications written against these MySQL versions.

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 2.3.6.1, “LogfileGroup Methods”.

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 2.3.26, “The AutoGrowSpecification Structure”.

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

2.3.6.1. `LogfileGroup` Methods

2.3.6.1.1. LogfileGroup Constructor
2.3.6.1.2. LogfileGroup::getName()
2.3.6.1.3. LogfileGroup::getUndoBufferSize()
2.3.6.1.4. LogfileGroup::getAutoGrowSpecification()
2.3.6.1.5. LogfileGroup::getUndoFreeWords()
2.3.6.1.6. LogfileGroup::getObjectStatus()
2.3.6.1.7. LogfileGroup::getObjectVersion()
2.3.6.1.8. LogfileGroup::getObjectId()
2.3.6.1.9. LogfileGroup::setName()
2.3.6.1.10. LogfileGroup::setUndoBufferSize()
2.3.6.1.11. LogfileGroup::setAutoGrowSpecification()

Abstract

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

2.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 2.3.3, “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...]

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

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

2.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 2.3.26, “The AutoGrowSpecification Structure”, for details.

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

2.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 2.3.20.1.3, “The Object::Status Type” for possible values.

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

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

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

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

2.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 2.3.26, “The AutoGrowSpecification Structure”.

Return Value. None.

2.3.7. The `List` Class

Abstract

This section covers the List class.

Parent class. Dictionary

Child classes. None

Description. The List class is a Dictionary subclass that is used for representing lists populated by the methods Dictionary::listObjects(), Dictionary::listIndexes(), and Dictionary::listEvents(). (See Section 2.3.3.1.26, “Dictionary::listObjects()”, Section 2.3.3.1.27, “Dictionary::listIndexes()”, and Section 2.3.3.1.28, “Dictionary::listEvents()”, for more information about these methods.)

Class Methods. This class has only two methods, a constructor and a destructor. Neither method takes any arguments.

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 2.3.27, “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 2.3.3, “The Dictionary Class”.

2.3.8. The `Ndb` Class

2.3.8.1. Ndb Methods

Abstract

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

Parent class. None

Child classes. None

Description. Any nontrivial 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.

It is also possible to use multiple Ndb objects to perform operations on different clusters in a single application. See the Note on Application-Level Partitioning for conditions and restrictions applying to such usage.

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.
`getDictionary()`	Gets a dictionary, which is used for working with database schema information.
`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 2.3.19, “The `NdbTransaction` Class”.)
`closeTransaction()`	Closes a transaction.
`computeHash()`	Computes a distribution hash value.
`createEventOperation()`	Creates a subscription to a database event. (See Section 2.3.11, “The `NdbEventOperation` Class”.)
`dropEventOperation()`	Drops a subscription to a database event.
`pollEvents()`	Waits for an event to occur.
`getNdbError()`	Retrieves an error. (See Section 2.3.30, “The `NdbError` Structure”.)
`getReference()`	Retrieves a reference or identifier for the `Ndb` object instance.

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

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

2.3.8.1. `Ndb` Methods

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

Abstract

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

2.3.8.1.1. `Ndb` Class Constructor

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

Signature.

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

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

ndb_cluster_connection is an instance of Ndb_cluster_connection, which represents a cluster connectstring. (See Section 2.3.24, “The Ndb_cluster_connection Class”.)
catalogName is an optional parameter providing a namespace for the tables and indexes created in any connection from the Ndb object.
This is equivalent to what mysqld considers “the database”.
The default value for this parameter is an empty string.
The optional schemaName provides an additional namespace for the tables and indexes created in a given catalog.
The default value for this parameter is the string “def”.

Return Value. An Ndb object.

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

2.3.8.1.2. `Ndb::init()`

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

Signature.

int init
    (
      int maxNoOfTransactions = 4
    )

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

Note

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

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

0: indicates that the Ndb object was initialised successfully.
-1: indicates failure.

2.3.8.1.3. `Ndb::getDictionary()`

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

Note

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

Signature.

NdbDictionary::Dictionary* getDictionary
    (
      void
    ) const

Parameters. None.

Return Value. An instance of the Dictionary class.

2.3.8.1.4. `Ndb::getDatabaseName()`

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

Signature.

const char* getDatabaseName
    (
      void
    )

Parameters. None.

Return Value. The name of the current database.

2.3.8.1.5. `Ndb::setDatabaseName()`

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

Signature.

void setDatabaseName
    (
      const char *databaseName
    )

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

Return Value. N/A.

2.3.8.1.6. `Ndb::getDatabaseSchemaName()`

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

Signature.

const char* getDatabaseSchemaName
    (
      void
    )

Parameters. None.

Return Value. The name of the current database schema.

2.3.8.1.7. `Ndb::setDatabaseSchemaName()`

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

Signature.

void setDatabaseSchemaName
    (
      const char *databaseSchemaName
    )

Parameters. The name of the database schema.

Return Value. N/A.

2.3.8.1.8. `Ndb::startTransaction()`

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

Important

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

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

Signature.

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

Parameters. This method takes three parameters, as follows:

table: A pointer to a Table object. (See Section 2.3.21, “The Table Class”.) This is used to determine on which node the transaction coordinator should run.
keyData: A pointer to a partition key corresponding to table.
keyLen: The length of the partition key, expressed in bytes.

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

Signature.

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

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

A pointer to a table (NdbDictionary::Table object) used for deciding which node should act as the transaction coordinator.
A null-terminated array of pointers to the values of the distribution key columns. The length of the key part is read from metadata and checked against the passed value.
A Key_part_ptr is defined as shown in Section 2.3.29, “The Key_part_ptr Structure”.
A pointer to a temporary buffer, used to calculate the hash value.
The length of the buffer.

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

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

Key_part_ptr distkey[2];

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

unsigned long long distkeyValue= 23;

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

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

The length of this pointer would be set accordingly:

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

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

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

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

xfrmbuf= NULL;
xfrmbuflen= 0;

Note

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

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

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

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

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

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

Return Value. On success, an NdbTransaction object (see Section 2.3.19, “The NdbTransaction Class”). In the event of failure, NULL is returned.

2.3.8.1.9. `Ndb::closeTransaction()`

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

Important

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

Signature.

void closeTransaction
    (
      NdbTransaction *transaction
    )

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

Return Value. N/A.

2.3.8.1.10. `Ndb::computeHash()`

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

Important

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

Signature.

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

Parameters. This method takes the following parameters:

If the method call id successful, hashvalueptr is set to the computed hash value.
A pointer to a table (see Section 2.3.21, “The Table Class”).
keyData is a null-terminated array of pointers to the key parts that are part of the table's distribution key. The length of each key part is read from metadata and checked against the passed value (see Section 2.3.29, “The Key_part_ptr Structure”).
xfrmbuf is a pointer to temporary buffer used to calculate the hash value.
xfrmbuflen is the length of this buffer.
Note
If xfrmbuf is NULL (the default), then a call to malloc() or free() is made automatically, as appropriate. computeHash() fails if xfrmbuf is not NULL and xfrmbuflen is too small.

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

2.3.8.1.11. `Ndb::createEventOperation`

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

Signature.

NdbEventOperation* createEventOperation
    (
      const char *eventName
    )

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

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

2.3.8.1.12. `Ndb::dropEventOperation()`

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

Signature.

int dropEventOperation
    (
      NdbEventOperation *eventOp
    )

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

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

2.3.8.1.13. `Ndb::pollEvents()`

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

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

Signature.

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

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

The maximum time to wait, in milliseconds, before “giving up” and reporting that no events were available (that is, before the method automatically returns 0).
The index of the most recent global checkpoint. Normally, this may safely be permitted to assume its default value, which is 0.

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

> 0: There are events available in the queue.
0: There are no events available.
< 0: Indicates failure (possible error).

2.3.8.1.14. `Ndb::nextEvent()`

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

Signature.

NdbEventOperation* nextEvent
    (
      void
    )

Parameters. None.

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

2.3.8.1.15. `Ndb::getNdbError()`

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

Signature. The getNdbError() method actually has two variants. The first of these simply gets the most recent error to have occurred:

const NdbError& getNdbError
    (
      void
    )

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

const NdbError& getNdbError
    (
      int errorCode
    )

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

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

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

2.3.8.1.16. `Ndb::getReference()`

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

Signature.

Uint32 getReference
    (
      void
    )

Parameters. None.

2.3.9. The `NdbBlob` Class

2.3.9.1. NdbBlob Types
2.3.9.2. NdbBlob 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.

Parent class. None

Child classes. None

Description. An instance of NdbBlob is created using the NdbOperation::getBlobHandle() method during the operation preparation phase. (See Section 2.3.15, “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 2.3.1, “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 2.3.11, “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 nonnullable.
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 nonnullable.
NdbOperation::deleteTuple() creates implicit, nonaccessible 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 nonaccessible blob handles.
An operation which is returned by lockCurrentTuple() cannot update blob values.

See Section 2.3.15, “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.

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 blob 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.
`getNdbOperation()`	Get a pointer to the operation (`NdbOperation` object) to which this `NdbBlob` object belonged when created.

Note

getBlobTableName() and getBlobEventName() 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 2.3.9.2, “NdbBlob Methods”.

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 2.3.9.1, “NdbBlob Types”.

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

Public methods and types of the
NdbBlob class.

2.3.9.1. `NdbBlob` Types

2.3.9.1.1. The NdbBlob::ActiveHook Type
2.3.9.1.2. The NdbBlob::State Type

Abstract

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

2.3.9.1.1. The `NdbBlob::ActiveHook` Type

Abstract

ActiveHook is a datatype defined for use as a callback for the setActiveHook() method. (See Section 2.3.9.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.

2.3.9.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
`Idle`	The `NdbBlob` has not yet been prepared for use with any operations.
`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.

2.3.9.2. `NdbBlob` Methods

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

2.3.9.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 2.3.9.1.2, “The NdbBlob::State Type”.

Signature.

State getState
    (
      void
    )

Parameters. None.

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

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

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

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

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

2.3.9.2.6. `NdbBlob::getNull()`

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

Signature.

int getNull
    (
      int& isNull
    )

Parameters. A reference to an integer isNull. Following invocation, this parameter has one of the following values, interpreted as shown here:

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

Return Value. None.

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

2.3.9.2.8. `NdbBlob::getLength()`

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.

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

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

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

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

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

2.3.9.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 2.3.1, “The Column Class”.)

2.3.9.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 nonzero error code.

Signature.

const NdbError& getNdbError
    (
      void
    ) const

Parameters. None.

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

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

2.3.9.2.17. `NdbBlob::blobsNextBlob()`

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

Signature.

NdbBlob* blobsNextBlob
    (
      void
    )

Parameters. None.

Return Value. A pointer to the desired blob.

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

2.3.9.2.19. `NdbBlob::getBlobTableName()`

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.

2.3.9.2.20. `NdbBlob::getNdbOperation()`

Description. This method can be used to find the operation with which the handle for this NdbBlob is associated.

NdbBlob::getNdbOperation() is available beginning with MySQL Cluster NDB 6.2.17 and MySQL Cluster NDB 6.3.19.

Signature.

const NdbOperation* getNdbOperation
    (
      void
    ) const

Parameters. None.

Return Value. A pointer to an operation.

Important

The operation referenced by the pointer retruned by this method may be represented by either an NdbOperation or NdbScanOperation object.

See Section 2.3.15, “The NdbOperation Class”, and Section 2.3.18, “The NdbScanOperation Class”, for more information.

2.3.10. The `NdbDictionary` Class

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.

Parent class. None

Child classes. Dictionary, Column, Object

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 MySQL Cluster Disk Data tables (introduced in MySQL 5.1).

Warning

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. It is possible that a table from which one or more indexes have been dropped using the NDB API will no longer be usable by MySQL following such operations. In this event, the table must be dropped, and then re-created using MySQL to make it accessible to MySQL once more.

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.

2.3.11. The `NdbEventOperation` Class

2.3.11.1. The NdbEventOperation::State Type
2.3.11.2. NdbEventOperation Methods

Abstract

This section describes the NdbEventOperation class, which is used to monitor changes (events) in a database. It provides the core functionality used to implement MySQL Cluster Replication.

Parent class. None

Child classes. None

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 2.3.3.1.12, “Dictionary::createEvent()”.
An NdbEventOperation object is instantiated using Ndb::createEventOperation(), which acts on instance of NdbDictionary::Event. See Section 2.3.8.1.11, “Ndb::createEventOperation”.

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

Tip

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

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

The maximum number of active NdbEventOperation objects is currently fixed at compile time at 2 * MaxNoOfTables. This may become a separately configurable parameter in a future release.
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 2.3.8.1.13, “Ndb::pollEvents()”, and Section 2.3.8.1.14, “Ndb::nextEvent()”.
Event code does not check the table schema version. When a table is dropped, make sure that you drop any associated events.
We intend to remedy this issue in a future release of MySQL Cluster and the NDB API.
If you have received a complete epoch, events from this epoch are not re-sent, even in the event of a node failure. However, if a node failure has occurred, subsequent epochs may contain duplicate events, which can be identified by duplicated primary keys.
In the MySQL Cluster replication code, duplicate primary keys on INSERT operations are normally handled by treating such inserts as REPLACE operations.

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'

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 2.3.11.2, “NdbEventOperation Methods”.

Types. NdbEventOperation defines one enumerated type. See Section 2.3.11.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.

2.3.11.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 2.3.11.2.1, “NdbEventOperation::getState()”, for more information.

2.3.11.2. `NdbEventOperation` Methods

2.3.11.2.1. NdbEventOperation::getState()
2.3.11.2.2. NdbEventOperation::getEventType()
2.3.11.2.3. NdbEventOperation::getValue()
2.3.11.2.4. NdbEventOperation::getPreValue()
2.3.11.2.5. NdbEventOperation::getBlobHandle()
2.3.11.2.6. NdbEventOperation::getPreBlobHandle()
2.3.11.2.7. NdbEventOperation::getGCI()
2.3.11.2.8. NdbEventOperation::getLatestGCI()
2.3.11.2.9. NdbEventOperation::getNdbError()
2.3.11.2.10. NdbEventOperation::isConsistent()
2.3.11.2.11. NdbEventOperation::tableNameChanged()
2.3.11.2.12. NdbEventOperation::tableFrmChanged()
2.3.11.2.13. NdbEventOperation::tableFragmentationChanged()
2.3.11.2.14. NdbEventOperation::tableRangeListChanged()
2.3.11.2.15. NdbEventOperation::mergeEvents()
2.3.11.2.16. NdbEventOperation::execute()

Abstract

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

2.3.11.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 2.3.11.1, “The NdbEventOperation::State Type”.

2.3.11.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 2.3.4.1.1, “The Event::TableEvent Type”.

2.3.11.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 a non-NULL value.

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 2.3.11.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 2.3.16, “The NdbRecAttr Class”.

2.3.11.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 2.3.11.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 2.3.16, “The NdbRecAttr Class”.

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

Signature.

NdbBlob* getBlobHandle
    (
      const char* name
    )

Parameters. The name of the blob attribute.

Return Value. A pointer to an NdbBlob object. See Section 2.3.9, “The NdbBlob Class”.

2.3.11.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 2.3.11.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 2.3.9, “The NdbBlob Class”.

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

2.3.11.2.8. `NdbEventOperation::getLatestGCI()`

Description. This method retrieves the most recent GCI.

Beginning with MySQL Cluster NDB 6.2.5, this method actually returns the latest epoch number, and all references to GCIs in the documentation for this method when using this or a later MySQL Cluster NDB version should be taken to mean epoch numbers instead. This is a consequence of the implementation for micro-CGPs.

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.

2.3.11.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 2.3.30, “The NdbError Structure”.

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

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

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

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

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

2.3.11.2.15. `NdbEventOperation::mergeEvents()`

Description. This method is used to set the merge events flag. For information about event merging, see Section 2.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.

2.3.11.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 a value other than NULL. One of getValue(), getPreValue(), getBlobValue(), or getPreBlobValue() must be called before invoking execute().

Important

Before attempting to use this method, you should have read the explanations provided in Section 2.3.8.1.14, “Ndb::nextEvent()”, and Section 2.3.11.2.3, “NdbEventOperation::getValue()”. Also see Section 2.3.11, “The NdbEventOperation Class”.

Signature.

int execute
    (
      void
    )

Parameters. None.

Return Value. This method returns 0 on success and -1 on failure.

2.3.12. The `NdbIndexOperation` Class

2.3.12.1. NdbIndexOperation Methods

Abstract

This section describes the NdbIndexOperation class and its public methods.

Parent class. NdbOperation

Child classes. None

Description. NdbIndexOperation represents an index operation for use in transactions. This class inherits from NdbOperation; see Section 2.3.15, “The NdbOperation Class”, for more information.

Note

NdbIndexOperation can be used only with unique hash indexes; to work with ordered indexes, use NdbIndexScanOperation. See Section 2.3.13, “The NdbIndexScanOperation Class”.

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 2.3.15.2, “NdbOperation Methods”.

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

2.3.12.1. `NdbIndexOperation` Methods

2.3.12.1.1. NdbIndexOperation::getIndex()
2.3.12.1.2. NdbIndexOperation::readTuple()
2.3.12.1.3. NdbIndexOperation::updateTuple()
2.3.12.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 2.3.19.2.4, “NdbTransaction::getNdbIndexOperation()”.

2.3.12.1.1. `NdbIndexOperation::getIndex()`

Description.

Signature.

const NdbDictionary::Index* getIndex
    (
      void
    ) const

Parameters. None.

Return Value. A pointer to an Index object. See Section 2.3.5, “The Index Class”.

2.3.12.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 2.3.19.2.5, “NdbTransaction::execute()”.

Signature.

int readTuple
    (
      LockMode mode
    )

Parameters. mode specifies the locking mode used by the read operation. See Section 2.3.15.1.3, “The NdbOperation::LockMode Type”, for possible values.

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

2.3.12.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 2.3.19.2.5, “NdbTransaction::execute()”.

Signature.

int updateTuple
    (
      void
    )

Parameters. None.

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

2.3.12.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 2.3.19.2.5, “NdbTransaction::execute()”.

Signature.

int deleteTuple
    (
      void
    )

Parameters. None.

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

2.3.13. The `NdbIndexScanOperation` Class

2.3.13.1. The NdbIndexScanOperation::BoundType Type
2.3.13.2. NdbIndexScanOperation Methods

Abstract

This section discusses the NdbIndexScanOperation class and its public members.

Parent class. NdbScanOperation

Child classes. None

Description. The NdbIndexScanOperation class represents a scan operation using an ordered index. This class inherits from NdbScanOperation and NdbOperation. See Section 2.3.18, “The NdbScanOperation Class”, and Section 2.3.15, “The NdbOperation Class”, for more information about these classes.

Note

NdbIndexScanOperation is for use with ordered indexes only; to work with unique hash indexes, use NdbIndexOperation.

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 2.3.13.2, “NdbIndexScanOperation Methods”.

Types. The NdbIndexScanOperation class defines one public type. See Section 2.3.13.1, “The NdbIndexScanOperation::BoundType Type”.

Beginning with MySQL Cluster NDB 6.2.3, this class defines an additional struct for use with operations employing NdbRecord; see Section 2.3.28, “The IndexBound Structure”, and Section 2.3.25, “The NdbRecord Interface”, for more information.

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”

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

2.3.13.2. `NdbIndexScanOperation` Methods

2.3.13.2.1. NdbIndexScanOperation::get_range_no()
2.3.13.2.2. NdbIndexScanOperation::getSorted()
2.3.13.2.3. NdbIndexScanOperation::getDescending()
2.3.13.2.4. NdbIndexScanOperation::readTuples()
2.3.13.2.5. NdbIndexScanOperation::setBound
2.3.13.2.6. NdbIndexScanOperation::reset_bounds()
2.3.13.2.7. NdbIndexScanOperation::end_of_bound()

Abstract

This section lists and describes the public methods of the NdbIndexScanOperation class.

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

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

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

2.3.13.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 2.3.15.1.3, “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 2.3.18.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.

2.3.13.2.5. `NdbIndexScanOperation::setBound`

Description. This method defines a bound on an index key used in a range scan. In MySQL Cluster NDB 6.2.3 and later, it is also sets bounds for index scans defined using NdbRecord.

“Old” API usage (prior to introduction of NdbRecord). 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 nonstrict. 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 (“Old” API).

int setBound
    (
      const char* name,
      int         type,
      const void* value
    )

int setBound
    (
      Uint32      id,
      int         type,
      const void* value
    )

Parameters (“Old” API). 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 2.3.13.1, “The NdbIndexScanOperation::BoundType Type”.
A pointer to the bound value (use 0 for NULL).

As used with NdbRecord (MySQL Cluster NDB 6.2.3 and later). This method is called to add a range to an IndexScan operation which has been defined with a call to NdbTransaction::scanIndex(). To add more than one range, the index scan operation must have been defined with the SF_MultiRange flag set. (See Section 2.3.18.1, “The NdbScanOperation::ScanFlag Type”.)

Note

Where multiple numbered ranges are defined with multiple calls to setBound(), and the scan is ordered, the range number for each range must be larger than the range number for the previously defined range.

Signature (when used with NdbRecord). MySQL Cluster NDB 6.2.3 and later:

int setBound
    (
      const NdbRecord* keyRecord,
      const IndexBound& bound
    )

Parameters. As used with NdbRecord in MySQL Cluster NDB 6.2.3 and later, this method takes 2 parameters:

keyRecord: This is an NdbRecord structure corresponding to the key on which the index is defined.
The bound to add (see Section 2.3.28, “The IndexBound Structure”).

Starting with MySQL Cluster NDB 6.3.24 and NDB 7.0.4, an additional version of this method is available, which can be used when the application knows that rows in-range will be found only within a particular partition. This is the same as that shown previously, except for the addition of a PartitionSpecification. Doing so limits the scan to a single partition, improving system efficiency.

Signature (when specifying a partition).

int setBound
    (
      const NdbRecord* keyRecord,
      const IndexBound& bound,
      const Ndb::PartitionSpec* partInfo,
      Uint32 sizeOfPartInfo = 0
    )

Parameters (when specifying a partition). Beginning with MySQL Cluster NDB 6.3.24 and MySQL Cluster NDB 7.0.4, this method can be invoked with the following 4 parameters:

keyRecord: This is an NdbRecord structure (see Section 2.3.25, “The NdbRecord Interface”) corresponding to the key on which the index is defined.
The bound to be added to the scan (see Section 2.3.28, “The IndexBound Structure”).

Note

keyRecord and bound are defined and used in the same way as with the 2-parameter version of this method.

partInfo: This is a pointer to an Ndb::PartitionSpec, which provides extra information making it possible to scan a reduced set of partitions. See Section 2.3.31, “The PartitionSpec Structure”, for more information.
sizeOfPartInfo: The length of the partition specification.

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

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

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

2.3.14. The `NdbInterpretedCode` Class

2.3.14.1. NdbInterpretedCode Methods

Abstract

This section discusses the NdbInterpretedCode class, which can be used to prepare and execute an NDB interpreted program.

Beginning with MySQL Cluster NDB 6.2.14 and MySQL Cluster 6.3.12, you must use the NdbInterpretedCode class (rather than NdbScanOperation) to write interpreted programs used for scans.

Parent class. None.

Child classes. None.

Description. NdbInterpretedCode represents an interpreted program for use in operations created using NdbRecord (see Section 2.3.25, “The NdbRecord Interface”), or with scans created using the old API. The NdbScanFilter class can also be used to generate an NDB interpreted program using this class. (See Section 2.3.17, “The NdbScanFilter Class”.) This class was added in MySQL Cluster NDB 6.2.14 and 6.3.12.

Important

This interface is still under development, and so is subject to change without notice. The NdbScanFilter API is a more stable API for defining scanning and filtering programs. See Section 2.3.17, “The NdbScanFilter Class”, for more information.

Using NdbInterpretedCode. To create an NdbInterpretedCode object, invoke the constructor, optionally supplying a table for the program to operate on, and a buffer for program storage and finalization. If no table is supplied, then only instructions which do not access table attributes can be used.

Note

Each NDB API operation applies to one table, and so does any NdbInterpretedCode program attached to that operation.

If no buffer is supplied, then an internal buffer is dynamically allocated and extended as necessary. Once the NdbInterpretedCode object is created, you can add instructions and labels to it by calling the appropriate methods as described later in this section. When the program has completed, finalize it by calling the finalise() method, which resolves any remaining internal branches and calls to label and subroutine offsets.

Note

A single finalized NdbInterpretedCode program can be used by more than one operation. It need not be re-prepared for successive operations.

To use the program with NdbRecord operations and scans, pass it at operation definition time via the OperationOptions or ScanOptions parameter. Alternatively, you can use the program with old-style API scans by passing it via the setInterpretedProgram() method. When the program is no longer required, the NdbInterpretedCode object can be deleted, along with any user-supplied buffer.

Error checking. For reasons of efficiency, methods of this class provide minimal error checking.

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

Method	Purpose / Use
`NdbInterpretedCode()`	Class constructor
`load_const_null()`	Load a `NULL` value into a register
`load_const_u16()`	Load a 16-bit numeric value into a register
`load_const_u32()`	Load a 32-bit numeric value into a register
`load_const_u64()`	Load a 64-bit numeric value into a register
`read_attr()`	Read a register value into a table column
`write_attr()`	Write a table column value into a register
`add_reg()`	Add two register values and store the result in a third register
`sub_reg()`	Subtract two register values and store the result in a third register
`def_label()`	Create a label for use within the interpreted program
`branch_label()`	Unconditional jump to a label
`branch_ge()`	Jump if one register value is greater than or equal to another
`branch_gt()`	Jump if one register value is greater than another
`branch_le()`	Jump if one register value is less than or equal to another
`branch_lt()`	Jump if one register value is less than another
`branch_eq()`	Jump if one register value is equal to another
`branch_ne()`	Jump if one register value is not equal to another
`branch_ne_null()`	Jump if a register value is not `NULL`
`branch_eq_null()`	Jump if a register value is `NULL`
`branch_col_eq()`	Jump if a column value is equal to another
`branch_col_ne()`	Jump if a column value is not equal to another
`branch_col_lt()`	Jump if a column value is less than another
`branch_col_le()`	Jump if a column value is less than or equal to another
`branch_col_gt()`	Jump if a column value is greater than another
`branch_col_ge()`	Jump if a column value is greater than or equal to another
`branch_col_eq_null()`	Jump if a column value is `NULL`
`branch_col_ne_null()`	Jump if a column value is not `NULL`
`branch_col_like()`	Jump if a column value matches a pattern
`branch_col_notlike()`	Jump if a column value does not match a pattern
`branch_col_and_mask_eq_mask()`	Jump if a column value `AND`ed with a bitmask is equal to the bitmask
`branch_col_and_mask_ne_mask()`	Jump if a column value `AND`ed with a bitmask is not equal to the bitmask
`branch_col_and_mask_eq_zero()`	Jump if a column value `AND`ed with a bitmask is equal to `0`
`branch_col_and_mask_ne_zero()`	Jump if a column value `AND`ed with a bitmask is not equal to `0`
`interpret_exit_ok()`	Return a row as part of the result
`interpret_exit_nok()`	Do not return a row as part of the result
`interpret_last_row()`	Return a row as part of the result, and do not check any more rows in this fragment
`add_val()`	Add a value to a table column value
`sub_val()`	Subtract a value from a table column value
`def_sub()`	Define a subroutine
`call_sub()`	Call a subroutine
`ret_sub()`	Return from a subroutine
`finalise()`	Completes interpreted program and prepares it for use
`getTable()`	Gets the table on which the program is defined
`getNdbError()`	Gets the most recent error associated with this `NdbInterpretedCode` object
`getWordsUsed()`	Gets the number of words used in the buffer

For detailed descriptions, signatures, and examples of use for each of these methods, see Section 2.3.14.1, “NdbInterpretedCode Methods”.

Types. This class defines no public types.

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

Public methods of the
NdbInterpretedCode class.

2.3.14.1. `NdbInterpretedCode` Methods

2.3.14.1.1. NdbInterpretedCode Constructor
2.3.14.1.2. NdbInterpretedCode Methods for Loading Values into Registers
2.3.14.1.3. NdbInterpretedCode Methods for Copying Values Between Registers and Table Columns
2.3.14.1.4. NdbInterpretedCode Register Arithmetic Methods
2.3.14.1.5. NdbInterpretedCode: Labels and Branching
2.3.14.1.6. NdbInterpretedCode::def_label()
2.3.14.1.7. NdbInterpretedCode::branch_label()
2.3.14.1.8. Register-Based NdbInterpretedCode Branch Operations
2.3.14.1.9. Column-Based NdbInterpretedCode Branch Operations
2.3.14.1.10. Pattern-Based NdbInterpretedCode Branch Operations
2.3.14.1.11. NdbInterpretedCode Bitwise Comparison Operations
2.3.14.1.12. NdbInterpretedCode Result Handling Methods
2.3.14.1.13. NdbInterpretedCode Convenience Methods
2.3.14.1.14. Using Subroutines with NdbInterpretedCode
2.3.14.1.15. NdbInterpretedCode Utility Methods

2.3.14.1.1. `NdbInterpretedCode` Constructor

Description. This is the NdbInterpretedCode class constuctor.

Signature.

NdbInterpretedCode
    (
      const NdbDictionary::Table* table = 0,
      Uint32* buffer = 0,
      Uint32 buffer_word_size = 0
    )

Parameters. The NdbInterpretedCode constructor takes three parameters, as described here:

The table against which which this program is to be be run. This parameter must be supplied if the program is table-specific — that is, if it reads from or writes to columns in a table.
A pointer to a buffer of 32-bit words used to store the program.
buffer_word_size is the length of the buffer passed in. If the program exceeds this length then adding new instructions will fail with error 4518 Too many instructions in interpreted program.
Alternatively, if no buffer is passed, a buffer will be dynamically allocated internally and extended to cope as instructions are added.

Return Value. An instance of NdbInterpretedCode.

2.3.14.1.2. `NdbInterpretedCode` Methods for Loading Values into Registers

2.3.14.1.2.1. NdbInterpretedCode::load_const_null()
2.3.14.1.2.2. NdbInterpretedCode::load_const_u16()
2.3.14.1.2.3. NdbInterpretedCode::load_const_u32()
2.3.14.1.2.4. NdbInterpretedCode::load_const_u64()

The methods described in this section are used to load constant values into NdbInterpretedCode program registers. The space required by each of these methods is shown in the following table:

Method	Buffer (words)	Request message (words)
`load_const_null()`	1	1
`load_const_u16()`	1	1
`load_const_u32()`	2	2
`load_const_u64()`	3	3

2.3.14.1.2.1. `NdbInterpretedCode::load_const_null()`

Description. This method is used to load a NULL value into a register.

Signature.

int load_const_null
    (
      Uint32 RegDest
    )

Parameters. This method takes a single parameter, the register into which to place the NULL.

Return Value. Returns 0 on success, -1 otherwise.

2.3.14.1.2.2. `NdbInterpretedCode::load_const_u16()`

Description. This method loads a 16-bit value into the specified interpreter register.

Signature.

int load_const_u16
    (
      Uint32 RegDest,
      Uint32 Constant
    )

Parameters. This method takes two parameters:

RegDest: The register into which the value should be loaded.
A Constant value to be loaded

Return Value. Returns 0 on success, -1 otherwise.

2.3.14.1.2.3. `NdbInterpretedCode::load_const_u32()`

Description. This method loads a 32-bit value into the specified interpreter register.

Signature.

int load_const_u32
    (
      Uint32 RegDest,
      Uint32 Constant
    )

Parameters. This method takes two parameters:

RegDest: The register into which the value should be loaded.
A Constant value to be loaded

Return Value. Returns 0 on success, -1 otherwise.

2.3.14.1.2.4. `NdbInterpretedCode::load_const_u64()`

Description. This method loads a 64-bit value into the specified interpreter register.

Signature.

int load_const_u64
    (
      Uint32 RegDest,
      Uint64 Constant
    )

Parameters. This method takes two parameters:

RegDest: The register into which the value should be loaded.
A Constant value to be loaded

Return Value. Returns 0 on success, -1 otherwise.

2.3.14.1.3. `NdbInterpretedCode` Methods for Copying Values Between Registers and Table Columns

2.3.14.1.3.1. NdbInterpretedCode::read_attr()
2.3.14.1.3.2. NdbInterpretedCode::write_attr()

This class provides two methods for copying values between a column in the current table row and a program register. The read_attr() method is used to copy a table column value into a program register; write_attr() is used to copy a value from a program register into a table column. Both of these methods require that the table being operated on was specified when creating the NdbInterpretedCode object for which they are called.

The space required by each of these methods is shown in the following table:

Method	Buffer (words)	Request message (words)
`read_attr()`	1	1
`write_attr()`	1	1

More detailed information may be found in the next two sections.

2.3.14.1.3.1. `NdbInterpretedCode::read_attr()`

Description. The read_attr() method is used to read a table column value into a program register. The column may be specified either by using its attribute ID or as a pointer to a Column object (Section 2.3.1, “The Column Class”).

Signature. Referencing the column by its attribute ID:

int read_attr
    (
      Uint32 RegDest,
      Uint32 attrId
    )

Referencing the column as a Column object:

int read_attr
    (
      Uint32 RegDest,
      const NdbDictionary::Column* column
    )

Parameters. This method takes two parameters:

The register to which the column value is to be copied (RegDest).
Either of the following references to the table column whose value is to be copied:
- The table column's attribute ID (attrId)
- A pointer to a column — that is, a pointer to an NdbDictionary::Column object referencing the table column

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

2.3.14.1.3.2. `NdbInterpretedCode::write_attr()`

Description. This method is used to copy a register value to a table column. The column may be specified either by using its attribute ID or as a pointer to a Column object (Section 2.3.1, “The Column Class”).

Signature. Referencing the column by its attribute ID:

int read_attr
    (
      Uint32 attrId,
      Uint32 RegSource
    )

Referencing the column as a Column object:

int read_attr
    (
      const NdbDictionary::Column* column,
      Uint32 RegSource
    )

Parameters. This method takes two parameters:

A reference to the table column to which the register value is to be copied. This can be either of the following:
- The table column's attribute ID (attrId)
- A pointer to a column — that is, a pointer to an NdbDictionary::Column object referencing the table column
The register whose value is to be copied (RegSource).

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

2.3.14.1.4. `NdbInterpretedCode` Register Arithmetic Methods

2.3.14.1.4.1. NdbInterpretedCode::add_reg()
2.3.14.1.4.2. NdbInterpretedCode::sub_reg()

This class provides two methods for performing arithmetic operations on registers. add_reg() allows you to load the sum of two registers into another register; sub_reg() lets you load the difference of two registers into another register.

The space required by each of these methods is shown in the following table:

Method	Buffer (words)	Request message (words)
`add_reg()`	1	1
`sub_reg()`	1	1

More information about these methods is presented in the next two sections.

2.3.14.1.4.1. `NdbInterpretedCode::add_reg()`

Description. This method sums the values stored in any two given registers and stores the result in a third register.

Signature.

int add_reg
    (
      Uint32 RegDest,
      Uint32 RegSource1,
      Uint32 RegSource2
    )

Parameters. This method takes three parameters. The first of these is the register in which the result is to be stored. The second and third parameters are the registers whose values are to be summed.

Note

It is possible to re-use for storing the result one of the registers whose values are summed; that is, RegDest can be the same as RegSource1 or RegSource2.

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

2.3.14.1.4.2. `NdbInterpretedCode::sub_reg()`

Description. This method gets the difference between the values stored in any two given registers and stores the result in a third register.

Signature.

int sub_reg
    (
      Uint32 RegDest,
      Uint32 RegSource1,
      Uint32 RegSource2
    )

Parameters. This method takes three

Sections

Personal tools

Chapter 2. The NDB API