The Mysql Cluster API Developer Guide208
The Mysql Cluster API Developer Guide208
The low-level C++-language NDB API for the MySQL NDBCLUSTER storage engine
the C-language MGM API for communicating with and controlling MySQL Cluster management servers
The MySQL Cluster Connector for Java, which is a a collection of Java APIs introduced in MySQL Cluster NDB 7.1
for writing applications against MySQL Cluster, including JDBC, JPA, and ClusterJ.
This Guide includes concepts, terminology, class and function references, practical examples, common problems, and tips
for using these APIs in applications. It also contains information about NDB internals that may be of interest to developers
working with NDBCLUSTER, such as communication protocols employed between nodes, filesystems used by data nodes,
and error messages.
The information presented in this guide is current for recent MySQL Cluster NDB 6.2, NDB 6.3, NDB 7.0, and NDB 7.1
releases. You should be aware that there have been significant changes in the NDB API, MGM API, and other particulars
in MySQL Cluster versions since MySQL 5.1.12.
Copyright 2003, 2010, Oracle and/or its affiliates. All rights reserved.
This documentation is NOT distributed under a GPL license. Use of this documentation is subject to the following terms: You may create a printed copy
of this documentation solely for your own personal use. Conversion to other formats is allowed as long as the actual content is not altered or edited in
any way. You shall not publish or distribute this documentation in any form or on any media, except if you distribute the documentation in a manner similar to how Sun disseminates it (that is, electronically for download on a Web site with the software) or on a CD-ROM or similar medium, provided
however that the documentation is disseminated together with the software on the same medium. Any other use, such as any dissemination of printed
copies or use of this documentation, in whole or in part, in another publication, requires the prior written consent from an authorized representative of
Sun Microsystems, Inc. Sun Microsystems, Inc. and MySQL AB reserve any and all rights to this documentation not expressly granted above.
For more information on the terms of this license, for details on how the MySQL documentation is built and produced, or if you are interested in doing a
translation, please contact the http://www.mysql.com/company/contact/.
If you want help with using MySQL, please visit either the MySQL Forums or MySQL Mailing Lists where you can discuss your issues with other
MySQL users.
For additional documentation on MySQL products, including translations of the documentation into other languages, and downloadable versions in variety of formats, including HTML, CHM, and PDF formats, see MySQL Documentation Library.
Table of Contents
1. Overview and Concepts ........................................................................................................................ 1
1.1. Introduction ............................................................................................................................ 1
1.1.1. The NDB API ............................................................................................................... 1
1.1.2. The MGM API .............................................................................................................. 1
1.2. Terminology ........................................................................................................................... 1
1.3. The NDBCLUSTER Transaction and Scanning API .............................................................................. 3
1.3.1. Core NDB API Classes .................................................................................................... 3
1.3.2. Application Program Basics .............................................................................................. 4
1.3.3. Review of MySQL Cluster Concepts ................................................................................... 10
1.3.4. The Adaptive Send Algorithm ........................................................................................... 11
2. The NDB API .................................................................................................................................. 13
2.1. Getting Started with the NDB API ................................................................................................ 13
2.1.1. Compiling and Linking NDB API Programs .......................................................................... 13
2.1.2. Connecting to the Cluster ................................................................................................. 15
2.1.3. Mapping MySQL Database Object Names and Types to NDB ...................................................... 16
2.2. The NDB API Object Hierarachy ................................................................................................. 17
2.3. NDB API Classes, Interfaces, and Structures .................................................................................... 19
2.3.1. The Column Class ........................................................................................................ 19
2.3.2. The Datafile Class .................................................................................................... 34
2.3.3. The Dictionary Class ................................................................................................. 40
2.3.4. The Event Class .......................................................................................................... 52
2.3.5. The Index Class .......................................................................................................... 61
2.3.6. The LogfileGroup Class ............................................................................................. 68
2.3.7. The List Class ........................................................................................................... 72
2.3.8. The Ndb Class ............................................................................................................. 73
2.3.9. The NdbBlob Class ...................................................................................................... 82
2.3.10. The NdbDictionary Class .......................................................................................... 91
2.3.11. The NdbEventOperation Class .................................................................................. 93
2.3.12. The NdbIndexOperation Class ................................................................................ 101
2.3.13. The NdbIndexScanOperation Class ......................................................................... 103
2.3.14. The NdbInterpretedCode Class ............................................................................... 108
2.3.15. The NdbOperation Class ......................................................................................... 130
2.3.16. The NdbRecAttr Class ............................................................................................. 143
2.3.17. The NdbScanFilter Class ........................................................................................ 150
2.3.18. The NdbScanOperation Class .................................................................................. 158
2.3.19. The NdbTransaction Class ...................................................................................... 165
2.3.20. The Object Class .................................................................................................... 181
2.3.21. The Table Class ...................................................................................................... 184
2.3.22. The Tablespace Class ............................................................................................. 205
2.3.23. The Undofile Class ................................................................................................. 209
2.3.24. The Ndb_cluster_connection Class ....................................................................... 215
2.3.25. The NdbRecord Interface ........................................................................................... 220
2.3.26. The AutoGrowSpecification Structure ..................................................................... 221
2.3.27. The Element Structure .............................................................................................. 222
2.3.28. The GetValueSpec Structure ..................................................................................... 222
2.3.29. The IndexBound Structure ......................................................................................... 223
2.3.30. The Key_part_ptr Structure ..................................................................................... 224
2.3.31. The NdbError Structure ............................................................................................ 224
2.3.32. The OperationOptions Structure .............................................................................. 227
2.3.33. The PartitionSpec Structure ................................................................................... 229
2.3.34. The RecordSpecification Structure ........................................................................ 231
2.3.35. The ScanOptions Structure ....................................................................................... 232
2.3.36. The SetValueSpec Structure ..................................................................................... 234
2.4. Practical Examples ................................................................................................................ 235
2.4.1. Using Synchronous Transactions ...................................................................................... 235
2.4.2. Using Synchronous Transactions and Multiple Clusters ........................................................... 238
2.4.3. Handling Errors and Retrying Transactions ......................................................................... 242
2.4.4. Basic Scanning Example ............................................................................................... 245
2.4.5. Using Secondary Indexes in Scans .................................................................................... 255
iv
1.1. Introduction
This section introduces the NDB Transaction and Scanning APIs as well as the NDB Management (MGM) API for use in building applications to run on MySQL Cluster. It also discusses the general theory and principles involved in developing such applications.
1.2. Terminology
Provides a glossary of terms which are unique to the NDB and MGM APIs, or have a specialized meaning when applied therein.
The terms in the following list are useful to an understanding of MySQL Cluster, the NDB API, or have a specialized meaning when
used in one of these contexts. See also MySQL Cluster Overview, in the MySQL Manual.
Backup: A complete copy of all cluster data, transactions and logs, saved to disk.
Checkpoint: Generally speaking, when data is saved to disk, it is said that a checkpoint has been reached. When working with the
NDB storage engine, there are two sorts of checkpoints which work together in order to ensure that a consistent view of the cluster's
data is maintained:
Local Checkpoint (LCP): This is a checkpoint that is specific to a single node; however, LCPs take place for all nodes in the
cluster more or less concurrently. An LCP involves saving all of a node's data to disk, and so usually occurs every few minutes,
depending upon the amount of data stored by the node.
More detailed information about LCPs and their behavior can be found in the MySQL Manual, in the sections Defining MySQL
Cluster Data Nodes, and Configuring MySQL Cluster Parameters for Local Checkpoints.
Global Checkpoint (GCP): A GCP occurs every few seconds, when transactions for all nodes are synchronized and the REDO
log is flushed to disk.
A related term is GCI, which stands for Global Checkpoint ID. This marks the point in the REDO log where a GCP took
place.
Management (MGM) node: This is an instance of ndb_mgmd, the cluster management server daemon.
Data node (sometimes also referred to as a storage nodes, although this usage is now discouraged): This is an instance of ndbd, and stores cluster data.
API node: This is an application that accesses cluster data. SQL node refers to a mysqld process that is connected to the cluster
as an API node.
For more information about these node types, please refer to Section 1.3.3, Review of MySQL Cluster Concepts, or to MySQL
Cluster Programs, in the MySQL Manual.
Node Failure: MySQL Cluster is not solely dependent upon the functioning of any single node making up the cluster, which can
continue to run even when one node fails.
Node Restart: The process of restarting a cluster node which has stopped on its own or been stopped deliberately. This can be done
for several different reasons, including the following:
Restarting a node which has shut down on its own (when this has occurred, it is known as forced shutdown or node failure; the
other cases dicussed here involve manually shutting down the node and restarting it)
Initial Node Restart: The process of starting a cluster node with its file system removed. This is sometimes used in the course of
software upgrades and in other special circumstances.
System Crash (or System Failure): This can occur when so many cluster nodes have failed that the cluster's state can no longer be
guaranteed.
System Restart: The process of restarting the cluster and reinitialising its state from disk logs and checkpoints. This is required
after either a planned or an unplanned shutdown of the cluster.
Fragment: Contains a portion of a database table; in other words, in the NDB storage engine, a table is broken up into and stored as
a number of subsets, usually referred to as fragments. A fragment is sometimes also called a partition.
Replica: Under the NDB storage engine, each table fragment has number of replicas in order to provide redundancy.
Transporter: A protocol providing data transfer across a network. The NDB API supports 4 different types of transporter connections: TCP/IP (local), TCP/IP (remote), SCI, and SHM. TCP/IP is, of course, the familiar network protocol that underlies HTTP,
FTP, and so forth, on the Internet. SCI (Scalable Coherent Interface) is a high-speed protocol used in building multiprocessor systems and parallel-processing applications. SHM stands for Unix-style shared memory segments. For an informal introduction to
SCI, see this essay at dolphinics.com.
NDB: This originally stood for Network Database. It now refers to the storage engine used by MySQL AB to enable its MySQL
Cluster distributed database.
ACC: Access Manager. Handles hash indexes of primary keys providing speedy access to the records.
TUP: Tuple Manager. This handles storage of tuples (records) and contains the filtering engine used to filter out records and attributes when performing reads and/or updates.
TC: Transaction Coordinator. Handles co-ordination of transactions and timeouts; serves as the interface to the NDB API for indexes and scan operations.
In addition, the NDB API defines an NdbError structure, which contains the specification for an error.
It is also possible to receive events triggered when data in the database is changed. This is accomplished through the NdbEventOperation class.
Important
The NDB event notification API is not supported prior to MySQL 5.1. (Bug#19719)
For more information about these classes as well as some additional auxiliary classes not listed here, see Section 2.3, NDB API
Classes, Interfaces, and Structures.
3
2.
Initiate a database connection by constructing and initialising one or more Ndb objects.
3.
Identify the tables, columns, and indexes on which you wish to operate, using NdbDictionary and one or more of its subclasses.
4.
5.
6.
2.
Add and define operations associated with the transaction using instances of one or more of the NdbOperation, NdbScanOperation, NdbIndexOperation, and NdbIndexScanOperation classes.
3.
4.
If the operation is of type NoCommit, then the application program requests that the operation portion of a transaction be executed, but without actually committing the transaction. Following the execution of a NoCommit operation, the program can
continue to define additional transaction operations for later execution.
NoCommit operations can also be rolled back by the application.
If the operation is of type Commit, then the transaction is immediately committed. The transaction must be closed after it has
been committed (even if the commit fails), and no further operations can be added to or defined for this transaction.
See Section 2.3.19.1.3, The NdbTransaction::ExecType Type.
Begin (create) the transaction, which is referenced by an NdbTransaction object typically created using
Ndb::startTransaction(). At this point, the transaction is merely being defined; it is not yet sent to the NDB kernel.
2.
Define operations and add them to the transaction, using one or more of the following:
NdbTransaction::getNdbOperation()
NdbTransaction::getNdbScanOperation()
NdbTransaction::getNdbIndexOperation()
NdbTransaction::getNdbIndexScanOperation()
along with the appropriate methods of the respectiveNdbOperation class (or possibly one or more of its subclasses). Note that,
at this point, the transaction has still not yet been sent to the NDB kernel.
3.
4.
For an example of this process, see Section 2.4.1, Using Synchronous Transactions.
To execute several synchronous transactions in parallel, you can either use multiple Ndb objects in several threads, or start multiple application programs.
1.3.2.3. Operations
An NdbTransaction consists of a list of operations, each of which is represented by an instance of NdbOperation, NdbScanOperation, NdbIndexOperation, or NdbIndexScanOperation (that is, of NdbOperation or one of its child classes).
Some general information about cluster access operation types can be found in MySQL Cluster Interconnects and Performance, in the
MySQL Manual.
2.
3.
Here are two brief examples illustrating this process. For the sake of brevity, we omit error handling.
This first example uses an NdbOperation:
// 1. Retrieve table object
myTable= myDict->getTable("MYTABLENAME");
// 2. Create an NdbOperation on this table
myOperation= myTransaction->getNdbOperation(myTable);
// 3. Define the operation's type and lock mode
myOperation->readTuple(NdbOperation::LM_Read);
// 4. Specify search conditions
myOperation->equal("ATTR1", i);
// 5. Perform attribute retrieval
myRecAttr= myOperation->getValue("ATTR2", NULL);
For additional examples of this sort, see Section 2.4.1, Using Synchronous Transactions.
The second example uses an NdbIndexOperation:
// 1. Retrieve index object
myIndex= myDict->getIndex("MYINDEX", "MYTABLENAME");
// 2. Create
myOperation= myTransaction->getNdbIndexOperation(myIndex);
// 3. Define type of operation and lock mode
myOperation->readTuple(NdbOperation::LM_Read);
// 4. Specify Search Conditions
myOperation->equal("ATTR1", i);
// 5. Attribute Actions
myRecAttr = myOperation->getValue("ATTR2", NULL);
Another example of this second type can be found in Section 2.4.5, Using Secondary Indexes in Scans.
We now discuss in somewhat greater detail each step involved in the creation and use of synchronous transactions.
1.
Define single row operation type. The following operation types are supported:
All of these operations operate on the unique tuple key. When NdbIndexOperation is used, then each of these operations operates on a defined unique hash index.
Note
If you want to define multiple operations within the same transaction, then you need to call NdbTransaction::getNdbOperation() or NdbTransaction::getNdbIndexOperation() for each operation.
2.
Specify Search Conditions. The search condition is used to select tuples. Search conditions are set using NdbOperation::equal().
3.
Specify Attribute Actions. Next, it is necessary to determine which attributes should be read or updated. It is important to remember that:
Deletes can neither read nor set values, but only delete them.
Updates can only set values. Normally the attribute is identified by name, but it is also possible to use the attribute's identity to
determine the attribute.
NdbOperation::getValue() returns an NdbRecAttr object containing the value as read. To obtain the actual value, one
of two methods can be used; the application can either
receive the attribute value in an NdbRecAttr object allocated by the NDB API.
The NdbRecAttr object is released when Ndb::closeTransaction() is called. For this reason, the application cannot reference this object following any subsequent call to Ndb::closeTransaction(). Attempting to read data from an NdbRecAttr object before calling NdbTransaction::execute() yields an undefined result.
They can perform read operations which may be shared, exclusive, or dirty.
After the operation is created using NdbTransaction::getNdbScanOperation() or NdbTransaction::getNdbIndexScanOperation(), it is carried out as follows:
1.
Note
See Section 2.3.18.2.1, NdbScanOperation::readTuples(), for additional information about deadlocks which
may occur when performing simultaneous, identical scans with exclusive locks.
2.
3.
4.
5.
Here are two brief examples illustrating this process. Once again, in order to keep things relatively short and simple, we forego any error handling.
This first example performs a table scan using an NdbScanOperation:
// 1. Retrieve a table object
myTable= myDict->getTable("MYTABLENAME");
// 2. Create a scan operation (NdbScanOperation) on this table
myOperation= myTransaction->getNdbScanOperation(myTable);
// 3. Define the operation's type and lock mode
myOperation->readTuples(NdbOperation::LM_Read);
// 4. Specify search conditions
NdbScanFilter sf(myOperation);
sf.begin(NdbScanFilter::OR);
sf.eq(0, i);
// Return rows with column 0 equal to i or
sf.eq(1, i+1); // column 1 equal to (i+1)
sf.end();
// 5. Retrieve attributes
myRecAttr= myOperation->getValue("ATTR2", NULL);
Define Scan Operation Type. It is important to remember that only a single operation is supported for each scan operation
(NdbScanOperation::readTuples() or NdbIndexScanOperation::readTuples()).
Note
If you want to define multiple scan operations within the same transaction, then you need to call NdbTransaction::getNdbScanOperation() or NdbTransaction::getNdbIndexScanOperation() separately for
each operation.
2.
Specify Search Conditions. The search condition is used to select tuples. If no search condition is specified, the scan will return
all rows in the table. The search condition can be an NdbScanFilter (which can be used on both NdbScanOperation and
NdbIndexScanOperation) or bounds (which can be used only on index scans - see NdbIndexScanOperation::setBound()). An index scan can use both NdbScanFilter and bounds.
Note
When NdbScanFilter is used, each row is examined, whether or not it is actually returned. However, when using bounds,
only rows within the bounds will be examined.
3.
Specify Attribute Actions. Next, it is necessary to define which attributes should be read. As with transaction attributes, scan attributes are defined by name, but it is also possible to use the attributes' identities to define attributes as well. As discussed elsewhere in this document (see Section 1.3.2.2, Synchronous Transactions), the value read is returned by the NdbOperation::getValue() method as an NdbRecAttr object.
2.
(When iterating through the result set:) For each row, optionally calling either NdbScanOperation::updateCurrentTuple() or NdbScanOperation::deleteCurrentTuple().
3.
(If performing NdbScanOperation::updateCurrentTuple():) Setting new values for records simply by using NdbOperation::setValue(). NdbOperation::equal() should not be called in such cases, as the primary key is retrieved
from the scan.
Important
The update or delete is not actually performed until the next call to NdbTransaction::execute() is made, just as
with single row operations. NdbTransaction::execute() also must be called before any locks are released; for
more information, see Section 1.3.2.3.4, Lock Handling with Scans.
Features Specific to Index Scans. When performing an index scan, it is possible to scan only a subset of a table using NdbIndexScanOperation::setBound(). In addition, result sets can be sorted in either ascending or descending order, using NdbIndexScanOperation::readTuples(). Note that rows are returned unordered by default unless sorted is set to true. It is also important to note that, when using NdbIndexScanOperation::BoundEQ() on a partition key, only fragments containing rows will
actually be scanned. Finally, when performing a sorted scan, any value passed as the NdbIndexScanOperation::readTuples() method's parallel argument will be ignored and maximum parallelism will be used instead. In other
words, all fragments which it is possible to scan are scanned simultaneously and in parallel in such cases.
For a more complete example of a scan, see Section 2.4.4, Basic Scanning Example.
NdbTransaction::getNdbErrorOperation() returns a reference to the operation causing the most recent error.
NdbTransaction::getNdbErrorLine() yields the method number of the erroneous method in the operation, starting with
1.
This short example illustrates how to detect an error and to use these two methods to identify it:
theTransaction = theNdb->startTransaction();
theOperation = theTransaction->getNdbOperation("TEST_TABLE");
if(theOperation == NULL)
goto error;
theOperation->readTuple(NdbOperation::LM_Read);
theOperation->setValue("ATTR_1", at1);
theOperation->setValue("ATTR_2", at1); // Error occurs here
theOperation->setValue("ATTR_3", at1);
theOperation->setValue("ATTR_4", at1);
if(theTransaction->execute(Commit) == -1)
{
errorLine = theTransaction->getNdbErrorLine();
errorOperation = theTransaction->getNdbErrorOperation();
}
Here, errorLine is 3, as the error occurred in the third method called on the NdbOperation object (in this case,
theOperation). If the result of NdbTransaction::getNdbErrorLine() is 0, then the error occurred when the operations
were executed. In this example, errorOperation is a pointer to the object theOperation. The NdbTransaction::getNdbError() method returns an NdbError object providing information about the error.
Note
Transactions are not automatically closed when an error occurs. You must call Ndb::closeTransaction() or NdbTransaction::close() to close the transaction.
See Section 2.3.8.1.9, Ndb::closeTransaction(), and Section 2.3.19.2.7, NdbTransaction::close().
One recommended way to handle a transaction failure (that is, when an error is reported) is as shown here:
1.
Roll back the transaction by calling NdbTransaction::execute() with a special ExecType value for the type parameter.
See Section 2.3.19.2.5, NdbTransaction::execute() and Section 2.3.19.1.3, The NdbTransaction::ExecType
Type, for more information about how this is done.
2.
3.
Several errors can occur when a transaction contains multiple operations which are simultaneously executed. In this case the application
must go through all operations and query each of their NdbError objects to find out what really happened.
Important
Errors can occur even when a commit is reported as successful. In order to handle such situations, the NDB API provides
an additional NdbTransaction::commitStatus() method to check the transaction's commit status.
9
When an application executes a transaction, it connects to one transaction coordinator on one data node. Usually, the programmer does
not need to specify which TC should be used, but in some cases where performance is important, the programmer can provide hints to
use a certain TC. (If the node with the desired transaction coordinator is down, then another TC will automatically take its place.)
Each data node has an ACC and a TUP which store the indexes and data portions of the database table fragment. Even though a single
TC is responsible for the transaction, several ACCs and TUPs on other data nodes might be involved in that transaction's execution.
SCI
2.
SHM
3.
TCP/IP (localhost)
4.
If there are several connections available with the same proximity, one is selected for each transaction in a round-robin fashion. Optionally, you may set the method for TC selection to round-robin mode, where each new set of transactions is placed on the next data node.
The pool of connections from which this selection is made consists of all available connections.
As noted in Section 1.3.3, Review of MySQL Cluster Concepts, the application programmer can provide hints to the NDB API as to
which transaction coordinator should be uses. This is done by providing a table and a partition key (usually the primary key). If the
primary key as the partition key, then the transaction is placed on the node where the primary replica of that record resides. Note that
this is only a hint; the system can be reconfigured at any time, in which case the NDB API chooses a transaction coordinator without using the hint. For more information, see Section 2.3.1.2.16, Column::getPartitionKey(), and Section 2.3.8.1.8,
Ndb::startTransaction(). The application programmer can specify the partition key from SQL by using this construct:
CREATE TABLE ... ENGINE=NDB PARTITION BY KEY (attribute_list);
For additional information, see Partitioning, and in particular KEY Partitioning, in the MySQL Manual.
data are (in most NDB Cluster configurations) synchronously replicated and stored on multiple data nodes, the system can handle processor failures without loss of data. However, in the case of a system-wide failure, all transactions (committed or not) occurring since
the most recent GCP are lost.
Concurrency Control. NDBCLUSTER uses pessimistic concurrency control based on locking. If a requested lock (implicit and depending on database operation) cannot be attained within a specified time, then a timeout error results.
Concurrent transactions as requested by parallel application programs and thread-based applications can sometimes deadlock when they
try to access the same information simultaneously. Thus, applications need to be written in a manner such that timeout errors occurring
due to such deadlocks are handled gracefully. This generally means that the transaction encountering a timeout should be rolled back
and restarted.
Hints and Performance. Placing the transaction coordinator in close proximity to the actual data used in the transaction can in many
cases improve performance significantly. This is particularly true for systems using TCP/IP. For example, a Solaris system using a
single 500 MHz processor has a cost model for TCP/IP communication which can be represented by the formula
[30 microseconds] + ([100 nanoseconds] * [number of bytes])
This means that if we can ensure that we use popular links we increase buffering and thus drastically reduce the costs of communication. The same system using SCI has a different cost model:
[5 microseconds] + ([10 nanoseconds] * [number of bytes])
This means that the efficiency of an SCI system is much less dependent on selection of transaction coordinators. Typically, TCP/IP systems spend 30 to 60% of their working time on communication, whereas for SCI systems this figure is in the range of 5 to 10%. Thus,
employing SCI for data transport means that less effort from the NDB API programmer is required and greater scalability can be
achieved, even for applications using data from many different parts of the database.
A simple example would be an application that uses many simple updates where a transaction needs to update one record. This record
has a 32-bit primary key which also serves as the partitioning key. Then the keyData is used as the address of the integer of the
primary key and keyLen is 4.
The NDB Transporter (TCP/IP, SCI, or shared memory) decides that a buffer is full and sends it off. The buffer size is implementation-dependent and may change between MySQL Cluster releases. When TCP/IP is the transporter, the buffer size is usually
around 64 KB. Since each Ndb object provides a single buffer per data node, the notion of a full buffer is local to each data
node.
2.
The accumulation of statistical data on transferred information may force sending of buffers to all storage nodes (that is, when all
the buffers become full).
3.
Every 10 ms, a special transmission thread checks whether or not any send activity has occurred. If not, then the thread will force
transmission to all nodes. This means that 20 ms is the maximum amount of time that database operations are kept waiting before
being dispatched. A 10-millisecond limit is likely in future releases of MySQL Cluster; checks more frequent than this require additional support from the operating system.
4.
For methods that are affected by the adaptive send algorithm (such as NdbTransaction::execute()), there is a force
parameter that overrides its default behavior in this regard and forces immediate transmission to all nodes. See the individual NDB
API class listings for more information.
11
Note
The conditions listed above are subject to change in future releases of MySQL Cluster.
12
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.
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
CFLAGS="$CFLAGS
CFLAGS="$CFLAGS
CFLAGS="$CFLAGS
"`mysql_config
"`mysql_config
"`mysql_config
"`mysql_config
--cflags`
--include`/storage/ndb
--include`/storage/ndb/ndbapi
--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
13
from MySQL, then you can omit the line referencing the ndbapi directory.
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"
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])
14
bin_PROGRAMS = example
example_SOURCES = example.cc
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.
15
<stdio.h>
<stdlib.h>
<NdbApi.hpp>
<mysql.h>
<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;
}
16
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:
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
behavior 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
17
Ndb
Key_part_ptr
PartitionSpec
NdbBlob
Ndb_cluster_connection
NdbDictionary
AutoGrowSpecification
Dictionary
List
Element
Column
Object
Datafile
Event
Index
LogfileGroup
Table
Tablespace
Undofile
RecordSpecification
NdbError
NdbEventOperation
NdbInterpretedCode
NdbOperation
NdbIndexOperation
NdbScanOperation
NdbIndexScanOperation
IndexBound
ScanOptions
GetValueSpec
SetValueSpec
OperationOptions
NdbRecAttr
NdbRecord
18
NdbScanFilter
NdbTransaction
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.
Built-in type
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()
getNullable()
getPrimaryKey()
getColumnNo()
equal()
getType()
Method
Purpose / Use
getLength()
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()
getPartitionKey()
getArrayType()
getStorageType()
getPrecision()
getScale()
Column()
~Column()
Class destructor
setName()
setNullable()
setPrimaryKey()
setType()
setLength()
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()
setArrayType()
setStorageType()
setPrecision()
setScale()
setDefaultValue()
getDefaultValue()
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
StorageType
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.
20
Class diagram. This diagram shows all the available methods and enumerated types of the Column class:
21
Description
ArrayTypeFixed
ArrayTypeShortVar
ArrayTypeMediumVar
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.
Description
StorageTypeMemory
StorageTypeDisk
2.3.1.1.3. Column::Type
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
Tinyunsigned
Smallint
Smallunsigned
Mediumint
Mediumunsigned
Int
Unsigned
Bigint
Bigunsigned
Value
Description
Float
4-byte float
Double
8-byte float
Olddecimal
Olddecimalunsigned
Decimal
Decimalunsigned
Char
Varchar
Binary
Varbinary
Datetime
Date
Blob
Text
A text blob
Bit
Longvarchar
A 2-byte Varchar
Longvarbinary
A 2-byte Varbinary
Time
Year
Timestamp
Unix time
Caution
Do not confuse Column::Type with Object::Type or Table::Type.
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.
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.
23
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.
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.
24
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
2.3.1.2.7. Column::getType()
Description. This method gets the column's datatype.
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.
Type getType
25
(
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
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.
int getLength
(
void
) const
26
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
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.
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
27
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
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.
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
(
28
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.
29
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.
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.
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.
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.
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.
30
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.
31
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.
32
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
(
33
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.1.2.33. Column::setDefaultValue()
Description. This method sets a column value to its default, if it has one; otherwise it sets the column to NULL.
This method was added in MySQL Cluster NDB 7.1.0.
To determine whether a table has any columns with default values, use Table::hasDefaultValues().
Signature.
int setDefaultValue
(
const void* buf,
unsigned int len
)
Parameters. This method takes 2 arguments: a value pointer buf; and the length len of the data, as the number of significant bytes.
For fixed size types, this is the type size. For variable length types, the leading 1 or 2 bytes pointed to by buffer also contain size information as normal for the type.
Return value. 0 on success, 1 on failure..
2.3.1.2.34. Column::getDefaultValue()
Description. Gets a column's default value data.
This method was added in MySQL Cluster NDB 7.1.0.
To determine whether a table has any columns with default values, use Table::hasDefaultValues().
Signature.
const void* getDefaultValue
(
unsigned int* len = 0
) const
Parameters. len holds either the length of the default value data, or 0 in the event that the column is nullable or has no default value.
Return value. The default value 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.
34
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()
getSize()
getFree()
getNode()
getTablespace()
getTablespaceId()
getFileNo()
getObjectStatus()
getObjectVersion()
getObjectId()
setPath()
Sets the name and location of the datafile on the file system
setSize()
setTablespace()
setNode()
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:
35
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()
36
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.
37
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.
38
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
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
)
39
Parameters. This method takes a single parameter, which can be either one of the following:
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.
Purpose / Use
Dictionary()
~Dictionary()
Destructor method
getTable()
getIndex()
getEvent()
getTablespace()
getLogfileGroup()
getDatafile()
getUndofile()
getNdbError()
createTable()
Creates a table
createIndex()
Creates an index
createEvent()
Creates an event
createTablespace()
Creates a tablespace
createLogfileGroup()
createDatafile()
Creates a datafile
40
Method
Purpose / Use
createUndofile()
Creates an undofile
dropTable()
Drops a table
dropIndex()
dropEvent()
Drops an index
dropTablespace()
Drops a tablespace
dropLogfileGroup()
dropDatafile()
Drops a datafile
dropUndofile()
Drops an undofile
listObjects()
listIndexes()
listEvents()
Fetches a list of the events defined in the dictionary
removeCachedTable()
removeCachedIndex()
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:
41
42
Note
Both the constructor and destructor for this class are protected methods, rather than public.
Signature.
protected Dictionary
(
Ndb& ndb
)
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
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
43
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
)
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
)
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
)
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
(
44
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
)
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.31, 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.
45
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
)
2.3.3.1.12. Dictionary::createEvent()
Description. Creates an event, given a reference to an Event object.
Signature.
int createEvent
(
const Event& event
)
2.3.3.1.13. Dictionary::createTablespace()
Description. This method creates a new tablespace, given a Tablespace object.
Signature.
int createTablespace
(
const Tablespace& tSpace
)
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
)
2.3.3.1.15. Dictionary::createDatafile()
46
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
)
or
NdbRecord* createRecord
(
const Index* index,
const RecordSpecification* recordSpec,
Uint32 length,
Uint32 elementSize
)
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.34, The RecordSpecification Structure.
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()
47
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.
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
)
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.
2.3.3.1.21. Dictionary::dropTablespace()
Description. This method drops a tablespace, given a Tablespace object.
Signature.
int dropTablespace
(
const Tablespace& tSpace
)
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
)
2.3.3.1.23. Dictionary::dropDatafile()
Description. This method drops a datafile, given a Datafile object.
Signature.
int dropDatafile
(
const Datafile& dFile
)
2.3.3.1.24. Dictionary::dropUndofile()
Description. This method drops an undofile, given an Undofile object.
Signature.
int dropUndofile
(
const Undofile& uFile
)
49
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.
Signature.
int listObjects
(
List&
list,
Object::Type type = Object::TypeUndefined
) const
Beginning with MySQL Cluster NDB 6.2.19, MySQL Cluster NDB 6.3.29, and MySQL Cluster NDB 7.0.10 (Bug#48851), this method
has the following additional signature:
int listObjects
(
List&
list,
Object::Type type,
bool
fullyQualified
) const
Note
A non-const version of this method, shown here, was removed in MySQL Cluster NDB 6.2.19, MySQL Cluster NDB
6.3.28, and MySQL Cluster NDB 7.0.9. (Bug#47798)
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.
Beginning with MySQL Cluster NDB 6.2.19, MySQL Cluster NDB 6.3.29, and MySQL Cluster NDB 7.0.10, you can also specify
whether or not the object names in the list are fully qualified (that is, whether the object name includes the database, schema, and
possibly the table name). If you specify fullyQualified, then you must also specify the type.
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.
50
int listIndexes
(
List&
list,
const char* table
) const
Warning
The non-const version of this method, shown here, was removed in MySQL Cluster NDB 6.2.19, MySQL Cluster NDB
6.3.28, and MySQL Cluster NDB 7.0.9. (Bug#47798)
int listIndexes
(
List&
list,
const char* table
)
A reference to the List that contains the indexes following the call to the method
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
)
Warning
The non-const version of this method, shown here, was removed in MySQL Cluster NDB 6.2.19, MySQL Cluster NDB
6.3.28, and MySQL Cluster NDB 7.0.9. (Bug#47798)
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
)
51
2.3.3.1.30. Dictionary::removeCachedTable()
Description. This method removes the specified table from the local cache.
Signature.
void removeCachedTable
(
const char* table
)
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
)
Purpose / Use
Event()
Class constructor
~Event()
Destructor
getName()
getTable()
getTableName()
getTableEvent()
getDurability()
getReport()
52
Method
Purpose / Use
getNoOfEventColumns()
getEventColumn()
getObjectStatus()
getObjectVersion()
getObjectId()
setName()
setTable()
addTableEvent()
setDurability()
setReport()
addEventColumn()
addEventColumns()
mergeEvents()
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
EventDurability
EventReport
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:
53
54
Description
TE_INSERT
TE_DELETE
TE_UPDATE
TE_DROP
TE_ALTER
TE_CREATE
TE_GCP_COMPLETE
TE_CLUSTER_FAILURE
TE_STOP
TE_NODE_FAILURE
TE_SUBSCRIBE
TE_UNSUBSCRIBE
TE_ALL
Occurs when any event occurs on a table (not relevant when a specific event is received)
Description
ED_UNDEFINED
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
Important
The value ED_PERMANENT is reserved for future use and is not yet supported in any MySQL Cluster release.
55
Description
ER_UPDATED
ER_ALL
Reporting of all events, except for those not resulting in any updates to the inline parts
of BLOB columns
ER_SUBSCRIBE
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.
56
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
57
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.
58
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 behavior.
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
)
59
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
)
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
)
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 get60
NoOfEventColumns().
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
)
The names of the columns columnNames this must be passed as a pointer to a character pointer.
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
)
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()
getTable()
getNoOfColumns()
getColumn()
getType()
getLogging()
getObjectStatus()
getObjectVersion()
getObjectId()
setName()
setTable()
addColumn()
addColumnName()
addColumnNames()
setType()
setLogging()
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:
62
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
UniqueHashIndex
OrderedIndex
63
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().
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.
64
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:
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.
66
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
)
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
)
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
)
67
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.
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
68
Method
Purpose / Use
getName()
getUndoBufferSize()
getAutoGrowSpecification()
getUndoFreeWords()
getObjectStatus()
getObjectVersion()
getObjectId()
setName()
setUndoBufferSize()
setAutoGrowSpecification()
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:
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
69
(
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
70
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()
71
Description. This method is used to set a name for the logfile group.
Signature.
void setName
(
const char* name
)
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.
72
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.
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()
~Ndb()
init()
getDictionary()
Gets a dictionary, which is used for working with database schema information.
getDatabaseName()
setDatabaseName()
getDatabaseSchemaName()
setDatabaseSchemaName()
startTransaction()
closeTransaction()
Closes a transaction.
computeHash()
createEventOperation()
Creates a subscription to a database event. (See Section 2.3.11, The NdbEventOperation Class.)
dropEventOperation()
pollEvents()
getNdbError()
getNdbErrorDetail()
Retrieves extra error details. Added in MySQL Cluster NDB 6.2.19, MySQL Cluster
NDB 6.3.29, and MySQL Cluster NDB 7.0.10.
73
Method
Purpose / Use
getReference()
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:
Parameters. The Ndb class constructor can take up to 3 parameters, of which only the first is required:
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.
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:
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
75
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
(
76
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
)
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.
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*
const struct Key_part_ptr*
void*
Uint32
)
table,
keyData,
xfrmbuf = 0,
xfrmbuflen = 0
Parameters. When specifying the transaction coordinator, this method takes four parameters:
A pointer to a table (NdbDictionary::Table object) used for deciding which node should act as the transaction coordinator.
A null-terminated array of pointers to the values of the distribution key columns. The length of the key part is read from metadata
and checked against the passed value.
A Key_part_ptr is defined as shown in Section 2.3.30, The Key_part_ptr Structure.
77
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 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.
78
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*
const NdbDictionary::Table*
const struct Key_part_ptr*
void*
Uint32
)
hashvalueptr,
table,
keyData,
xfrmbuf = 0,
xfrmbuflen = 0
If the method call id successful, hashvalueptr is set to the computed hash value.
keyData is a null-terminated array of pointers to the key parts that are part of the table's distribution key. The length of each key
part is read from metadata and checked against the passed value (see Section 2.3.30, The Key_part_ptr Structure).
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()
79
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
)
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:
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()
80
Description. This method provides you with two different ways to obtain an NdbError object representing an error condition. For
more detailed information about error handling in the NDB API, see Chapter 5, MySQL Cluster API Errors.
Signature. The getNdbError() method actually has two variants. The first of these simply gets the most recent error to have occurred:
const NdbError& getNdbError
(
void
)
The second variant returns the error corresponding to a given error code:
const NdbError& getNdbError
(
int errorCode
)
Regardless of which version of the method is used, the NdbError object returned persists until the next NDB API method is invoked.
Parameters. To obtain the most recent error, simply call getNdbError() without any parameters. To obtain the error matching a
specific errorCode, invoke the method passing the code (an int) to it as a parameter. For a listing of NDB API error codes and corresponding error messages, see Section 5.2, NDB API Errors and Error Handling.
Return value. An NdbError object containing information about the error, including its type and, where applicable, contextual information as to how the error arose. See Section 2.3.31, The NdbError Structure, for details.
2.3.8.1.16. Ndb::getNdbErrorDetail()
Description. This method, introduced in MySQL Cluster NDB 6.2.19, MySQL Cluster NDB 6.3.29, and MySQL Cluster NDB 7.0.10,
provides an easier and safer way to access any extra information about an error. Formerly, it was necessary to read these extra details
from the NdbError object's details property, which is now deprecated in favor of getNdbErrorDetail() (Bug#48851). This
method allows you to store such details in a user-supplied buffer, returning a pointer to the beginning of this buffer. In the event that the
string containing the details exceeds the length of the buffer, it is truncated to fit.
getErrorDetail() makes it much simpler to determine the source of an error than reading NdbError.details, because this
method provides the information in the form of a string. For example, in the case of a unique constraint violation (error 893), this string
supplies the fully qualified name of the index where the problem originated, in the format database-name/schema-name/tablename/index-name, (NdbError.details, on the other hand, supplies only an index ID, and it is often not readily apparent to
which table this index belongs.) Regardless of the type of error and details concerning this error, the string retrieved by getErrorDetail() is always null-terminated.
Signature. The getNdbErrorDetail() method has the following signature:
const char* getNdbErrorDetail
(
const NdbError& error,
char*
buffer,
Uint32
bufferLength
) const
Parameters. To obtain detailed information about an error, call getNdbErrorDetail() with a reference to the corresponding NdbError object, a buffer, and the length of this buffer (expressed as an unsigned 32-bit integer).
Return value. When extra details about the error are available, this method returns a pointer to the beginning of the buffer supplied. As stated previously, if the string containing the details is longer than bufferLength, the string is truncated to fit. In the event
that no addition details are available, getNdbErrorDetail() returns NULL.
2.3.8.1.17. Ndb::getReference()
Description. This method can be used to obtain a reference to a given Ndb object. This is the same value that is returned for a given
operation corresponding to this object in the output of DUMP 2350. (See Section 6.2.3.9, DUMP 2350, for an example.)
Signature.
Uint32 getReference
(
void
)
81
Parameters. None.
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 preblob 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::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.
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
82
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()
getValue()
setValue()
setActiveHook()
getVersion()
getNull()
setNull()
getLength()
truncate()
getPos()
setPos()
readData()
writeData()
getColumn()
getNdbError()
blobsFirstBlob()
blobsNextBlob()
getBlobEventName()
getBlobTableName()
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:
83
Type
Purpose / Use
ActiveHook
State
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:
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.
Description
Idle
The NdbBlob has not yet been prepared for use with any operations.
Prepared
Active
This is the BLOB handle's state following execution or the fetching of the next result,
but before the transaction is committed.
Closed
Invalid
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
85
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*
Uint32
)
data,
bytes
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 nocommit 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*
void*
)
activeHook,
arg
A pointer to an ActiveHook value; this is a callback as explained in Section 2.3.9.1.1, The NdbBlob::ActiveHook Type.
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.
86
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:
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.
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
(
87
Uint64& length
)
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
)
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
88
(
void*
Uint32&
data,
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*
Uint32
)
data,
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.31, 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.
89
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
)
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,
90
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.
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:
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 Cluster source tree.
92
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.
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:
93
Method
Purpose / Use
getState()
getEventType()
getValue()
getPreValue()
getBlobHandle()
getPreBlobHandle()
getGCI()
getLatestGCI()
getNdbError()
isConsistent()
tableNameChanged()
tableFrmChanged()
tableFragmentationChanged()
tableRangeListChanged()
mergeEvents()
execute()
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:
94
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
EO_ERROR
A State value is returned by the getState() method. See Section 2.3.11.2.1, NdbEventOperation::getState(), for
more information.
95
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
)
96
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
)
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
)
2.3.11.2.6. NdbEventOperation::getPreBlobHandle()
97
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
)
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.31, The NdbError Structure.
98
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.
bool tableNameChanged
(
void
) const
Note
Prior to MySQL Cluster NDB 7.1.0, this method used const bool as its return type. (Bug#44840)
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.
bool tableFrmChanged
(
void
) const
Note
Prior to MySQL Cluster NDB 7.1.0, this method used const bool as its return type. (Bug#44840)
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.
bool tableFragmentationChanged
(
void
) const
99
Note
Prior to MySQL Cluster NDB 7.1.0, this method used const bool as its return type. (Bug#44840)
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.
bool tableRangeListChanged
(
void
) const
Note
Prior to MySQL Cluster NDB 7.1.0, this method used const bool as its return type. (Bug#44840)
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
)
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
)
100
Parameters. None.
Return value. This method returns 0 on success and -1 on failure.
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()
readTuple()
updateTuple()
deleteTuple()
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:
Note
For more information about the use of NdbIndexOperation, see Section 1.3.2.3.1, Single-row operations.
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, NdbTransac101
tion::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.
102
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()
getSorted()
getDescending()
readTuples()
setBound()
reset_bounds()
end_of_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.29, 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:
103
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
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
Lower bound
BoundLT
BoundGE
Upper bound
BoundGT
BoundEQ
Equality
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
104
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
)
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
105
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
)
or
int setBound
(
Uint32
id,
int
type,
const void* value
)
Either the name or the id of the attribute on which the bound is to be set.
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:
106
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.
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.29, 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.33, The PartitionSpec Structure, for more information.
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()
107
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
)
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
108
Method
Purpose / Use
load_const_null()
load_const_u16()
load_const_u32()
load_const_u64()
read_attr()
write_attr()
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()
branch_label()
branch_ge()
branch_gt()
branch_le()
branch_lt()
branch_eq()
branch_ne()
branch_ne_null()
branch_eq_null()
branch_col_eq()
branch_col_ne()
branch_col_lt()
branch_col_le()
branch_col_gt()
branch_col_ge()
branch_col_eq_null()
branch_col_ne_null()
branch_col_like()
branch_col_notlike()
branch_col_and_mask_eq_mask()
branch_col_and_mask_ne_mask()
Jump if a column value ANDed with a bitmask is not equal to the bitmask
branch_col_and_mask_eq_zero()
branch_col_and_mask_ne_zero()
interpret_exit_ok()
interpret_exit_nok()
interpret_last_row()
Return a row as part of the result, and do not check any more rows in this fragment
add_val()
sub_val()
def_sub()
Define a subroutine
call_sub()
Call a subroutine
ret_sub()
finalise()
getTable()
getNdbError()
Gets the most recent error associated with this NdbInterpretedCode object
getWordsUsed()
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:
110
111
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.
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.
Buffer (words)
load_const_null()
load_const_u16()
load_const_u32()
load_const_u64()
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
112
(
Uint32 RegDest,
Uint32 Constant
)
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
)
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
)
2.3.14.1.3. NdbInterpretedCode Methods for Copying Values Between Registers and Table Columns
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:
113
Method
Buffer (words)
read_attr()
write_attr()
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
)
Either of the following references to the table column whose value is to be copied:
A pointer to a column that is, a pointer to an NdbDictionary::Column object referencing the table column
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
)
A reference to the table column to which the register value is to be copied. This can be either of the following:
A pointer to a column that is, a pointer to an NdbDictionary::Column object referencing the table column
Buffer (words)
add_reg()
sub_reg()
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 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 subtracted; that is, the value of register RegDest is set equal to
(value in register RegSource1) (value in register RegSource2)
Note
115
It is possible to re-use one of the registers whose values are subtracted for storing the result; that is, RegDest can be the
same as RegSource1 or RegSource2.
Return value. 0 on success; -1 on failure.
To define a label, use the def_label() method. See Section 2.3.14.1.6, NdbInterpretedCode::def_label().
To perform an unconditional jump to a label, use the branch_label() method. See Section 2.3.14.1.7, NdbInterpretedCode::branch_label().
To perform a jump to a given label based on a comparison of register values, use one of the branch_*() methods (branch_ge(),
branch_gt(), branch_le(), branch_lt(), branch_eq(), branch_ne(), branch_ne_null(), or
branch_eq_null()). See Section 2.3.14.1.8, Register-Based NdbInterpretedCode Branch Operations.
To perform a jump to a given label based on a comparison of table column values, use one of the branch_col_*() methods
(branch_col_ge(), branch_col_gt(), branch_col_le(), branch_col_lt(), branch_col_eq(),
branch_col_ne(), branch_col_ne_null(), or branch_col_eq_null()). See Section 2.3.14.1.9, Column-Based NdbInterpretedCode Branch Operations.
To perform a jump based on pattern-matching of a table column value, use one of the methods branch_col_like() or
branch_col_notlike(). See Section 2.3.14.1.10, Pattern-Based NdbInterpretedCode Branch Operations.
2.3.14.1.6. NdbInterpretedCode::def_label()
Description. This method defines a label to be used as the target of one or more jumps in an interpreted program.
def_label() uses a 2-word buffer and requires no space for request messages.
Signature.
int def_label
(
int LabelNum
)
Parameters. This method takes a single parameter LabelNum, whose value must be unique among all values used for labels within
the interpreted program.
Return value. 0 on success; -1 on failure.
2.3.14.1.7. NdbInterpretedCode::branch_label()
Description. This method performs an unconditional jump to an interpreted program label (see Section 2.3.14.1.6, NdbInterpretedCode::def_label()).
Signature.
int branch_label
(
Uint32 Label
)
Parameters. This method takes a single parameter, an interpreted program Label defined using def_label().
116
The space required by each of these methods is shown in the following table:
Method
Buffer (words)
branch_ge()
branch_gt()
branch_le()
branch_lt()
branch_eq()
branch_ne()
branch_ne_null()
branch_eq_null()
2.3.14.1.8.1. NdbInterpretedCode::branch_ge()
Description. This method compares two register values; if the first is greater than or equal to the second, the interpreted program jumps
to the specified label.
Signature.
int branch_ge
(
Uint32 RegLvalue,
Uint32 RegRvalue,
Uint32 Label
)
Parameters. This method takes three parameters, the registers whose values are to be compared RegLvalue and RegRvalue
and the program Label to jump to if RegLvalue is greater than or equal to RegRvalue. Label must have been defined previously
using def_label() (see Section 2.3.14.1.6, NdbInterpretedCode::def_label()).
Return value. 0 on success, -1 on failure.
2.3.14.1.8.2. NdbInterpretedCode::branch_gt()
Description. This method compares two register values; if the first is greater than the second, the interpreted program jumps to the specified label.
Signature.
int branch_gt
(
Uint32 RegLvalue,
Uint32 RegRvalue,
Uint32 Label
)
Parameters. This method takes three parameters, the registers whose values are to be compared RegLvalue and RegRvalue
and the program Label to jump to if RegLvalue is greater than RegRvalue. Label must have been defined previously using
def_label() (see Section 2.3.14.1.6, NdbInterpretedCode::def_label()).
117
2.3.14.1.8.3. NdbInterpretedCode::branch_le()
Description. This method compares two register values; if the first is less than or equal to the second, the interpreted program jumps to
the specified label.
Signature.
int branch_le
(
Uint32 RegLvalue,
Uint32 RegRvalue,
Uint32 Label
)
Parameters. This method takes three parameters, the registers whose values are to be compared RegLvalue and RegRvalue
and the program Label to jump to if RegLvalue is less than or equal to RegRvalue. Label must have been defined previously using def_label() (see Section 2.3.14.1.6, NdbInterpretedCode::def_label()).
Return value. 0 on success, -1 on failure.
2.3.14.1.8.4. NdbInterpretedCode::branch_lt()
Description. This method compares two register values; if the first is less than the second, the interpreted program jumps to the specified label.
Signature.
int branch_lt
(
Uint32 RegLvalue,
Uint32 RegRvalue,
Uint32 Label
)
Parameters. This method takes three parameters, the registers whose values are to be compared RegLvalue and RegRvalue
and the program Label to jump to if RegLvalue is less than RegRvalue. Label must have been defined previously using
def_label() (see Section 2.3.14.1.6, NdbInterpretedCode::def_label()).
Return value. 0 on success, -1 on failure.
2.3.14.1.8.5. NdbInterpretedCode::branch_eq()
Description. This method compares two register values; if they equal, then the interpreted program jumps to the specified label.
Signature.
int branch_eq
(
Uint32 RegLvalue,
Uint32 RegRvalue,
Uint32 Label
)
Parameters. This method takes three parameters, the registers whose values are to be compared RegLvalue and RegRvalue
and the program Label to jump to if they are equal. Label must have been defined previously using def_label() (see Section 2.3.14.1.6, NdbInterpretedCode::def_label()).
Return value. 0 on success, -1 on failure.
2.3.14.1.8.6. NdbInterpretedCode::branch_ne()
Description. This method compares two register values; if they are not equal, then the interpreted program jumps to the specified label.
Signature.
int branch_ne
(
118
Uint32 RegLvalue,
Uint32 RegRvalue,
Uint32 Label
)
Parameters. This method takes three parameters, the registers whose values are to be compared RegLvalue and RegRvalue
and the program Label to jump they are not equal. Label must have been defined previously using def_label() (see Section 2.3.14.1.6, NdbInterpretedCode::def_label()).
Return value. 0 on success, -1 on failure.
2.3.14.1.8.7. NdbInterpretedCode::branch_ne_null()
Description. This method compares a register value with NULL; if the value is not null, then the interpreted program jumps to the specified label.
Signature.
int branch_ne_null
(
Uint32 RegLvalue,
Uint32 Label
)
Parameters. This method takes two parameters, the register whose value is to be compared with NULL (RegLvalue) and the program Label to jump to if RegLvalue is not null. Label must have been defined previously using def_label() (see Section 2.3.14.1.6, NdbInterpretedCode::def_label()).
Return value. 0 on success, -1 on failure.
2.3.14.1.8.8. NdbInterpretedCode::branch_eq_null()
Description. This method compares a register value with NULL; if the register value is null, then the interpreted program jumps to the
specified label.
Signature.
int branch_eq_null
(
Uint32 RegLvalue,
Uint32 Label
)
Parameters. This method takes two parameters, the register whose value is to be compared with NULL (RegLvalue) and the program Label to jump to if RegLvalue is null. Label must have been defined previously using def_label() (see Section 2.3.14.1.6, NdbInterpretedCode::def_label()).
Return value. 0 on success, -1 on failure.
In each case (once again excepting branch_col_eq_null() and branch_col_ne_null()), the arbitrary constant is the first
parameter passed to the method.
The space requirements for each of these methods is shown in the following table, where L represents the length of the constant value:
119
Method
Buffer (words)
branch_col_eq_null()
branch_col_ne_null()
branch_col_eq()
2 + CEIL(L / 8)
branch_col_ne()
2 + CEIL(L / 8)
branch_col_lt()
2 + CEIL(L / 8)
branch_col_le()
2 + CEIL(L / 8)
branch_col_gt()
2 + CEIL(L / 8)
branch_col_ge()
2 + CEIL(L / 8)
Note
The expression CEIL(L / 8) is the number of whole 8-byte words required to hold the constant value to be compared.
2.3.14.1.9.1. NdbInterpretedCode::branch_col_eq()
Description. This method compares a table column value with an arbitrary constant and jumps to the specified program label if the values are equal.
Signature.
int branch_col_eq
(
const void* val,
Uint32 len,
Uint32 attrId,
Uint32 Label
)
The attribute ID of the table column whose value is to be compared with val
A Label (previously defined using def_label()) to jump to if the compared values are equal
2.3.14.1.9.2. NdbInterpretedCode::branch_col_ne()
Description. This method compares a table column value with an arbitrary constant and jumps to the specified program label if the two
values are not equal.
Signature.
int branch_col_ne
(
const void* val,
Uint32 len,
Uint32 attrId,
Uint32 Label
)
120
The attribute ID of the table column whose value is to be compared with val
A Label (previously defined using def_label()) to jump to if the compared values are unequal
2.3.14.1.9.3. NdbInterpretedCode::branch_col_lt()
Description. This method compares a table column value with an arbitrary constant and jumps to the specified program label if the
constant is less than the column value.
Signature.
int branch_col_lt
(
const void* val,
Uint32 len,
Uint32 attrId,
Uint32 Label
)
The attribute ID of the table column whose value is to be compared with val
A Label (previously defined using def_label()) to jump to if the constant value is less than the column value
2.3.14.1.9.4. NdbInterpretedCode::branch_col_le()
Description. This method compares a table column value with an arbitrary constant and jumps to the specified program label if the
constant is less than or equal to the column value.
Signature.
int branch_col_le
(
const void* val,
Uint32 len,
Uint32 attrId,
Uint32 Label
)
The attribute ID of the table column whose value is to be compared with val
A Label (previously defined using def_label()) to jump to if the constant value is less than or equal to the column value
2.3.14.1.9.5. NdbInterpretedCode::branch_col_gt()
121
Description. This method compares a table column value with an arbitrary constant and jumps to the specified program label if the
constant is greater than the column value.
Signature.
int branch_col_gt
(
const void* val,
Uint32 len,
Uint32 attrId,
Uint32 Label
)
The attribute ID of the table column whose value is to be compared with val
A Label (previously defined using def_label()) to jump to if the constant value is greater than the column value
2.3.14.1.9.6. NdbInterpretedCode::branch_col_ge()
Description. This method compares a table column value with an arbitrary constant and jumps to the specified program label if the
constant is greater than or equal to the column value.
Signature.
int branch_col_ge
(
const void* val,
Uint32 len,
Uint32 attrId,
Uint32 Label
)
The attribute ID of the table column whose value is to be compared with val
A Label (previously defined using def_label()) to jump to if the constant value is greater than or equal to the column value
2.3.14.1.9.7. NdbInterpretedCode::branch_col_eq_null()
Description. This method tests the value of a table column and jumps to the indicated program label if the column value is NULL.
Signature.
int branch_col_eq_null
(
Uint32 attrId,
Uint32 Label
)
Parameters. This method requires two parameters: the attribuite ID for the table column, and the program label to jump to if the
122
2.3.14.1.9.8. NdbInterpretedCode::branch_col_ne_null()
Description. This method tests the value of a table column and jumps to the indicated program label if the column value is not NULL.
Signature.
int branch_col_ne_null
(
Uint32 attrId,
Uint32 Label
)
Parameters. This method requires two parameters: the attribuite ID of the table column, and the program label to jump to if the
column value is not NULL.
Return value. 0 on success, -1 on failure.
Note
This is also the same regular expression pattern syntax supported by NdbScanFilter; see Section 2.3.17.2.6, NdbScanFilter::cmp(), for more information.
The table being operated upon must be supplied when the NdbInterpretedCode object is instantiated. The regular expression pattern should be in plain CHAR format, even if the column is actually a VARCHAR (in other words, there should be no leading length
bytes).
These functions behave as shown here:
if (column_value [NOT] LIKE pattern)
goto Label;
The space requirements for these methods are shown in the following table, where L represents the length of the constant value:
Method
Buffer (words)
branch_col_like()
2 + CEIL(L / 8)
branch_col_notlike()
2 + CEIL(L / 8)
Note
The expression CEIL(L / 8) is the number of whole 8-byte words required to hold the constant value to be compared.
2.3.14.1.10.1. NdbInterpretedCode::branch_col_like()
Description. This method tests a table column value against a regular expression pattern and jumps to the indicated program label if
they match.
Signature.
int branch_col_like
(
const void* val,
Uint32 len,
Uint32 attrId,
Uint32 Label
123
A regular expression pattern (val); see Section 2.3.14.1.10, Pattern-Based NdbInterpretedCode Branch Operations, for the
syntax supported
The program label to jump to if the table column value matches the pattern
2.3.14.1.10.2. NdbInterpretedCode::branch_col_notlike()
Description. This method is similar to branch_col_like() in that it tests a table column value against a regular expression pattern; however it jumps to the indicated program label only if the pattern and the column value do not match.
Signature.
int branch_col_notlike
(
const void* val,
Uint32 len,
Uint32 attrId,
Uint32 Label
)
A regular expression pattern (val); see Section 2.3.14.1.10, Pattern-Based NdbInterpretedCode Branch Operations, for the
syntax supported
The program label to jump to if the table column value does not match the pattern
2.3.14.1.11.1. NdbInterpretedCode::branch_col_and_mask_eq_mask()
Description. This method is used to compare a BIT column value with a bitmask; if the column value ANDed together with the bitmask is equal to the bitmask, then execution jumps to a specified label specified in the method call.
Signature.
124
int branch_col_and_mask_eq_mask
(
const void* mask,
Uint32 unused,
Uint32 attrId,
Uint32 Label
)
Parameters. This method allows for 4 parameters, of which 3 are actually used:
2.3.14.1.11.2. NdbInterpretedCode::branch_col_and_mask_ne_mask()
Description. This method is used to compare a BIT column value with a bitmask; if the column value ANDed together with the bitmask is not equal to the bitmask, then execution jumps to a specified label specified in the method call.
Signature.
int branch_col_and_mask_ne_mask
(
const void* mask,
Uint32 unused,
Uint32 attrId,
Uint32 Label
)
Parameters. This method allows for 4 parameters, of which 3 are actually used:
2.3.14.1.11.3. NdbInterpretedCode::branch_col_and_mask_eq_zero()
Description. This method is used to compare a BIT column value with a bitmask; if the column value ANDed together with the bitmask is equal to 0, then execution jumps to a specified label specified in the method call.
Signature.
int branch_col_and_mask_eq_zero
(
const void* mask,
Uint32 unused,
Uint32 attrId,
Uint32 Label
)
Parameters. This method allows for 4 parameters, of which 3 are actually used:
2.3.14.1.11.4. NdbInterpretedCode::branch_col_and_mask_ne_zero()
Description. This method is used to compare a BIT column value with a bitmask; if the column value ANDed together with the bitmask is not equal to 0, then execution jumps to a specified label specified in the method call.
Signature.
int branch_col_and_mask_ne_zero
(
const void* mask,
Uint32 unused,
Uint32 attrId,
Uint32 Label
)
Parameters. This method allows for 4 parameters, of which 3 are actually used:
Buffer (words)
interpret_exit_ok()
interpret_exit_nok()
interpret_exit_last_row()
2.3.14.1.12.1. NdbInterpretedCode::interpret_exit_ok()
Description. For a scanning operation, this method indicates that the current row should be returned as part of the results of the scan
and that the program should move on to the next row. For other operations, calling this method causes the interpreted program to exit.
Signature.
int interpret_exit_ok
(
void
)
Parameters. None.
Return value. 0 on success, -1 on failure.
126
2.3.14.1.12.2. NdbInterpretedCode::interpret_exit_nok()
Description. For scanning operations, this method is used to indicate that the current row should not be returned as part of the scan,
and to cause the program should move on to the next row. It causes other types of operations to be aborted.
Signature.
int interpret_exit_nok
(
Uint32 ErrorCode = 899
)
Parameters. This method takes a single (optional) parameter ErrorCode which defaults to NDB error code 899 (ROWID ALREADY
ALLOCATED). For a complete listing of NDB error codes, see Section 5.2.2, NDB Error Codes and Messages.
Return value. 0 on success, -1 on failure.
2.3.14.1.12.3. NdbInterpretedCode::interpret_last_row()
Description. For a scanning operation, invoking this method indicates that this row should be returned as part of the scan, and that no
more rows in this fragment should be scanned. For other types of operations, the method causes the operation to be aborted.
Signature.
int interpret_exit_last_row
(
void
)
Parameters. None.
Return value. 0 if successful, -1 otherwise.
Important
In addition to updating the table column, these methods use interpreter registers 6 and 7, replacing any existing contents of
register 6 with the original column value and any existing contents of register 7 with the modified column value. The table
itself must be previously defined when instantiating the NdbInterpretedCode object for which the method is invoked.
The space requirements for these methods are shown in the following table, where L represents the length of the constant value:
Method
Buffer (words)
add_value()
sub_value()
2.3.14.1.13.1. NdbInterpretedCode::add_val()
Description. This method adds a specified value to the value of a given table column, and places the original and modified column values in registers 6 and 7. It is equivalent to the following series of NdbInterpretedCode method calls, where attrId is the table
column' attribute ID and aValue is the value to be added:
read_attr(6, attrId);
load_const_u32(7, aValue);
add_reg(7,6,7);
write_attr(attrId, 7);
127
Signature.
int add_val
(
Uint32 attrId,
Uint32 aValue
)
or
int add_val
(
Uint32 attrId,
Uint64 aValue
)
Parameters. A table column attribute ID and a 32-bit or 64-bit integer value to be added to this column value.
Return value. 0 on success, -1 on failure.
2.3.14.1.13.2. NdbInterpretedCode::sub_val()
Description. This method subtracts a specified value from the value of a given table column, and places the original and modified
column values in registers 6 and 7. It is equivalent to the following series of NdbInterpretedCode method calls, where attrId is
the table column' attribute ID and aValue is the value to be subtracted:
read_attr(6, attrId);
load_const_u32(7, aValue);
sub_reg(7,6,7);
write_attr(attrId, 7);
or
int sub_val
(
Uint32 attrId,
Uint64 aValue
)
Parameters. A table column attribute ID and a 32-bit or 64-bit integer value to be subtracted from this column value.
Return value. 0 on success, -1 on failure.
Important
Numbers used to identify subroutines must be contiguous; however, they do not have to be in any particular order.
The beginning of a subroutine is indicated by invoking the def_sub() method; all instructions after this belong to this subroutine until the subroutine is terminated with ret_sub(). A subroutine is called using call_sub().
Once the subroutine has completed, the program resumes execution with the instruction immediately following the one which invoked
the subroutine. Subroutines can also be invoked from other subroutines; currently, the maximum subroutine stack depth is 32.
2.3.14.1.14.1. NdbInterpretedCode::def_sub()
Description. This method is used to mark the start of a subroutine. See Section 2.3.14.1.14, Using Subroutines with NdbInter128
2.3.14.1.14.2. NdbInterpretedCode::call_sub()
Description. This method is used to call a subroutine.
Signature.
int call_sub
(
Uint32 SubroutineNumber
)
Parameters. This method takes a single parameter, the number identifying the subroutine to be called.
Return value. 0 on success, -1 on failure.
2.3.14.1.14.3. NdbInterpretedCode::ret_sub()
Description. This method marks the end of the current subroutine.
Signature.
int ret_sub
(
void
)
Parameters. None.
Return value. 0 on success, -1 otherwise.
2.3.14.1.15.1. NdbInterpretedCode::finalise()
Description. This method prepares an interpreted program, including any subroutines it might have, by resolving all branching instructions and calls to subroutines. It must be called before using the program, and can be invoked only once for any given NdbInterpretedCode object.
If no instructions have been defined, this method attempts to insert a single interpret_exit_ok() method call prior to finalization.
Signature.
int finalise
(
void
)
Parameters. None.
Return value. 0 on success, -1 otherwise.
2.3.14.1.15.2. NdbInterpretedCode::getTable()
129
Description. This method can be used to obtain a reference to the table for which the NdbInterpretedCode object was defined.
Signature.
const NdbDictionary::Table* getTable
(
void
) const
Parameters. None.
Return value. A pointer to a Table object. Returns NULL if no table object was supplied when the NdbInterpretedCode was instantiated.
2.3.14.1.15.3. NdbInterpretedCode::getNdbError()
Description. This method returns the most recent error associated with this NdbInterpretedCode object.
Signature.
const class NdbError& getNdbError
(
void
) const
Parameters. None.
Return value. A reference to an NdbError object. See Section 2.3.31, The NdbError Structure, for more information.
2.3.14.1.15.4. NdbInterpretedCode::getWordsUsed()
Description. This method returns the number of words from the buffer that have been used, whether the buffer is one that is usersupplied or the internally-provided buffer.
Signature.
Uint32 getWordsUsed
(
void
) const
Parameters. None.
Return value. The number of words used from the buffer.
130
Description. NdbOperation represents a generic data operation. Its subclasses represent more specific types of operations. See
Section 2.3.15.1.2, The NdbOperation::Type Type for a listing of operation types and their corresponding NdbOperation
subclasses.
Methods. The following table lists the public methods of this class and the purpose or use of each method:
Method
Purpose / Use
getValue()
getBlobHandle()
getTableName()
getTable()
getNdbError()
getNdbErrorLine()
Gets the number of the method where the latest error occurred
getType()
getLockMode()
getNdbTransaction()
equal()
Method
Purpose / Use
setValue()
insertTuple()
updateTuple()
readTuple()
writeTuple()
deleteTuple()
For detailed descriptions, signatures, and examples of use for each of these methods, see Section 2.3.15.2, NdbOperation
Methods.
Types. The NdbOperation class defines three public types, as shown in the following table:
Type
Purpose / Use
AbortOption
Type
LockMode
For a discussion of each of these types, along with its possible values, see Section 2.3.15.1, NdbOperation Types.
Class diagram. This diagram shows all the available methods and enumerated types of the NdbOperation class:
132
133
Note
For more information about the use of NdbOperation, see Section 1.3.2.3.1, Single-row operations.
Description
AbortOnError
AO_IgnoreOnError
DefaultAbortOption
DefaultAbortOperation is available beginning with MySQL Cluster NDB 6.2.0. See Section 2.3.19.2.5, NdbTransaction::execute(), for more information.
Important
Previous to MySQL Cluster NDB 6.2.0, this type belonged to the NdbTransaction class.
Description
Class
PrimaryKeyAccess
A read, insert, update, or delete operation using the table's primary key
NdbOperation
UniqueIndexAccess
NdbIndexOperation
TableScan
NdbScanOperation
OrderedIndexScan
NdbIndexScanOperation
Description
LM_Read
LM_Exclusive
LM_CommittedRead
Value
Description
LM_SimpleRead
Note
There is also support for dirty reads (LM_Dirty), but this is normally for internal purposes only, and should not be used
for applications deployed in a production setting.
Note
This class has no public constructor. To create an instance of NdbOperation, you must use NdbTransaction::getNdbOperation(). See Section 2.3.19.2.1, NdbTransaction::getNdbOperation(), for more
information.
2.3.15.2.1. NdbOperation::getValue()
Description. This method prepares for the retrieval of an attribute value. The NDB API allocates memory for an NdbRecAttr object
that is later used to obtain the attribute value. This can be done by using one of the many NdbRecAttr accessor methods, the exact
method to be used depending on the attribute's data type. (This includes the generic NdbRecAttr::aRef() which retrieves the data
as char*, regardless of its actual type. However, this is not type-safe, and requires a cast from the user.) See Section 2.3.16, The NdbRecAttr Class, and Section 2.3.16.1.19, NdbRecAttr::aRef(), for more information.
Important
This method does not fetch the attribute value from the database; the NdbRecAttr object returned by this method is not
readable or printable before calling NdbTransaction::execute().
If a specific attribute has not changed, the corresponding NdbRecAttr has the state UNDEFINED. This can be checked
by using NdbRecAttr::isNULL(), which in such cases returns -1.
See Section 2.3.19.2.5, NdbTransaction::execute(), and Section 2.3.16.1.4, NdbRecAttr::isNULL().
Signature. There are three versions of this method, each having different parameters:
NdbRecAttr* getValue
(
const char* name,
char*
value = 0
)
NdbRecAttr* getValue
(
Uint32 id,
char* value = 0
)
NdbRecAttr* getValue
(
const NdbDictionary::Column* col,
char*
value = 0
)
Parameters. All three forms of this method have two parameters, the second parameter being optional (defaults to 0). They differ with
regard to the type of the first parameter, which can be any one of the following:
The attribute id
In all three cases, the second parameter is a character buffer in which a non-NULL attribute value is returned. In the event that the attrib135
ute is NULL, is it stored only in the NdbRecAttr object returned by this method.
If no value is specified in the getValue() method call, or if 0 is passed as the value, then the NdbRecAttr object provides
memory management for storing the received data. If the maximum size of the received data is above a small fixed size, malloc() is
used to store it: For small sizes, a small, fixed internal buffer (32 bytes in extent) is provided. This storage is managed by the NdbRecAttr instance; it is freed when the operation is released, such as at transaction close time; any data written here that you wish to preserve should be copied elsewhere before this freeing of memory takes place.
If you pass a non-zero pointer for value, then it is assumed that this points to an portion of memory which is large enough to hold the
maximum value of the column; any returned data is written to that location. The pointer should be at least 32-bit aligned.
Return value. A pointer to an NdbRecAttr object to hold the value of the attribute, or a NULL pointer, indicating an error.
Retrieving integers. Integer values can be retrieved from both the value buffer passed as this method's second parameter, and from
the NdbRecAttr object itself. On the other hand, character data is available from NdbRecAttr if no buffer has been passed in to
getValue() (see Section 2.3.16.1.19, NdbRecAttr::aRef()). However, character data is written to the buffer only if one is
provided, in which case it cannot be retrieved from the NdbRecAttr object that was returned. In the latter case, NdbRecAttr::aRef() returns a buffer pointing to an empty string.
Accessing bit values. The following example shows how to check a given bit from the value buffer. Here, op is an operation (NdbOperation object), name is the name of the column from which to get the bit value, and trans is an NdbTransaction object.
Uint32 buf[];
op->getValue(name, buf); /* bit column */
trans->execute();
if(buf[X/32] & 1 << (X & 31)) /* check bit X */
{
/* bit X set */
}
2.3.15.2.2. NdbOperation::getBlobHandle()
Description. This method is used in place of getValue() or setValue() for blob attributes. It creates a blob handle (NdbBlob
object). A second call with the same argument returns the previously created handle. The handle is linked to the operation and is maintained automatically. See Section 2.3.9, The NdbBlob Class, for details.
Signature. This method has two forms, depending on whether it is called with the name or the ID of the blob attribute:
virtual NdbBlob* getBlobHandle
(
const char* name
)
or
virtual NdbBlob* getBlobHandle
(
Uint32 id
)
Parameters. This method takes a single parameter, which can be either one of the following:
Return value. Regardless of parameter type used, this method return a pointer to an instance of NdbBlob.
2.3.15.2.3. NdbOperation::getTableName()
Description. This method retrieves the name of the table used for the operation.
Signature.
const char* getTableName
(
136
void
) const
Parameters. None.
Return value. The name of the table.
2.3.15.2.4. NdbOperation::getTable()
Description. This method is used to retrieve the table object associated with the operation.
Signature.
const NdbDictionary::Table* getTable
(
void
) const
Parameters. None.
Return value. An instance of Table. For more information, see Section 2.3.21, The Table Class.
2.3.15.2.5. NdbOperation::getNdbError()
Description. This method gets the most recent error (an NdbError object).
Signature.
const NdbError& getNdbError
(
void
) const
Parameters. None.
Return value. An NdbError object. See Section 2.3.31, The NdbError Structure.
2.3.15.2.6. NdbOperation::getNdbErrorLine()
Description. This method retrieves the method number in which the latest error occurred.
Signature. Beginning with MySQL Cluster NDB 6.2.17 and MySQL Cluster NDB 6.3.19, this method can (and should) be used as
shown here:
int getNdbErrorLine
(
void
) const
The non-const version of this method, shown here, was removed in MySQL Cluster NDB 6.2.19, MySQL Cluster NDB 6.3.28, and
MySQL Cluster NDB 7.0.9. (Bug#47798)
int getNdbErrorLine
(
void
)
Parameters. None.
Return value. The method number (an integer).
2.3.15.2.7. NdbOperation::getType()
Description. This method is used to retrieve the access type for this operation.
Signature.
Type getType
137
(
void
) const
Parameters. None.
Note
Prior to MySQL Cluster NDB 7.1.0, this method used const Type as its return type. (Bug#44840)
Return value. A Type value. See Section 2.3.15.1.2, The NdbOperation::Type Type.
2.3.15.2.8. NdbOperation::getLockMode()
Description. This method gets the operation's lock mode.
Signature.
LockMode getLockMode
(
void
) const
Parameters. None.
Return value. A LockMode value. See Section 2.3.15.1.3, The NdbOperation::LockMode Type.
2.3.15.2.9. NdbOperation::getNdbTransaction()
Description. Gets the NdbTransaction object for this operation. Available beginning with MySQL Cluster NDB 6.2.17 and
MySQL Cluster NDB 6.3.19.
Signature.
virtual NdbTransaction* getNdbTransaction
(
void
) const
Parameters. None.
Return value. A pointer to an NdbTransaction object. See Section 2.3.19, The NdbTransaction Class.
2.3.15.2.10. NdbOperation::equal()
Description. This method defines a search condition with an equality. The condition is true if the attribute has the given value. To set
search conditions on multiple attributes, use several calls to equal(); in such cases all of them must be satisfied for the tuple to be selected.
Important
If the attribute is of a fixed size, its value must include all bytes. In particular a Char value must be native-blank padded.
If the attribute is of variable size, its value must start with 1 or 2 little-endian length bytes (2 if its type is Long*).
Note
When using insertTuple(), you may also define the search key with setValue(). See Section 2.3.15.2.11, NdbOperation::setValue().
Signature. There are 10 versions of equal(), each having slightly different parameters. All of these are listed here:
int
int
equal
(
const char* name,
const char* value
)
equal
138
(
const char* name,
Int32
value
)
int
equal
(
const char* name,
Uint32
value
)
int
equal
(
const char* name,
Int64
value
)
int
equal
(
const char* name,
Uint64
value
)
int
equal
(
Uint32
id,
const char* value
)
int
equal
(
Uint32 id,
Int32 value
)
int
equal
(
Uint32 id,
Uint32 value
)
int
equal
(
Uint32 id,
Int64 value
)
int
equal
(
Uint32 id,
Uint64 value
)
The second parameter is the attribute value to be tested; it can be any one of the following 5 types:
String
32-bit integer
64-bit integer
2.3.15.2.11. NdbOperation::setValue()
Description. This method defines an attribute to be set or updated.
139
Important
There are a number of NdbOperation::setValue() methods that take a certain type as input (pass by value rather
than passing a pointer). It is the responsibility of the application programmer to use the correct types.
However, the NDB API does check that the application sends a correct length to the interface as given in the length parameter. A char* value can contain any datatype or any type of array. If the length is not provided, or if it is set to zero,
then the API assumes that the pointer is correct, and does not check it.
Tip
To set a NULL value, use the following construct:
setValue("ATTR_NAME", (char*)NULL);
Note
When you use insertTuple(), the NDB API will automatically detect that it is supposed to use equal() instead.
In addition, it is not necessary when using insertTuple() to use setValue() on key attributes before other attributes.
Signature. There are 14 versions of NdbOperation::setValue(), each with slightly different parameters, as listed here (and
summarised in the Parameters section following):
int setValue
(
const char* name,
const char* value
)
int setValue
(
const char* name,
Int32
value
)
int setValue
(
const char* name,
Uint32
value
)
int setValue
(
const char* name,
Int64
value
)
int setValue
(
const char* name,
Uint64
value
)
int setValue
(
const char* name,
float
value
)
int setValue
(
const char* name,
double
value
)
int setValue
(
Uint32
id,
const char* value
)
int setValue
(
Uint32 id,
Int32 value
)
int setValue
(
140
Uint32 id,
Uint32 value
)
int setValue
(
Uint32 id,
Int64 value
)
int setValue
(
Uint32 id,
Uint64 value
)
int setValue
(
Uint32 id,
float value
)
int setValue
(
Uint32 id,
double value
)
The first parameter identified the attribute to be set, and may be either one of:
The second parameter is the value to which the attribute is to be set; its type may be any one of the following 7 types:
32-bit integer
64-bit integer
Double
Float
See Section 2.3.15.2.10, NdbOperation::equal(), for important information regarding the value's format and length.
Return value. Returns -1 in the event of failure.
2.3.15.2.12. NdbOperation::insertTuple()
Description. This method defines the NdbOperation to be an INSERT operation. When the NdbTransaction::execute()
method is called, this operation adds a new tuple to the table. See Section 2.3.19.2.5, NdbTransaction::execute().
Signature.
virtual int insertTuple
(
void
)
Parameters. None.
Return value. 0 on success, -1 on failure.
141
2.3.15.2.13. NdbOperation::readTuple()
Description. This method define the NdbOperation as a READ operation. When the NdbTransaction::execute() method is
invoked, the operation reads a tuple. See Section 2.3.19.2.5, NdbTransaction::execute().
Signature.
virtual 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.15.2.14. NdbOperation::writeTuple()
Description. This method defines the NdbOperation as a WRITE operation. When the NdbTransaction::execute() method is invoked, the operation writes a tuple to the table. If the tuple already exists, it is updated; otherwise an insert takes place. See Section 2.3.19.2.5, NdbTransaction::execute().
Signature.
virtual int writeTuple
(
void
)
Parameters. None.
Return value. 0 on success, -1 on failure.
2.3.15.2.15. NdbOperation::updateTuple()
Description. This method defines the NdbOperation as an UPDATE operation. When the NdbTransaction::execute()
method is invoked, the operation updates a tuple found in the table. See Section 2.3.19.2.5, NdbTransaction::execute().
Signature.
virtual int updateTuple
(
void
)
Parameters. None.
Return value. 0 on success, -1 on failure.
2.3.15.2.16. NdbOperation::deleteTuple()
Description. This method defines the NdbOperation as a DELETE operation. When the NdbTransaction::execute() method is invoked, the operation deletes a tuple from the table. See Section 2.3.19.2.5, NdbTransaction::execute().
Signature.
virtual int deleteTuple
(
void
)
Parameters. None.
Return value. 0 on success, -1 on failure.
142
Note
An NdbRecAttr object is instantiated with its value when NdbTransaction::execute() is invoked. Prior to this,
the value is undefined. (Use NdbRecAttr::isNULL() to check whether the value is defined.) This means that an NdbRecAttr object has valid information only between the times that NdbTransaction::execute() and
Ndb::closeTransaction() are called. The value of the NULL indicator is -1 until the NdbTransaction::execute() method is invoked.
Methods. NdbRecAttr has a number of methods for retrieving values of various simple types directly from an instance of this class.
Note
It is also possible to obtain a reference to the value regardless of its actual type, by using NdbRecAttr::aRef();
however, you should be aware that this is not type-safe, and requires a cast from the user. See Section 2.3.16.1.19, NdbRecAttr::aRef(), for more information.
The following table lists all of the public methods of this class and the purpose or use of each method:
Method
Purpose / Use
getColumn()
getType()
get_size_in_bytes()
isNULL()
int64_value()
int32_value()
medium_value()
short_value()
char_value()
int8_value()
u_64_value()
u_32_value()
u_medium_value()
u_short_value()
u_char_value()
u_8_value()
float_value()
143
Method
Purpose / Use
double_value()
aRef()
clone()
~NdbRecAttr()
Destructor method
For detailed descriptions, signatures, and examples of use for each of these methods, see Section 2.3.16.1, NdbRecAttr Methods.
Types. The NdbRecAttr class defines no public types.
Class diagram. This diagram shows all the available methods of the NdbRecAttr class:
2.3.16.1.1. NdbRecAttr::getColumn()
Description. This method is used to obtain the column to which the attribute belongs.
Signature.
const NdbDictionary::Column* getColumn
(
void
) const
Parameters. None.
144
Return value. A pointer to a Column object. See Section 2.3.1, The Column Class.
2.3.16.1.2. NdbRecAttr::getType()
Description. This method is used to obtain the column's datatype.
Signature.
NdbDictionary::Column::Type getType
(
void
) const
Parameters. None.
Return value. An NdbDictionary::Column::Type value. See Section 2.3.1.1.3, Column::Type for more information, including permitted values.
2.3.16.1.3. NdbRecAttr::get_size_in_bytes()
Description. You can use this method to obtain the size of an attribute (element).
Signature.
Uint32 get_size_in_bytes
(
void
) const
Parameters. None.
Return value. The attribute size in bytes, as an unsigned 32-bit integer.
2.3.16.1.4. NdbRecAttr::isNULL()
Description. This method checks whether an attribute value is NULL.
Signature.
int isNULL
(
void
) const
Parameters. None.
Return value. One of the following 3 values:
Important
In the event that NdbTransaction::execute() has not yet been called, the value returned by isNull() is not determined.
2.3.16.1.5. NdbRecAttr::int64_value()
Description. This method gets a Bigint value stored in an NdbRecAttr object, and returns it as a 64-bit signed integer.
Signature.
145
Int64 int64_value
(
void
) const
Parameters. None.
Return value. A 64-bit signed integer.
2.3.16.1.6. NdbRecAttr::int32_value()
Description. This method gets an Int value stored in an NdbRecAttr object, and returns it as a 32-bit signed integer.
Signature.
Int32 int32_value
(
void
) const
Parameters. None.
Return value. A 32-bit signed integer.
2.3.16.1.7. NdbRecAttr::medium_value()
Description. Gets the value of a Mediumint value stored in an NdbRecAttr object, and returns it as a 32-bit signed integer.
Signature.
Int32 medium_value
(
void
) const
Parameters. None.
Return value. A 32-bit signed integer.
2.3.16.1.8. NdbRecAttr::short_value()
Description. This method gets a Smallint value stored in an NdbRecAttr object, and returns it as a 16-bit signed integer (short).
Signature.
short short_value
(
void
) const
Parameters. None.
Return value. A 16-bit signed integer.
2.3.16.1.9. NdbRecAttr::char_value()
Description. This method gets a Char value stored in an NdbRecAttr object, and returns it as a char.
Signature.
char char_value
(
void
) const
Parameters. None.
146
2.3.16.1.10. NdbRecAttr::int8_value()
Description. This method gets a Small value stored in an NdbRecAttr object, and returns it as an 8-bit signed integer.
Signature.
Int8 int8_value
(
void
) const
Parameters. None.
Return value. An 8-bit signed integer.
2.3.16.1.11. NdbRecAttr::u_64_value()
Description. This method gets a Bigunsigned value stored in an NdbRecAttr object, and returns it as a 64-bit unsigned integer.
Signature.
Uint64 u_64_value
(
void
) const
Parameters. None.
Return value. A 64-bit unsigned integer.
2.3.16.1.12. NdbRecAttr::u_32_value()
Description. This method gets an Unsigned value stored in an NdbRecAttr object, and returns it as a 32-bit unsigned integer.
Signature.
Uint32 u_32_value
(
void
) const
Parameters. None.
Return value. A 32-bit unsigned integer.
2.3.16.1.13. NdbRecAttr::u_medium_value()
Description. This method gets an Mediumunsigned value stored in an NdbRecAttr object, and returns it as a 32-bit unsigned integer.
Signature.
Uint32 u_medium_value
(
void
) const
Parameters. None.
Return value. A 32-bit unsigned integer.
Example.
[To be supplied...]
147
2.3.16.1.14. NdbRecAttr::u_short_value()
Description. This method gets a Smallunsigned value stored in an NdbRecAttr object, and returns it as a 16-bit (short) unsigned
integer.
Signature.
Uint16 u_short_value
(
void
) const
Parameters. None.
Return value. A short (16-bit) unsigned integer.
2.3.16.1.15. NdbRecAttr::u_char_value()
Description. This method gets a Char value stored in an NdbRecAttr object, and returns it as an unsigned char.
Signature.
Uint8 u_char_value
(
void
) const
Parameters. None.
Return value. An 8-bit unsigned char value.
2.3.16.1.16. NdbRecAttr::u_8_value()
Description. This method gets a Smallunsigned value stored in an NdbRecAttr object, and returns it as an 8-bit unsigned integer.
Signature.
Uint8 u_8_value
(
void
) const
Parameters. None.
Return value. An 8-bit unsigned integer.
2.3.16.1.17. NdbRecAttr::float_value()
Description. This method gets a Float value stored in an NdbRecAttr object, and returns it as a float.
Signature.
float float_value
(
void
) const
Parameters. None.
Return value. A float (4 bytes).
2.3.16.1.18. NdbRecAttr::double_value()
Description. This method gets a Double value stored in an NdbRecAttr object, and returns it as a double.
Signature.
148
double double_value
(
void
) const
Parameters. None.
Return value. A double (8 bytes).
2.3.16.1.19. NdbRecAttr::aRef()
Description. This method is used to obtain a reference to an attribute value, as a char pointer. This pointer is aligned appropriately for
the datatype. The memory is released by the NDB API when NdbTransaction::closeTransaction() is executed on the
transaction which read the value.
Signature.
char* aRef
(
void
) const
Parameters. A pointer to the attribute value. Because this pointer is constant, this method can be called anytime after NdbOperation::getValue() has been called.
Return value. None.
2.3.16.1.20. NdbRecAttr::clone()
Description. This method creates a deep copy of an NdbRecAttr object.
Note
The copy created by this method should be deleted by the application when no longer needed.
Signature.
NdbRecAttr* clone
(
void
) const
Parameters. None.
Return value. An NdbRecAttr object. This is a complete copy of the original, including all data.
2.3.16.1.21. ~NdbRecAttr()
Description. The NdbRecAttr class destructor method.
Important
You should delete only copies of NdbRecAttr objects that were created in your application using the clone() method.
See Section 2.3.16.1.20, NdbRecAttr::clone().
Signature.
~NdbRecAttr
(
void
)
Parameters. None.
Return value. None.
149
Important
Prior to MySQL 5.1.14, the comparison methods of this class did not work with BIT values (see Bug#24503).
Development of this interface continues in MySQL 5.1, and the charcateristics of the NdbScanFilter class are likely to
change further in future releases.
Methods. The following table lists the public methods of this class and the purpose or use of each method:
Method
Purpose / Use
NdbScanFilter()
Constructor method
~NdbScanFilter()
Destructor method
begin()
end()
Ends a compound
istrue()
isfalse()
cmp()
eq()
ne()
lt()
le()
gt()
ge()
isnull()
isnotnull()
getNdbError()
getNdbOperation()
For detailed descriptions, signatures, and examples of use for each of these methods, see Section 2.3.17.2, NdbScanFilter Methods.
Types. The NdbScanFilter class defines two public types:
For a discussion of each of these types, along with its possible values, see Section 2.3.17.1, NdbScanFilter Types.
Class diagram. This diagram shows all the public members of the NdbScanFilter class:
150
151
Description
COND_LE
integer
COND_LT
integer
COND_GE
integer
COND_GT
integer
COND_EQ
Equality (=)
integer
COND_NE
integer
COND_LIKE
LIKE condition
string
COND_NOTLIKE
string
COL_AND_MASK_EQ_MASK
COL_AND_MASK_NE_MASK
COL_AND_MASK_EQ_ZERO
COL_AND_MASK_NE_ZERO
BIT
BIT
String comparisons. Strings compared using COND_LIKE and COND_NOTLIKE can use the pattern metacharacters % and _. See Section 2.3.17.2.6, NdbScanFilter::cmp(), for more information.
BIT comparisons. The BIT comparison operators COL_AND_MASK_EQ_MASK, COL_AND_MASK_NE_MASK,
COL_AND_MASK_EQ_ZERO, and COL_AND_MASK_NE_ZERO were added in MySQL Cluster NDB 6.3.20. Corresponding methods
are also available for NdbInterpretedCode and NdbOperation beginning with MySQL Cluster NDB 6.3.20; for more information about these methods, see Section 2.3.14.1.11, NdbInterpretedCode Bitwise Comparison Operations.
Description
AND
OR
Logical OR: A OR B OR C
NAND
NOR
152
Parameters. This method takes a single parameter: a pointer to the NdbOperation to which the filter applies.
Return value. A new instance of NdbScanFilter.
Destructor. The destructor takes no arguments and does not return a value. It should be called to remove the NdbScanFilter object
when it is no longer needed.
2.3.17.2.2. NdbScanFilter::begin()
Description. This method is used to start a compound, and specifies the logical operator used to group together the conditions making
up the compound. The default is AND.
Signature.
int begin
(
Group group = AND
)
Parameters. A Group value: one of AND, OR, NAND, or NOR. See Section 2.3.17.1.2, The NdbScanFilter::Group Type, for
additional information.
Return value. 0 on success, -1 on failure.
2.3.17.2.3. NdbScanFilter::end()
Description. This method completes a compound, signalling that there are no more conditions to be added to it.
Signature.
int end
(
void
)
Parameters. None.
Return value. 0 on success, -1 on failure.
2.3.17.2.4. NdbScanFilter::istrue()
Description. Defines a term of the current group as TRUE.
Signature.
int istrue
(
void
)
Parameters. None.
Return value. 0 on success, -1 on failure.
2.3.17.2.5. NdbScanFilter::isfalse()
153
Parameters. None.
Return value. 0 on success, -1 on failure.
2.3.17.2.6. NdbScanFilter::cmp()
Description. This method is used to perform a comparison between a given value and the value of a column.
Note
In many cases, where the value to be compared is an integer, you can instead use one of several convenience methods
provided by NdbScanFilter for this purpose. See Section 2.3.17.2.7, NdbScanFilter Integer Comparison Methods.
Signature.
int cmp
(
BinaryCondition condition,
int columnId,
const void* value,
Uint32 length = 0
)
condition: This represents the condition to be tested which compares the value of the column having the column ID columnID
with some arbitrary value. The condition is a BinaryCondition value; for permitted values and the relations that they represent, see Section 2.3.17.1.1, The NdbScanFilter::BinaryCondition Type.
The condition values COND_LIKE or COND_NOTLIKE are used to compare a column value with a string pattern.
columnId: This is the column's identifier, which can be obtained using the Column::getColumnNo() method (see Section 2.3.1.2.5, Column::getColumnNo(), for details).
Metacharacter
Description
Note
These are the same wildcard characters that are supported by the SQL LIKE and NOT LIKE operators, and are interpreted in the same way. See String Comparison Functions, for more information.
length: The length of the value to be compared. The default value is 0. Using 0 for the length has the same effect as comparing
to NULL, that is using the isnull() method (see Section 2.3.17.2.8, NdbScanFilter::isnull()).
154
Return value. This method returns an integer whose value can be interpreted as shown here:
For more information about the cmp() method, see Section 2.3.17.2.6, NdbScanFilter::cmp().
2.3.17.2.7.1. NdbScanFilter::eq()
Description. This method is used to perform an equality test on a column value and an integer.
Signature.
int eq
(
int
ColId,
Uint32 value
)
or
int eq
(
int
ColId,
Uint64 value
)
An integer with which to compare the column value; this integer may be either 32-bit or 64-bit, and is unsigned in either case.
2.3.17.2.7.2. NdbScanFilter::ne()
Description. This method is used to perform an inequality test on a column value and an integer.
Signature.
int ne
(
int
ColId,
Uint32 value
)
or
int ne
(
int
ColId,
Uint64 value
)
155
Parameters. Like eq() and the other NdbScanFilter methods of this type, this method takes two parameters:
An integer with which to compare the column value; this integer may be either 32-bit or 64-bit, and is unsigned in either case.
2.3.17.2.7.3. NdbScanFilter::lt()
Description. This method is used to perform a less-than (strict lower bound) test on a column value and an integer.
Signature.
int lt
(
int
ColId,
Uint32 value
)
or
int lt
(
int
ColId,
Uint64 value
)
Parameters. Like eq(), ne(), and the other NdbScanFilter methods of this type, this method takes two parameters:
An integer with which to compare the column value; this integer may be either 32-bit or 64-bit, and is unsigned in either case.
2.3.17.2.7.4. NdbScanFilter::le()
Description. This method is used to perform a less-than-or-equal test on a column value and an integer.
Signature.
int le
(
int
ColId,
Uint32 value
)
or
int le
(
int
ColId,
Uint64 value
)
Parameters. Like the other NdbScanFilter methods of this type, this method takes two parameters:
An integer with which to compare the column value; this integer may be either 32-bit or 64-bit, and is unsigned in either case.
2.3.17.2.7.5. NdbScanFilter::gt()
156
Description. This method is used to perform a greater-than (strict upper bound) test on a column value and an integer.
Signature.
int gt
(
int
ColId,
Uint32 value
)
or
int gt
(
int
ColId,
Uint64 value
)
Parameters. Like the other NdbScanFilter methods of this type, this method takes two parameters:
An integer with which to compare the column value; this integer may be either 32-bit or 64-bit, and is unsigned in either case.
2.3.17.2.7.6. NdbScanFilter::ge()
Description. This method is used to perform a greater-than-or-equal test on a column value and an integer.
Signature.
int ge
(
int
ColId,
Uint32 value
)
or
int ge
(
int
ColId,
Uint64 value
)
Parameters. Like eq(), lt(), le(), and the other NdbScanFilter methods of this type, this method takes two parameters:
An integer with which to compare the column value; this integer may be either 32-bit or 64-bit, and is unsigned in either case.
2.3.17.2.8. NdbScanFilter::isnull()
Description. This method is used to check whether a column value is NULL.
Signature.
int isnull
(
int ColId
)
157
2.3.17.2.9. NdbScanFilter::isnotnull()
Description. This method is used to check whether a column value is not NULL.
Signature.
int isnotnull
(
int ColId
)
2.3.17.2.10. NdbScanFilter::getNdbError()
Description. Because errors encountered when building an NdbScanFilter do not propagate to any involved NdbOperation object, it
is necessary to use this method to access error information.
Signature.
const NdbError& getNdbError
(
void
)
Parameters. None.
Return value. A reference to an NdbError. See Section 2.3.31, The NdbError Structure, for more information.
2.3.17.2.11. NdbScanFilter::getNdbOperation()
Description. If the NdbScanFilter was constructed with an NdbOperation, this method can be used to obtain a pointer to that
NdbOperation object.
Signature.
NdbOperation* getNdbOperation
(
void
)
Parameters. None.
Return value. A pointer to the NdbOperation associated with this NdbScanFilter, if there is one. Otherwise, NULL.
Note
Beginning with MySQL Cluster NDB 6.2.14 and MySQL Cluster 6.3.12, you must use the NdbInterpretedCode
class instead of NdbScanOperation when writing interpreted programs used for scans. See Section 2.3.14, The NdbInterpretedCode Class, for more information.
158
Methods. The following table lists the public methods of this class and the purpose or use of each method:
Method
Purpose / Use
readTuples()
Reads tuples
nextResult()
close()
lockCurrentTuple()
updateCurrentTuple()
deleteCurrentTuple()
restart()
getNdbTransaction()
getPruned()
For detailed descriptions, signatures, and examples of use for each of these methods, see Section 2.3.18.2, NdbScanOperation
Methods.
Types. This class defines a single public type ScanFlag. See Section 2.3.18.1, The NdbScanOperation::ScanFlag Type,
for details.
Class diagram. This diagram shows all the available members of the NdbScanOperation class:
Note
For more information about the use of NdbScanOperation, see Section 1.3.2.3.2, Scan Operations, and Section 1.3.2.3.3, Using Scans to Update or Delete Rows.
Multi-Range Read (MRR) scans using NdbScanOperation are not supported using MySQL Cluster NDB 6.2. They
are supported for MySQL Cluster NDB 6.3 beginning with 6.3.17. (Bug#38791) Both NDB 6.2 and NDB 6.3 support
MRR scans using the NdbRecord interface.
159
Description
SF_TupScan
TUP scan
SF_OrderBy
SF_Descending
SF_ReadRangeNo
Enables NdbIndexScanOperation::get_range_no()
SF_KeyInfo
Note
This class has no public constructor. To create an instance of NdbScanOperation, it is necessary to use the NdbTransaction::getNdbScanOperation() method. See Section 2.3.19.2.2, NdbTransaction::getNdbScanOperation().
2.3.18.2.1. NdbScanOperation::readTuples()
Description. This method is used to perform a scan.
Signature.
virtual int readTuples
(
LockMode mode = LM_Read,
Uint32
flags = 0,
Uint32
parallel = 0,
Uint32
batch = 0
)
The lock mode; this is a LockMode value as described in Section 2.3.15.1.3, The NdbOperation::LockMode Type.
Caution
When scanning with an exclusive lock, extra care must be taken due to the fact that, if two threads perform this scan simultaneously over the same range, then there is a significant probability of causing a deadlock. The likelihood of a deadlock
is increased if the scan is also ordered (that is, using SF_OrderBy or SF_Descending).
The NdbIndexScanOperation::close() method is also affected by this deadlock, since all outstanding requests
are serviced before the scan is actually closed.
We are working to resolve this issue in a future release.
The number of fragments to scan in parallel; use 0 to require that the maximum possible number be used.
The batch parameter specifies how many records will be returned to the client from the server by the next NdbScanOperation::nextResult(true) method call. Use 0 to specify the maximum automatically.
160
Note
This parameter was ignored prior to MySQL 5.1.12, and the maximum was used. (Bug#20252)
Return value. 0 on success, -1 on failure.
2.3.18.2.2. NdbScanOperation::nextResult()
Description. This method is used to fetch the next tuple in a scan transaction. Following each call to nextResult(), the buffers and
NdbRecAttr objects defined in NdbOperation::getValue() are updated with values from the scanned tuple.
Signature.
int nextResult
(
bool fetchAllowed = true,
bool forceSend = false
)
Beginning with MySQL Cluster NDB 6.2.3, it is also possible to use this method as shown here:
int nextResult
(
const char*& outRow,
bool fetchAllowed = true,
bool forceSend = false
)
Normally, the NDB API contacts the NDB kernel for more tuples whenever it is necessary; setting fetchAllowed to false
keeps this from happening.
Disabling fetchAllowed by setting it to false forces NDB to process any records it already has in its caches. When there are no
more cached records it returns 2. You must then call nextResult() with fetchAllowed equal to true in order to contact
NDB for more records.
While nextResult(false) returns 0, you should transfer the record to another transaction. When nextResult(false) returns 2, you must execute and commit the other transaction. This causes any locks to be transferred to the other transaction, updates
or deletes to be made, and then, the locks to be released. Following this, call nextResult(true) this fetches more records
and caches them in the NDB API.
Note
If you do not transfer the records to another transaction, the locks on those records will be released the next time that the
NDB Kernel is contacted for more records.
Disabling fetchAllowed can be useful when you want to update or delete all of the records obtained in a given transaction, as
doing so saves time and speeds up updates or deletes of scanned records.
forceSend defaults to false, and can normally be omitted. However, setting this parameter to true means that transactions are
sent immediately. See Section 1.3.4, The Adaptive Send Algorithm, for more information.
Parameters. Beginning with MySQL Cluster NDB 6.2.3, this method can also be called with the following parameters:
Calling nextResult() sets a pointer to the next row in outRow (if returning 0). This pointer is valid (only) until the next call to
nextResult() when fetchAllowed is true. The NdbRecord object defining the row format must be specified beforehand
using NdbTransaction::scanTable() (or NdbTransaction::scanIndex().
When false, fetchAllowed forces NDB to process any records it already has in its caches. See the description for this parameter
in the previous Parameters subsection for more details.
Setting forceSend to true means that transactions are sent immediately, as described in the previous Parameters subsection, as
161
2: There are no more cached records (invoke nextResult(true) to fetch more records).
2.3.18.2.3. NdbScanOperation::close()
Description. Calling this method closes a scan.
Note
See Scans and exclusive locks for information about multiple threads attempting to perform the same scan with an exclusive lock and how this can affect closing the scans..
Signature.
void close
(
bool forceSend = false,
bool releaseOp = false
)
forceSend defaults to false; call close() with this parameter set to true in order to force transactions to be sent.
releaseOp also defaults to false; set to true in order to release the operation.
2.3.18.2.4. NdbScanOperation::lockCurrentTuple()
Description. This method locks the current tuple.
Signature.
NdbOperation* lockCurrentTuple
(
void
)
or
NdbOperation* lockCurrentTuple
(
NdbTransaction* lockTrans
)
Beginning with MySQL Cluster NDB 6.2.3, the following signature is also supported for this method, when using NdbRecord:
NdbOperation *lockCurrentTuple
(
NdbTransaction* takeOverTrans,
const NdbRecord* record,
char* row = 0,
const unsigned char* mask = 0
)
162
Parameters. This method takes a single, optional parameter the transaction that should perform the lock. If this is omitted, the transaction is the current one.
Parameters when using NdbRecord. When using the NdbRecord interface (see Section 2.3.25, The NdbRecord Interface), this
method takes these parameters, as described in the following list:
The transaction (takeOverTrans) that should perform the lock; when using NdbRecord with scans, this parameter is not optional.
The NdbRecord referenced by the scan. This is required, even if no records are being read.
The row from which to read. Set this to NULL if no read is to occur.
The mask pointer is optional. If it is present, then only columns for which the corresponding bit in the mask is set are retrieved by
the scan.
Important
Calling an NdbRecord scan lock takeover on an NdbRecAttr-style scan is not valid, nor is calling an NdbRecAttrstyle scan lock takeover on an NdbRecord-style scan.
Return value. This method returns a pointer to an NdbOperation object, or NULL. (See Section 2.3.15, The NdbOperation
Class.)
2.3.18.2.5. NdbScanOperation::updateCurrentTuple()
Description. This method is used to update the current tuple.
Signature.
NdbOperation* updateCurrentTuple
(
void
)
or
NdbOperation* updateCurrentTuple
(
NdbTransaction* updateTrans
)
Beginning with MySQL Cluster NDB 6.2.3, it is also possible to employ this method, when using NdbRecord with scans, as shown
here:
NdbOperation* updateCurrentTuple
(
NdbTransaction*
takeOverTrans,
const NdbRecord*
record,
const char*
row,
const unsigned char* mask = 0
)
The record (NdbRecord object) referencing the column used for the scan.
The row to read from. If no attributes are to be read, set this equal to NULL.
The mask pointer is optional. If it is present, then only columns for which the corresponding bit in the mask is set are retrieved by
163
the scan.
Return value. This method returns an NdbOperation object or NULL. (See Section 2.3.15, The NdbOperation Class.)
2.3.18.2.6. NdbScanOperation::deleteCurrentTuple()
Description. This method is used to delete the current tuple.
Signature.
int deleteCurrentTuple
(
void
)
or
int deleteCurrentTuple
(
NdbTransaction* takeOverTransaction
)
Beginning with MySQL Cluster NDB 6.2.3, this method's signature when performing NdbRecord-style scans is shown here:
For more information, see Section 2.3.25, The NdbRecord Interface.
Parameters. This method takes a single, optional parameter the transaction that should perform the lock. If this is omitted, the transaction is the current one.
Parameters when using NdbRecord. When used with the NdbRecord interface (beginning with MySQL Cluster NDB 6.2.3), this
method takes two parameters, as shown here:
2.3.18.2.7. NdbScanOperation::restart()
Description. Use this method to restart a scan without changing any of its getValue() calls or search conditions.
Signature.
int restart
(
bool forceSend = false
)
Parameters. Call this method with forceSend set to true in order to force the transaction to be sent.
Return value. 0 on success, -1 on failure.
2.3.18.2.8. NdbScanOperation::getNdbTransaction()
Description. Gets the NdbTransaction object for this scan. Available beginning with MySQL Cluster NDB 6.2.17 and MySQL
Cluster NDB 6.3.19.
Signature.
NdbTransaction* getNdbTransaction
(
void
) const
164
Parameters. None.
Return value. A pointer to an NdbTransaction object. See Section 2.3.19, The NdbTransaction Class.
2.3.18.2.9. NdbScanOperation::getPruned()
Description. This method is used to determine whether or not a given scan operation has been pruned to a single partition. For scans
defined using NdbRecord, this method can be called before or after the scan is executed. For scans not defined using NdbRecord,
getPruned() is valid only after the scan has been executed.
Signature.
bool getPruned
(
void
) const
Parameters. None.
Return value. TRUE, if the scan is pruned to a single table partition.
getNdbOperation()
getNdbScanOperation()
getNdbIndexOperation()
getNdbIndexScanOperation()
Calling one of these methods defines the operation. Several operations can be defined on the same NdbTransaction object, in
which case they are executed in parallel. When all operations are defined, the execute() method sends them to the NDB kernel
for execution.
The execute() method returns when the NDB kernel has completed execution of all operations previously defined.
Important
All allocated operations should be properly defined before calling the execute() method.
NdbTransaction::Commit: Executes any remaining operation and then commits the complete transaction.
NdbOperation::AbortOnError: Any error causes the transaction to be aborted. This is the default behavior.
165
NdbOperation::AO_IgnoreError: The transaction continues to be executed even if one or more of the operations
defined for that transaction fails.
Note
In MySQL 5.1.15 and earlier, these values were NdbTransaction::AbortOnError and NdbTransaction::AO_IgnoreError.
Methods. The following table lists the public methods of this class and the purpose or use of each method:
Method
Purpose / Use
getNdbOperation()
Gets an NdbOperation
getNdbScanOperation()
Gets an NdbScanOperation
getNdbIndexScanOperation()
Gets an NdbIndexScanOperation
getNdbIndexOperation()
Gets an NdbIndexOperation
execute
Executes a transaction
refresh()
close()
Closes a transaction
getGCI()
getTransactionId()
commitStatus()
getNdbError()
getNdbErrorOperation()
getNdbErrorLine()
Gets the line number where the most recent error occurred
getNextCompletedOperation()
Gets operations that have been executed; used for finding errors
readTuple()
insertTuple()
updateTuple()
writeTuple()
deleteTuple()
scanTable()
scanIndex()
Note
The methods readTuple(), insertTuple(), updateTuple(), writeTuple(), deleteTuple(), scanTable(), and scanIndex() require the use of NdbRecord, which is available beginning with MySQL Cluster NDB
6.2.3.
These methods were updated in MySQL Cluster NDB 6.2.15 and NDB 6.3.15, but remain backward-compatible with their
older versions.
For detailed descriptions, signatures, and examples of use for each of these methods, see Section 2.3.19.2, NdbTransaction Methods.
Types. NdbTransaction defines 3 public types as shown in the following table:
Type
Purpose / Use
AbortOption
CommitStatusType
ExecType
For a discussion of each of these types, along with its possible values, see Section 2.3.19.1, NdbTransaction Types.
Class diagram. This diagram shows all the available methods and enumerated types of the ... class:
Value
Description
AbortOnError
AO_IgnoreOnError
Important
Beginning with MySQL Cluster NDB 6.2.0, this type belongs to the NdbOperation class and its possible values and
default behavior have changed. NDB API application code written against previous versions of MySQL Cluster that refers
explicitly to NdbTransaction::AbortOption values must be modified to work with MySQL Cluster NDB 6.2.0 or
later.
In particular, this effects the use of NdbTransaction::execute() in MySQL Cluster NDB 6.2.0 and later. See Section 2.3.15.1.1, The NdbOperation::AbortOption Type, and Section 2.3.19.2.5, NdbTransaction::execute(), for more information.
Description
NotStarted
Started
Committed
Aborted
NeedAbort
The transaction has encountered an error, but has not yet been aborted.
A transaction's commit status ca be read using the commitStatus() method. See Section 2.3.19.2.10, NdbTransaction::commitStatus().
Description
NoCommit
Commit
Rollback
2.3.19.2.1. NdbTransaction::getNdbOperation()
Description. This method is used to create an NdbOperation associated with a given table.
Note
All operations within the same transaction must be initialised with this method. Operations must be defined before they are
executed.
168
Signature.
NdbOperation* getNdbOperation
(
const NdbDictionary::Table* table
)
Parameters. The Table object on which the operation is to be performed. See Section 2.3.21, The Table Class.
Return value. A pointer to the new NdbOperation. See Section 2.3.15, The NdbOperation Class.
2.3.19.2.2. NdbTransaction::getNdbScanOperation()
Description. This method is used to create an NdbScanOperation associated with a given table.
Note
All scan operations within the same transaction must be initialised with this method. Operations must be defined before
they are executed.
Signature.
NdbScanOperation* getNdbScanOperation
(
const NdbDictionary::Table* table
)
Parameters. The Table object on which the operation is to be performed. See Section 2.3.21, The Table Class.
Return value. A pointer to the new NdbScanOperation. See Section 2.3.18, The NdbScanOperation Class.
2.3.19.2.3. NdbTransaction::getNdbIndexScanOperation()
Description. This method is used to create an NdbIndexScanOperation associated with a given table.
Note
All index scan operations within the same transaction must be initialised with this method. Operations must be defined before they are executed.
Signature.
NdbIndexScanOperation* getNdbIndexScanOperation
(
const NdbDictionary::Index* index
)
Parameters. The Index object on which the operation is to be performed. See Section 2.3.5, The Index Class.
Return value. A pointer to the new NdbIndexScanOperation. See Section 2.3.13, The NdbIndexScanOperation Class.
2.3.19.2.4. NdbTransaction::getNdbIndexOperation()
Description. This method is used to create an NdbIndexOperation associated with a given table.
Note
All index operations within the same transaction must be initialised with this method. Operations must be defined before
they are executed.
Signature.
NdbIndexOperation* getNdbIndexOperation
(
const NdbDictionary::Index* index
)
169
Parameters. The Index object on which the operation is to be performed. See Section 2.3.5, The Index Class.
Return value. A pointer to the new NdbIndexOperation. See Section 2.3.12, The NdbIndexOperation Class.
2.3.19.2.5. NdbTransaction::execute()
Description. This method is used to execute a transaction.
Signature.
int execute
(
ExecType execType,
NdbOperation::AbortOption abortOption = NdbOperation::DefaultAbortOption,
int force = 0
)
The execution type (ExecType value); see Section 2.3.19.1.3, The NdbTransaction::ExecType Type, for more information and possible values.
Note
Prior to MySQL Cluster NDB 6.2.0, abortOption was of type NdbTransaction::AbortOption; the AbortOption type became a member of NdbOperation in MySQL Cluster NDB 6.2.0), and its default value was NdbTransaction::AbortOnError. See Section 2.3.15.1.1, The NdbOperation::AbortOption Type, for more
information.
Also beginning with MySQL Cluster NDB 6.2.0, errors arising from this method are found with NdbOperation::getNdbError() rather than NdbTransaction::getNdbError(). See Section 2.3.15.2.5, NdbOperation::getNdbError(), for more information.
A force parameter, which determines when operations should be sent to the NDB Kernel:
define operations...
myTransaction = myNdb->startTransaction();
if(myTransaction->getNdbError().classification == NdbError:NoDataFound)
170
{
cout << "No records found." << endl;
// ...
}
myNdb->closeTransaction(myTransaction);
2.3.19.2.6. NdbTransaction::refresh()
Description. This method updates the transaction's timeout counter, and thus avoids aborting due to transaction timeout.
Note
It is not advisable to take a lock on a record and maintain it for a extended time since this can impact other transactions.
Signature.
int refresh
(
void
)
Parameters. None.
Return value. 0 on success, -1 on failure.
2.3.19.2.7. NdbTransaction::close()
Description. This method closes a transaction. It is equivalent to calling Ndb::closeTransaction() (see Section 2.3.8.1.9,
Ndb::closeTransaction()).
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 close
(
void
)
Parameters. None.
Return value. None.
2.3.19.2.8. NdbTransaction::getGCI()
Description. This method retrieves the transaction's global checkpoint ID (GCI).
Each committed transaction belongs to a GCI. The log for the committed transaction is saved on disk when a global checkpoint occurs.
By comparing the GCI of a transaction with the value of the latest GCI restored in a restarted NDB Cluster, you can determine whether
or not the transaction was restored.
Note
Whether or not the global checkpoint with this GCI has been saved on disk cannot be determined by this method.
Important
The GCI for a scan transaction is undefined, since no updates are performed in scan transactions.
Signature.
int getGCI
171
(
void
)
Parameters. None.
Return value. The transaction's GCI, or -1 if none is available.
Note
No GCI is available until execute() has been called with ExecType::Commit.
2.3.19.2.9. NdbTransaction::getTransactionId()
Description. This method is used to obtain the transaction ID.
Signature.
Uint64 getTransactionId
(
void
)
Parameters. None.
Return value. The transaction ID, as an unsigned 64-bit integer.
2.3.19.2.10. NdbTransaction::commitStatus()
Description. This method gets the transaction's commit status.
Signature.
CommitStatusType commitStatus
(
void
)
Parameters. None.
Return value. The commit status of the transaction, a CommitStatusType value. See Section 2.3.19.1.2, The NdbTransaction::CommitStatusType Type.
2.3.19.2.11. NdbTransaction::getNdbError()
Description. This method is used to obtain the most recent error (NdbError).
Signature.
const NdbError& getNdbError
(
void
) const
Parameters. None.
Return value. A reference to an NdbError object. See Section 2.3.31, The NdbError Structure.
Note
For additional information about handling errors in transactions, see Section 1.3.2.3.5, Error Handling.
2.3.19.2.12. NdbTransaction::getNdbErrorOperation()
Description. This method retrieves the operation that caused an error.
172
Tip
To obtain more information about the actual error, use the NdbOperation::getNdbError() method of the NdbOperation object returned by getNdbErrorOperation(). (See Section 2.3.15.2.5, NdbOperation::getNdbError().)
Signature.
NdbOperation* getNdbErrorOperation
(
void
)
Parameters. None.
Return value. A pointer to an NdbOperation.
Note
For additional information about handling errors in transactions, see Section 1.3.2.3.5, Error Handling.
2.3.19.2.13. NdbTransaction::getNdbErrorLine()
Description. This method return the line number where the most recent error occurred.
Signature.
int getNdbErrorLine
(
void
)
Parameters. None.
Return value. The line number of the most recent error.
Note
For additional information about handling errors in transactions, see Section 1.3.2.3.5, Error Handling.
2.3.19.2.14. NdbTransaction::getNextCompletedOperation()
Description. This method is used to retrieve a transaction's completed operations. It is typically used to fetch all operations belonging
to a given transaction to check for errors.
NdbTransaction::getNextCompletedOperation(NULL) returns the transaction's first NdbOperation object; NdbTransaction::getNextCompletedOperation(myOp) returns the NdbOperation object defined after NdbOperation
myOp.
Important
This method should only be used after the transaction has been executed, but before the transaction has been closed.
Signature.
const NdbOperation* getNextCompletedOperation
(
const NdbOperation* op
) const
Parameters. This method requires a single parameter op, which is an operation (NdbOperation object), or NULL.
Return value. The operation following op, or the first operation defined for the transaction if getNextCompletedOperation()
was called using NULL.
2.3.19.2.15. NdbTransaction::readTuple()
173
key_rec is a pointer to an NdbRecord for either a table or an index. If on a table, then the operation uses a primary key; if on an
index, then the operation uses a unique key. In either case, the key_rec must include all columns of the key.
The key_row passed to this method defines the primary or unique key of the affected tuple, and must remain valid until execute() is called.
lock_mode specifies the lock mode in effect for the operation. See Section 2.3.15.1.3, The NdbOperation::LockMode
Type, for permitted values and other information.
result_mask defines a subset of attributes to read. Only if mask[attrId >> 3] & (1<<(attrId & 7)) is set is the
column affected. The mask is copied, and so need not remain valid after the method call returns.
OperationOptions (opts) can be used to provide more finely-grained control of operation definitions. An OperationOptions structure is passed with flags indicating which operation definition options are present. Not all operation types support all
operation options; the options supported for each type of operation are shown in the following table:
readTuple()
insertTuple()
updateTuple()
writeTuple()
deleteTuple()
The optional sizeOfOptions parameter is used to allow this interface to be backwards compatible with previous definitions of
the OperationOptions structure. If an unusual size is detected by the interface implementation, it can use this to determine how
to interpret the passed OperationOptions structure. To enable this functionality, the caller should pass
sizeof(NdbOperation::OperationOptions) for the value of this argument.
Return value. A pointer to the NdbOperation representing this read operation (this can be used to check for errors).
Old version. Prior to MySQL Cluster NDB 6.2.15 and 6.3.15, this method was defined as shown here:
NdbOperation* readTuple
(
const NdbRecord* key_rec,
const char* key_row,
const NdbRecord* result_rec,
char* result_row,
NdbOperation::LockMode lock_mode = NdbOperation::LM_Read,
const unsigned char* result_mask = 0
174
Parameters (old version). Prior to MySQL Cluster NDB 6.2.15 and 6.3.15, this method took the following parameters:
key_rec is a pointer to an NdbRecord for either a table or an index. If on a table, then the operation uses a primary key; if on an
index, then the operation uses a unique key. In either case, the key_rec must include all columns of the key.
The key_row passed to this method defines the primary or unique key of the affected tuple, and must remain valid until execute() is called.
lock_mode specifies the lock mode in effect for the operation. See Section 2.3.15.1.3, The NdbOperation::LockMode
Type, for permitted values and other information.
result_mask defines a subset of attributes to read. Only if mask[attrId >> 3] & (1<<(attrId & 7)) is set is the
column affected. The mask is copied, and so need not remain valid after the method call returns.
Return value. The NdbOperation representing this operation (this can be used to check for errors).
2.3.19.2.16. NdbTransaction::insertTuple()
Description. Inserts a tuple using NdbRecord.
Signature.
const NdbOperation* insertTuple
(
const NdbRecord* key_rec,
const char* key_row,
const NdbRecord* attr_rec,
const char* attr_row,
const unsigned char* mask = 0,
const NdbOperation::OperationOptions* opts = 0,
Uint32 sizeOfOptions = 0
)
const NdbOperation* insertTuple
(
const NdbRecord* combined_rec,
const char* combined_row,
const unsigned char* mask = 0,
const NdbOperation::OperationOptions* opts = 0,
Uint32 sizeOfOptions = 0
)
OperationOptions (opts) can be used to provide more finely-grained control of operation definitions. An OperationOptions structure is passed with flags indicating which operation definition options are present. Not all operation types support all
operation options; for the options supported by each type of operation, see Section 2.3.19.2.15, NdbTransaction::readTuple().
The optional sizeOfOptions parameter is used to allow this interface to be backwards compatible with previous definitions of
the OperationOptions structure. If an unusual size is detected by the interface implementation, it can use this to determine how
175
to interpret the passed OperationOptions structure. To enable this functionality, the caller should pass
sizeof(NdbOperation::OperationOptions) for the value of this argument.
This method can also be called using a single NdbRecord pointer and single char pointer (combined_rec, combined_row)
where the single NdbRecord represents record and attribute and data.
Return value. A const pointer to the NdbOperation representing this insert operation.
Old version. Prior to MySQL Cluster NDB 6.2.15 and 6.3.15, this method was defined as follows:
NdbOperation* insertTuple
(
const NdbRecord* record,
const char* row,
const unsigned char* mask = 0
)
Parameters (old version). Prior to MySQL Cluster NDB 6.2.15 and 6.3.15, insertTuple() took the following parameters:
Return Value (old version). Prior to MySQL Cluster NDB 6.2.15 and 6.3.15, this method returned a pointer to the NdbOperation
representing the insert operation.
2.3.19.2.17. NdbTransaction::updateTuple()
Description. Updates a tuple using an NdbRecord object.
Signature.
const NdbOperation* updateTuple
(
const NdbRecord* key_rec,
const char* key_row,
const NdbRecord* attr_rec,
const char* attr_row,
const unsigned char* mask = 0,
const NdbOperation::OperationOptions* opts = 0,
Uint32 sizeOfOptions = 0
)
key_rec is a pointer to an NdbRecord for either a table or an index. If on a table, then the operation uses a primary key; if on an
index, then the operation uses a unique key. In either case, the key_rec must include all columns of the key.
The key_row passed to this method defines the primary or unique key of the affected tuple, and must remain valid until execute() is called.
Note
For unique index operations, the attr_rec must refer to the underlying table of the index, not to the index itself.
The mask, if not NULL, defines a subset of attributes to be updated. The mask is copied, and so does not need to remain valid after
the call to this method returns.
176
Return value. The NdbOperation representing this operation (can be used to check for errors).
Old version. Prior to MySQL Cluster NDB 6.2.15 and 6.3.15, this method was defined as follows:
NdbOperation* updateTuple
(
const NdbRecord* key_rec,
const char* key_row,
const NdbRecord* attr_rec,
const char* attr_row,
const unsigned char* mask = 0
)
Parameters (old version). Prior to MySQL Cluster NDB 6.2.15 and 6.3.15, updateTuple() took the following parameters:
key_rec is a pointer to an NdbRecord for either a table or an index. If on a table, then the operation uses a primary key; if on an
index, then the operation uses a unique key. In either case, the key_rec must include all columns of the key.
The key_row passed to this method defines the primary or unique key of the affected tuple, and must remain valid until execute() is called.
Note
For unique index operations, the attr_rec must refer to the underlying table of the index, not to the index itself.
The mask, if not NULL, defines a subset of attributes to be updated. The mask is copied, and so does not need to remain valid after
the call to this method returns.
Return Value (old version). Prior to MySQL Cluster NDB 6.2.15 and 6.3.15, this method returned a pointer to the NdbOperation
representing this operation (which could be used to check for errors).
2.3.19.2.18. NdbTransaction::writeTuple()
Description. This method is used with NdbRecord to write a tuple of data.
Signature.
const NdbOperation* writeTuple
(
const NdbRecord* key_rec,
const char* key_row,
const NdbRecord* attr_rec,
const char* attr_row,
const unsigned char* mask = 0,
const NdbOperation::OperationOptions* opts = 0,
Uint32 sizeOfOptions = 0
)
key_rec is a pointer to an NdbRecord for either a table or an index. If on a table, then the operation uses a primary key; if on an
index, then the operation uses a unique key. In either case, the key_rec must include all columns of the key.
The key_row passed to this method defines the primary or unique key of the tuple to be written, and must remain valid until execute() is called.
Note
For unique index operations, the attr_rec must refer to the underlying table of the index, not to the index itself.
177
The mask, if not NULL, defines a subset of attributes to be written. The mask is copied, and so does not need to remain valid after
the call to this method returns.
OperationOptions (opts) can be used to provide more finely-grained control of operation definitions. An OperationOptions structure is passed with flags indicating which operation definition options are present. Not all operation types support all
operation options; for the options supported by each type of operation, see Section 2.3.19.2.15, NdbTransaction::readTuple().
The optional sizeOfOptions parameter is used to allow this interface to be backwards compatible with previous definitions of
the OperationOptions structure. If an unusual size is detected by the interface implementation, it can use this to determine how
to interpret the passed OperationOptions structure. To enable this functionality, the caller should pass
sizeof(NdbOperation::OperationOptions) for the value of this argument.
Return value. A const pointer to the NdbOperation representing this write operation. The operation can be checked for errors if
and as necessary.
Old version. Prior to MySQL Cluster NDB 6.2.15 and 6.3.15, this method was defined as shown here:
NdbOperation* writeTuple
(
const NdbRecord* key_rec,
const char* key_row,
const NdbRecord* attr_rec,
const char* attr_row,
const unsigned char* mask = 0
)
Parameters (old version). Prior to MySQL Cluster NDB 6.2.15 and 6.3.15, this method took the following parameters:
key_rec is a pointer to an NdbRecord for either a table or an index. If on a table, then the operation uses a primary key; if on an
index, then the operation uses a unique key. In either case, the key_rec must include all columns of the key.
The key_row passed to this method defines the primary or unique key of the tuple to be written, and must remain valid until execute() is called.
Note
For unique index operations, the attr_rec must refer to the underlying table of the index, not to the index itself.
The mask, if not NULL, defines a subset of attributes to be written. The mask is copied, and so does not need to remain valid after
the call to this method returns.
Return Value (old version). Prior to MySQL Cluster NDB 6.2.15 and 6.3.15, this method returned a pointer to the NdbOperation
representing this write operation. The operation could be checked for errors if and as necessary.
2.3.19.2.19. NdbTransaction::deleteTuple()
Description. Deletes a tuple using NdbRecord.
Signature.
const NdbOperation* deleteTuple
(
const NdbRecord* key_rec,
const char* key_row,
const NdbRecord* result_rec,
char* result_row,
const unsigned char* result_mask = 0,
const NdbOperation::OperationOptions* opts = 0,
Uint32 sizeOfOptions = 0
)
178
key_rec is a pointer to an NdbRecord for either a table or an index. If on a table, then the delete operation uses a primary key; if
on an index, then the operation uses a unique key. In either case, the key_rec must include all columns of the key.
The key_row passed to this method defines the primary or unique key of the tuple to be deleted, and must remain valid until execute() is called.
The result_mask, if not NULL, defines a subset of attributes to be written. The mask is copied, and so does not need to remain
valid after the call to this method returns.
OperationOptions (opts) can be used to provide more finely-grained control of operation definitions. An OperationOptions structure is passed with flags indicating which operation definition options are present. Not all operation types support all
operation options; for the options supported by each type of operation, see Section 2.3.19.2.15, NdbTransaction::readTuple().
The optional sizeOfOptions parameter is used to allow this interface to be backwards compatible with previous definitions of
the OperationOptions structure. If an unusual size is detected by the interface implementation, it can use this to determine how
to interpret the passed OperationOptions structure. To enable this functionality, the caller should pass
sizeof(NdbOperation::OperationOptions) for the value of this argument.
Return value. A const pointer to the NdbOperation representing this write operation. The operation can be checked for errors if
necessary.
Old version. Prior to MySQL Cluster NDB 6.2.15 and 6.3.15, this method was defined as shown here:
NdbOperation* deleteTuple
(
const NdbRecord* key_rec,
const char* key_row
)
Parameters (old version). Prior to MySQL Cluster NDB 6.2.15 and 6.3.15, this method took the following parameters:
key_rec is a pointer to an NdbRecord for either a table or an index. If on a table, then the delete operation uses a primary key; if
on an index, then the operation uses a unique key. In either case, the key_rec must include all columns of the key.
The key_row passed to this method defines the primary or unique key of the tuple to be deleted, and must remain valid until execute() is called.
Return Value (old version). A pointer to the NdbOperation representing this write operation. The operation can be checked for errors if necessary.
2.3.19.2.20. NdbTransaction::scanTable()
Description. This method performs a table scan, using an NdbRecord object to read out column data.
Signature.
NdbScanOperation* scanTable
(
const NdbRecord* result_record,
NdbOperation::LockMode lock_mode = NdbOperation::LM_Read,
const unsigned char* result_mask = 0,
Uint32 scan_flags = 0,
Uint32 parallel = 0,
Uint32 batch = 0
)
A pointer to an NdbRecord for storing the result. This result_record must remain valid until after the execute() call has
179
been made.
The lock_mode in effect for the operation. See Section 2.3.15.1.3, The NdbOperation::LockMode Type, for allowable
values and other information.
The result_mask pointer is optional. If it is present, only columns for which the corresponding bit (by attribute ID order) in
result_mask is set will be retrieved in the scan. The result_mask is copied internally, so in contrast to result_record
need not be valid when execute() is invoked.
scan_flags can be used to impose ordering and sorting conditions for scans. See Section 2.3.18.1, The NdbScanOperation::ScanFlag Type, for a list of permitted values.
The parallel argument is the desired parallelism, or 0 for maximum parallelism (receiving rows from all fragments in parallel),
which is the default.
Return value. A pointer to the NdbScanOperation representing this scan. The operation can be checked for errors if necessary.
2.3.19.2.21. NdbTransaction::scanIndex()
Description. This method is used to perform an index scan of a table, using NdbRecord. The scan may optionally be ordered.
Signature.
NdbIndexScanOperation* scanIndex
(
const NdbRecord* key_record,
const char* low_key,
Uint32 low_key_count,
bool low_inclusive,
const char* high_key,
Uint32 high_key_count,
bool high_inclusive,
const NdbRecord* result_record,
NdbOperation::LockMode lock_mode = NdbOperation::LM_Read,
const unsigned char* result_mask = 0,
Uint32 scan_flags = 0,
Uint32 parallel = 0,
Uint32 batch = 0
)
Note
For multi-range scans, the low_key and high_key pointers must be unique. In other words, it is not permissible to reuse the same row buffer for several different range bounds within a single scan. However, it is permissible to use the same
row pointer as low_key and high_key in order to specify an equals bound; it is also permissible to reuse the rows after
the scanIndex() method returns thatis, they need not remain valid until execute() time (unlike the NdbRecord
pointers).
Parameters. This method takes the following parameters:
The key_record describes the index to be scanned. It must be a key record on the index; that is, the columns which it specifies
must include all of the key columns of the index. It must be created from the index to be scanned, and not from the underlying table.
low_key_count determines the number of columns used for the lower bound when specifying a partial prefix for the scan.
low_inclusive determines whether the lower bound is considered as a >= or > relation.
high_key_count determines the number of columns used for the higher bound when specifying a partial prefix for the scan.
high_inclusive determines whether the lower bound is considered as a <= or < relation.
180
The result_record describes the rows to be returned from the scan. For an ordered index scan, result_record be a key record on the index; that is, the columns which it specifies must include all of the key columns of the index. This is because the index
key is needed for merge sorting of the scans returned from each fragment.
The lock_mode for the scan must be one of the values specified in Section 2.3.15.1.3, The NdbOperation::LockMode
Type.
The result_mask pointer is optional. If it is present, only columns for which the corresponding bit (by attribute ID order) in
result_mask is set will be retrieved in the scan. The result_mask is copied internally, so in contrast to result_record
need not be valid when execute() is invoked.
scan_flags can be used to impose ordering and sorting conditions for scans. See Section 2.3.18.1, The NdbScanOperation::ScanFlag Type, for a list of permitted values.
The parallel argument is the desired parallelism, or 0 for maximum parallelism (receiving rows from all fragments in parallel),
which is the default.
Return value. The current NdbIndexScanOperation, which can be used for error checking.
Purpose / Use
getObjectStatus()
getObjectVersion()
getObjectId()
Gets an object's ID
For a detailed discussion of each of these methods, see Section 2.3.20.2, Object Methods.
Types. These are the public types of the Object class:
Type
Purpose / Use
FragmentType
State
Status
Store
Type
The object's type (what sort of table, index, or other database object the Object represents)
For a discussion of each of these types, along with its possible values, see Section 2.3.20.1, Object Class Enumerated Types.
This diagram shows all public members of the Object class:
181
For a visual representation of Object's subclasses, see Section 2.3.10, The NdbDictionary Class.
Description
FragUndefined
FragAllMedium
FragAllLarge
Description
StateUndefined
Undefined
StateOffline
StateBuilding
StateDropping
StateOnline
Online, usable
182
Value
Description
StateBackup
StateBroken
Description
New
The object exists only in memory, and has not yet been created in the NDB kernel
Changed
The object has been modified in memory, and must be committed in the NDB Kernel
for changes to take effect
Retrieved
The object exists, and has been read into main memory from the NDB Kernel
Invalid
Altered
The table has been altered in the NDB kernel, but is still available for use
Description
StoreUndefined
StoreTemporary
StorePermanent
Description
TypeUndefined
Undefined
SystemTable
System table
UserTable
UniqueHashIndex
OrderedIndex
HashIndexTrigger
IndexTrigger
SubscriptionTrigger
ReadOnlyConstraint
Trigger (internal)
Tablespace
Tablespace
183
Value
Description
LogfileGroup
Logfile group
Datafile
Datafile
Undofile
Undofile
Important
All 3 of these methods are pure virtual methods, and are reimplemented in the Table, Index, and Event subclasses
where needed. See Section 2.3.21, The Table Class, Section 2.3.5, The Index Class, and Section 2.3.4, The
Event Class.
2.3.20.2.1. Object::getObjectStatus()
Description. This method retrieves the status of the object for which it is invoked.
Signature.
virtual Status getObjectStatus
(
void
) const
Parameters. None.
Return value. The current Status of the Object. For possible values, see Section 2.3.20.1.3, The Object::Status Type.
2.3.20.2.2. Object::getObjectVersion()
Description. The method gets the current version of the object.
Signature.
virtual int getObjectVersion
(
void
) const
Parameters. None.
Return value. The object's version number, an integer.
2.3.20.2.3. Object::getObjectId()
Description. This method retrieves the object's ID.
Signature.
virtual int getObjectId
(
void
) const
Parameters. None.
Return value. The object ID, an integer.
Important
It is possible using the NDB API to create tables independently of the MySQL server. However, it is usually not advisable
to do so, since tables created in this fashion cannot be seen by the MySQL server. Similarly, it is possible using Table
methods to modify existing tables, but these changes (except for renaming tables) are not visible to MySQL.
Calculating Table Sizes. When calculating the data storage one should add the size of all attributes (each attribute consuming a minimum of 4 bytes) and well as 12 bytes overhead. Variable size attributes have a size of 12 bytes plus the actual data storage parts, with
an additional overhead based on the size of the variable part. For example, consider a table with 5 attributes: one 64-bit attribute, one
32-bit attribute, two 16-bit attributes, and one array of 64 8-bit attributes. The amount of memory consumed per record by this table is
the sum of the following:
8 bytes for the two 16-bit attributes, each of these taking up 4 bytes due to right-alignment
12 bytes overhead
This totals 96 bytes per record. In addition, you should assume an overhead of about 2% for the allocation of page headers and wasted
space. Thus, 1 million records should consume 96 MB, and the additional page header and other overhead comes to approximately 2
MB. Rounding up yields 100 MB.
Methods. The following table lists the public methods of this class and the purpose or use of each method:
Method
Purpose / Use
Table()
Class constructor
~Table()
Destructor
getName()
getTableId()
getColumn()
getLogging()
getFragmentType()
getKValue()
getMinLoadFactor()
getMaxLoadFactor()
getNoOfColumns()
getNoOfPrimaryKeys()
getPrimaryKey()
equal()
getFrmData()
getFrmLength()
getFragmentData()
getFragmentDataLen()
getRangeListData()
getRangeListDataLen()
Method
Purpose / Use
getTablespaceData()
getTablespaceDataLen()
getLinearFlag()
Gets the current setting for the table's linear hashing flag
getFragmentCount()
getFragmentNodes()
getTablespace()
getTablespaceNames()
getObjectType()
getObjectStatus()
getObjectVersion()
getObjectId()
getMaxRows()
Gets the maximum number of rows that this table may contain
getDefaultNoPartitionsFlag()
getRowGCIIndicator()
getRowChecksumIndicator()
setName()
addColumn()
setLogging()
setLinearFlag()
setFragmentCount()
setFragmentType()
setKValue()
setMinLoadFactor()
setMaxLoadFactor()
setTablespace()
setStatusInvalid()
setMaxRows()
setDefaultNoPartitionsFlag()
Toggles whether the default number of partitions should be used for the
table
setFrm()
setFragmentData()
Sets the fragment ID, node group ID, and fragment state
setTablespaceNames()
setTablespaceData()
setRangeListData()
setObjectType()
setRowGCIIndicator()
setRowChecksumIndicator()
aggregate()
validate()
hasDefaultValues()
For detailed descriptions, signatures, and examples of use for each of these methods, see Section 2.3.21.2, Table Methods.
Types. The Table class defines a single public type SingleUserMode. For more information, see Section 2.3.21.1, The Ta186
ble::SingleUserMode Type.
Class diagram. This diagram shows all the available methods of the Table class:
187
188
Description
SingleUserModeLocked
SingleUserModeReadOnly
SingleUserModeReadWrite
Note
The assignment (=) operator is overloaded for this class, so that it always performs a deep copy.
Warning
As with other database objects, Table object creation and attribute changes to existing tables done using the NDB API
are not visible from MySQL. For example, if you add a new column to a table using Table::addColumn(), MySQL
will not see the new column. The only exception to this rule with regard to tables is that you can change the name of an existing table using Table::setName().
Important
Tables created in the NDB API using this method are not accessible from MySQL.
Signature. New instance:
Table
(
const char* name = ""
)
Copy constructor:
Table
(
const Table& table
)
Parameters. For a new instance, the name of the table to be created. For a copy, a reference to the table to be copied.
Return value. A Table object.
Destructor.
virtual ~Table()
2.3.21.2.2. Table:getName()
Description. Gets the name of a table.
Signature.
const char* getName
189
(
void
) const
Parameters. None.
Return value. The name of the table (a string).
2.3.21.2.3. Table::getTableId()
Description. This method gets a table's ID.
Signature.
int getTableId
(
void
) const
Parameters. None.
Return value. An integer.
2.3.21.2.4. Table::getColumn()
Description. This method is used to obtain a column definition, given either the index or the name of the column.
Signature. Using the column ID:
Column* getColumn
(
const int AttributeId
)
Parameters. Either of: the column's index in the table (as would be returned by the column's getColumnNo() method), or the name
of the column.
Return value. A pointer to the column with the specified index or name. If there is no such column, then this method returns NULL.
2.3.21.2.5. Table::getLogging()
Description. This class is used to check whether a table is logged to disk that is, whether it is permanent or temporary.
Signature.
bool getLogging
(
void
) const
Parameters. None.
Return value. Returns a Boolean value. If this method returns true, then full checkpointing and logging are done on the table. If
false, then the table is a temporary table and is not logged to disk; in the event of a system restart the table still exists and retains its
definition, but it will be empty. The default logging value is true.
2.3.21.2.6. Table::getFragmentType()
Description. This method gets the table's fragmentation type.
Signature.
190
FragmentType getFragmentType
(
void
) const
Parameters. None.
Return value. A FragmentType value, as defined in Section 2.3.20.1.1, The Object::FragmentType Type.
2.3.21.2.7. Table::getKValue()
Description. This method gets the KValue, a hashing parameter which is currently restricted to the value 6. In a future release, it may
become feasible to set this parameter to other values.
Signature.
int getKValue
(
void
) const
Parameters. None.
Return value. An integer (currently always 6).
2.3.21.2.8. Table::getMinLoadFactor()
Description. This method gets the value of the load factor when reduction of the hash table begins. This should always be less than the
value returned by getMaxLoadFactor().
Signature.
int getMinLoadFactor
(
void
) const
Parameters. None.
Return value. An integer (actually, a percentage expressed as an integer see Section 2.3.21.2.9, Table::getMaxLoadFactor()).
2.3.21.2.9. Table::getMaxLoadFactor()
Description. This method returns the load factor (a hashing parameter) when splitting of the containers in the local hash tables begins.
Signature.
int getMaxLoadFactor
(
void
) const
Parameters. None.
Return value. An integer whose maximum value is 100. When the maximum value is returned, this means that memory usage is optimised. Smaller values indicate that less data is stored in each container, which means that keys are found more quickly; however, this
also consumes more memory.
2.3.21.2.10. Table::getNoOfCOlumns()
Description. This method is used to obtain the number of columns in a table.
Signature.
int getNoOfColumns
(
void
191
) const
Parameters. None.
Return value. An integer the number of columns in the table.
2.3.21.2.11. Table::getNoOfPrimaryKeys()
Description. This method finds the number of primary key columns in the table.
Signature.
int getNoOfPrimaryKeys
(
void
) const
Parameters. None.
Return value. An integer.
2.3.21.2.12. Table::getPrimaryKey()
Description. This method is used to obtain the name of the table's primary key.
Signature.
const char* getPrimaryKey
(
int no
) const
Parameters. None.
Return value. The name of the primary key, a string (character pointer).
2.3.21.2.13. Table::equal()
Description. This method is used to compare one instance of Table with another.
Signature.
bool equal
(
const Table& table
) const
Parameters. A reference to the Table object with which the current instance is to be compared.
Return value. true if the two tables are the same, otherwise false.
2.3.21.2.14. Table::getFrmData()
Description. The the data from the .FRM file associated with the table.
Signature.
const void* getFrmData
(
void
) const
Parameters. None.
Return value. A pointer to the .FRM data.
192
2.3.21.2.15. Table::getFrmLength()
Description. Gets the length of the table's .FRM file data, in bytes.
Signature.
Uint32 getFrmLength
(
void
) const
Parameters. None.
Return value. The length of the .FRM file data (unsigned 32-bit integer).
2.3.21.2.16. Table::getFragmentData()
Description. This method gets the table's fragment data (ID, state, and node group).
Signature.
const void* getFragmentData
(
void
) const
Parameters. None.
Return value. A pointer to the data to be read.
2.3.21.2.17. Table::getFragmentDataLen()
Description. Gets the length of the table fragment data to be read, in bytes.
Signature.
Uint32 getFragmentDataLen
(
void
) const
Parameters. None.
Return value. The number of bytes to be read, as an unsigned 32-bit integer.
2.3.21.2.18. Table::getRangeListData()
Description. This method gets the range or list data associated with the table.
Signature.
const void* getRangeListData
(
void
) const
Parameters. None.
Return value. A pointer to the data.
2.3.21.2.19. Table::getRangeListDataLen()
Description. This method gets the size of the table's range or list array.
Signature.
Uint32 getRangeListDataLen
193
(
void
) const
Parameters. None.
Return value. The length of the list or range array, as an integer.
2.3.21.2.20. Table::getTablespaceData()
Description. This method gets the table's tablespace data (ID and version).
Signature.
const void* getTablespaceData
(
void
) const
Parameters. None.
Return value. A pointer to the data.
2.3.21.2.21. Table::getTablespaceDataLen()
Description. This method is used to get the length of the table's tablespace data.
Signature.
Uint32 getTablespaceDataLen
(
void
) const
Parameters. None.
Return value. The length of the data, as a 32-bit unsigned integer.
2.3.21.2.22. Table::getLinearFlag()
Description. This method retrieves the value of the table's linear hashing flag.
Signature.
bool getLinearFlag
(
void
) const
Parameters. None.
Return value. true if the flag is set, and false if it is not.
2.3.21.2.23. Table::getFragmentCount()
Description. This method gets the number of fragments in the table.
Signature.
Uint32 getFragmentCount
(
void
) const
Parameters. None.
Return value. The number of table fragments, as a 32-bit unsigned integer.
194
2.3.21.2.24. Table::getFragmentNodes()
Description. This method retrieves a list of nodes storing a given fragment.
Signature.
Uint32 getFragmentNodes
(
Uint32 fragmentId,
Uint32* nodeIdArrayPtr,
Uint32 arraySize
) const
nodeIdArrayPtr: Pointer to an array of node IDs of the nodes containing this fragment.
Note
Normally, the primary fragment is entry 0 in this array.
arraySize: The size of the array containing the node IDs. If this is less than the number of fragments, then only the first arraySize entries are written to this array.
Return value. A return value of 0 indicates an error; otherwise, this is the number of table fragments, as a 32-bit unsigned integer.
This method was added in MySQL Cluster NDB 6.2.19, MySQL Cluster NDB 6.3.33, MySQL Cluster NDB 7.0.14, and MySQL
Cluster NDB 7.1.2.
2.3.21.2.25. Table::getTablespace()
Description. This method is used in two ways: to obtain the name of the tablespace to which this table is assigned; to verify that a given tablespace is the one being used by this table.
Signatures. To obtain the name of the tablespace:
const char* getTablespace
(
void
) const
To determine whether the tablespace is the one indicated by the given ID and version:
bool getTablespace
(
Uint32* id
= 0,
Uint32* version = 0
) const
Parameters. The number and types of parameters depend on how this method is being used:
When used to obtain the name of the tablespace in use by the table, it is called without any arguments.
When used to determine whether the given tablespace is the one being used by this table, then getTablespace() takes two parameters:
1.
When getTablespace() is called without any arguments, it returns a Tablespace object instance. See Section 2.3.22, The
Tablespace Class, for more information.
When called with two arguments, it returns true if the tablespace is the same as the one having the ID and version indicated; otherwise, it returns false.
2.3.21.2.26. Table::getObjectType()
Description. This method is used to obtain the table's type that is, its Object::Type value
Signature.
Object::Type getObjectType
(
void
) const
Parameters. None.
Return value. Returns a Type value. For possible values, see Section 2.3.20.1.5, The Object::Type Type.
2.3.21.2.27. Table::getObjectStatus()
Description. This method gets the table's status that is, its Object::Status.
Signature.
virtual Object::Status getObjectStatus
(
void
) const
Parameters. None.
Return value. A Status value. For possible values, see Section 2.3.20.1.3, The Object::Status Type.
2.3.21.2.28. Table::getObjectVersion()
Description. This method gets the table's object version.
Signature.
virtual int getObjectVersion
(
void
) const
Parameters. None.
Return value. The table's object version, as an integer.
2.3.21.2.29. Table::getMaxRows()
Description. This method gets the maximum number of rows that the table can hold. This is used for calculating the number of partitions.
Signature.
Uint64 getMaxRows
(
void
) const
Parameters. None.
Return value. The maximum number of table rows, as a 64-bit unsigned integer.
196
2.3.21.2.30. Table::getDefaultNoPartitionsFlag()
Description. This method is used to find out whether the default number of partitions is used for the table.
Signature.
Uint32 getDefaultNoPartitionsFlag
(
void
) const
Parameters. None.
Return value. A 32-bit unsigned integer.
2.3.21.2.31. Table::getObjectId()
Description. This method gets the table's object ID.
Signature.
virtual int getObjectId
(
void
) const
Parameters. None.
Return value. The object ID is returned as an integer.
2.3.21.2.32. Table::getTablespaceNames()
Description. This method gets a pointer to the names of the tablespaces used in the table fragments.
Signature.
const void* getTablespaceNames
(
void
)
Parameters. None.
Return value. A pointer to the tablespace name data.
2.3.21.2.33. Table::getTablespaceNamesLen()
Description. This method gets the length of the tablespace name data returned by getTablespaceNames(). (See Section 2.3.21.2.32, Table::getTablespaceNames().)
Signature.
Uint32 getTablespaceNamesLen
(
void
) const
Parameters. None.
Return value. The length of the names data, in bytes, as a 32-but unsigned integer.
2.3.21.2.34. Table::getRowGCIIndicator()
Description.
Signature.
197
bool getRowGCIIndicator
(
void
) const
Parameters. None.
Return value. A true/false value.
2.3.21.2.35. Table::getRowChecksumIndicator()
Description.
Signature.
bool getRowChecksumIndicator
(
void
) const
Parameters. None.
Return value. A true/false value.
2.3.21.2.36. Table::setName()
Description. This method sets the name of the table.
Note
This is the only set*() method of Table whose effects are visible to MySQL.
Signature.
void setName
(
const char* name
)
2.3.21.2.37. Table::addColumn()
Description. Adds a column to a table.
Signature.
void addColumn
(
const Column& column
)
2.3.21.2.38. Table::setLogging()
Description. Toggles the table's logging state. See Section 2.3.21.2.5, Table::getLogging().
Signature.
void setLogging
(
bool enable
)
198
Parameters. If enable is true, then logging for this table is enabled; if it is false, then logging is disabled.
Return value. None.
2.3.21.2.39. Table::setLinearFlag()
Description.
Signature.
void setLinearFlag
(
Uint32 flag
)
2.3.21.2.40. Table::setFragmentCount()
Description. Sets the number of table fragments.
Signature.
void setFragmentCount
(
Uint32 count
)
2.3.21.2.41. Table::setFragmentType()
Description. This method sets the table's fragmentation type.
Signature.
void setFragmentType
(
FragmentType fragmentType
)
Parameters. This method takes one argument, a FragmentType value. See Section 2.3.20.1.1, The Object::FragmentType
Type, for more information.
Return value. None.
2.3.21.2.42. Table::setKValue()
Description. This sets the KValue, a hashing parameter.
Signature.
void setKValue
(
int kValue
)
Parameters. kValue is an integer. Currently the only permitted value is 6. In a future version this may become a variable parameter.
Return value. None.
2.3.21.2.43. Table::setMinLoadFactor()
199
Description. This method sets the minimum load factor when reduction of the hash table begins.
Signature.
void setMinLoadFactor
(
int min
)
Parameters. This method takes a single parameter min, an integer representation of a percentage (for example, 45 represents 45 percent). For more information, see Section 2.3.21.2.8, Table::getMinLoadFactor().
Return value. None.
2.3.21.2.44. Table::setMaxLoadFactor()
Description. This method sets the maximum load factor when splitting the containers in the local hash tables.
Signature.
void setMaxLoadFactor
(
int max
)
Parameters. This method takes a single parameter max, an integer representation of a percentage (for example, 45 represents 45 percent). For more information, see Section 2.3.21.2.9, Table::getMaxLoadFactor().
Caution
This should never be greater than the minimum load factor.
Return value. None.
2.3.21.2.45. Table::setTablespace()
Description. This method sets the tablespace for the table.
Signatures. Using the name of the tablespace:
void setTablespace
(
const char* name
)
Parameters. This method can be called with a single argument of either of two types:
1.
2.
2.3.21.2.46. Table::setMaxRows()
Description. This method sets the maximum number of rows that can be held by the table.
Signature.
200
void setMaxRows
(
Uint64 maxRows
)
Parameters. maxRows is a 64-bit unsigned integer that represents the maximum number of rows to be held in the table.
Return value. None.
2.3.21.2.47. Table::setDefaultNoPartitionsFlag()
Description. This method sets an indicator that determines whether the default number of partitions is used for the table.
Signature.
void setDefaultNoPartitionsFlag
(
Uint32 indicator
) const
Parameters. This method takes a single argument indicator, a 32-bit unsigned integer.
Return value. None.
2.3.21.2.48. Table::setFrm()
Description. This method is used to write data to this table's .FRM file.
Signature.
void setFrm
(
const void* data,
Uint32
len
)
2.3.21.2.49. Table::setFragmentData()
Description. This method writes an array of fragment information containing the following information:
Fragment ID
Node group ID
Fragment State
Signature.
void setFragmentData
(
const void* data,
Uint32
len
)
201
2.3.21.2.50. Table::setTablespaceNames()
Description. Sets the names of the tablespaces used by the table fragments.
Signature.
void setTablespaceNames
(
const void* data
Uint32
len
)
2.3.21.2.51. Table::setTablespaceData()
Description. This method sets the tablespace information for each fragment, and includes a tablespace ID and a tablespace version.
Signature.
void setTablespaceData
(
const void* data,
Uint32
len
)
2.3.21.2.52. Table::setRangeListData()
Description. This method sets an array containing information that maps range values and list values to fragments. This is essentially a
sorted map consisting of fragment ID/value pairs. For range partitions there is one pair per fragment. For list partitions it could be any
number of pairs, but at least as many pairs as there are fragments.
Signature.
void setRangeListData
(
const void* data,
Uint32
len
)
202
2.3.21.2.53. Table::setObjectType()
Description. This method sets the table's object type.
Signature.
void setObjectType
(
Object::Type type
)
Parameters. The desired object type. This must be one of the Type values listed in Section 2.3.20.1.5, The Object::Type
Type.
Return value. None.
2.3.21.2.54. Table::setRowGCIIndicator()
Description. Documentation not yet available
Signature.
void setRowGCIIndicator
(
bool value
) const
2.3.21.2.55. Table::setRowChecksumIndicator()
Description. Documentation not yet available
Signature.
void setRowChecksumIndicator
(
bool value
) const
2.3.21.2.56. Table::setStatusInvalid()
Description. Forces the table's status to be invalidated.
Signature.
void setStatusInvalid
(
void
) const
Parameters. None.
Return value. None.
203
2.3.21.2.57. Table::aggregate()
Description. This method computes aggregate data for the table. It is required in order for aggregate methods such as getNoOfPrimaryKeys() to work properly before the table has been created and retrieved via getTable().
Note
This method was added in MySQL 5.1.12. (See Bug#21690.)
Signature.
int aggregate
(
struct NdbError& error
)
2.3.21.2.58. Table::validate()
Description. This method validates the definition for a new table prior to its being created, and executes the Table::aggregate()
method, as well as performing additional checks. validate() is called automatically when a table is created or retrieved. For this
reason, it is usually not necessary to call aggregate() or validate() directly.
Warning
Even after the validate() method is called, there may still exist errors which can be detected only by the NDB kernel
when the table is actually created.
Note
This method was added in MySQL 5.1.12. (See Bug#21690.)
Signature.
int validate
(
struct NdbError& error
)
2.3.21.2.59. Table::hasDefaultValues()
Description. Used to determine whether the table has any columns that are defined with non-NULL default values.
This method was added in MySQL Cluster NDB 7.1.0.
To read and write default column values, use Column::getDefaultValue() and Column::setDefaultValue().
Signature.
bool hasDefaultValues
(
void
) const
Parameters. None.
Return value. TRUE if the table has any non-NULL columns with default values; otherwise, FALSE.
204
Note
In MySQL 5.1, only unindexed column data can be stored on disk. Indexes and indexes columns continue to be stored in
memory as with previous versions of MySQL Cluster.
Versions of MySQL prior to 5.1 do not support Disk Data storage and so do not support tablespaces; thus the Tablespace class is unavailable for NDB API applications written against these MySQL versions.
Methods. The following table lists the public methods of this class and the purpose or use of each method:
Method
Purpose / Use
Tablespace()
Class constructor
~Tablespace()
getName()
getExtentSize()
getAutoGrowSpecification()
getDefaultLogfileGroup()
getDefaultLogfileGroupId()
getObjectStatus()
Used to obtain the Object::Status of the Tablespace instance for which it is called
getObjectVersion()
getObjectId()
setName()
setExtentSize()
setAutoGrowSpecification()
setDefaultLogfileGroup()
For detailed descriptions, signatures, and examples of use for each of these methods, see Section 2.3.22.1, Tablespace Methods.
Types. The Tablespace class defines no public types of its own; however, two of its methods make use of the AutoGrowSpecification data structure. Information about this structure can be found in Section 2.3.26, The AutoGrowSpecification Structure.
Class diagram. This diagram shows all the available methods and enumerated types of the Tablespace class:
205
Note
The NdbDictionary::Dictionary class also supplies methods for creating and dropping tablespaces. See Section 2.3.3, The Dictionary Class.
Signatures. New instance:
Tablespace
(
void
)
Copy constructor:
Tablespace
(
const Tablespace& tablespace
)
Parameters. New instance: None. Copy constructor: a reference tablespace to an existing Tablespace instance.
Return value. A Tablespace object.
Destructor. The class defines a virtual destructor ~Tablespace() which takes no arguments and returns no value.
2.3.22.1.2. Tablespace::getName()
Description. This method retrieves the name of the tablespace.
Signature.
const char* getName
206
(
void
) const
Parameters. None.
Return value. The name of the tablespace, a string value (as a character pointer).
2.3.22.1.3. Tablespace::getExtentSize()
Description. This method is used to retrieve the extent size that is the size of the memory allocation units used by the tablespace.
Note
The same extent size is used for all datafiles contained in a given tablespace.
Signature.
Uint32 getExtentSize
(
void
) const
Parameters. None.
Return value. The tablespace's extent size in bytes, as an unsigned 32-bit integer.
2.3.22.1.4. Tablespace::getAutoGrowSpecification()
Description.
Signature.
const AutoGrowSpecification& getAutoGrowSpecification
(
void
) const
Parameters. None.
Return value. A reference to the structure which describes the tablespace auto-grow characteristics for details, see Section 2.3.26,
The AutoGrowSpecification Structure.
2.3.22.1.5. Tablespace::getDefaultLogfileGroup()
Description. This method retrieves the name of the tablespace's default logfile group.
Note
Alternatively, you may wish to obtain the ID of the default logfile group see Section 2.3.22.1.6, Tablespace::getDefaultLogfileGroupId().
Signature.
const char* getDefaultLogfileGroup
(
void
) const
Parameters. None.
Return value. The name of the logfile group (string value as character pointer).
2.3.22.1.6. Tablespace::getDefaultLogfileGroupId()
Description. This method retrieves the ID of the tablespace's default logfile group.
207
Note
You can also obtain directly the name of the default logfile group rather than its ID see Section 2.3.22.1.5, Tablespace::getDefaultLogfileGroup().
Signature.
Uint32 getDefaultLogfileGroupId
(
void
) const
Parameters. None.
Return value. The ID of the logfile group, as an unsigned 32-bit integer.
2.3.22.1.7. Tablespace::getObjectStatus()
Description. This method is used to retrieve the object status of a tablespace.
Signature.
virtual Object::Status getObjectStatus
(
void
) const
Parameters. None.
Return value. An Object::Status value see Section 2.3.20.1.3, The Object::Status Type, for details.
2.3.22.1.8. Tablespace::getObjectVersion()
Description. This method gets the tablespace object version.
Signature.
virtual int getObjectVersion
(
void
) const
Parameters. None.
Return value. The object version, as an integer.
2.3.22.1.9. Tablespace::getObjectId()
Description. This method retrieves the tablespace's object ID.
Signature.
virtual int getObjectId
(
void
) const
Parameters. None.
Return value. The object ID, as an integer.
2.3.22.1.10. Tablespace::setName()
Description. This method sets the name of the tablespace.
Signature.
208
void setName
(
const char* name
) const
2.3.22.1.11. Tablespace::setExtentSize()
Description. This method sets the tablespace's extent size.
Signature.
void setExtentSize
(
Uint32 size
)
2.3.22.1.12. Tablespace::setAutoGrowSpecification()
Description. This method is used to set the auto-grow characteristics of the tablespace.
Signature.
void setAutoGrowSpecification
(
const AutoGrowSpecification& autoGrowSpec
)
Parameters. This method takes a single parameter, an AutoGrowSpecification data structure. See Section 2.3.26, The
AutoGrowSpecification Structure.
Return value. None.
2.3.22.1.13. Tablespace::setDefaultLogfileGroup()
Description. This method is used to set a tablespace's default logfile group.
Signature. This method can be called in two different ways. The first of these uses the name of the logfile group, as shown here:
void setDefaultLogfileGroup
(
const char* name
)
Note
There is no method for setting a logfile group as the default for a tablespace by referencing the logfile group's ID. (In other
words, there is no set*() method corresponding to getDefaultLogfileGroupId().)
Parameters. Either the name of the logfile group to be assigned to the tablespace, or a reference lGroup to this logfile group.
Return value. None.
The section discusses the Undofile class and its public methods.
Parent class. NdbDictionary
Child classes. None
Description. The Undofile class models a Cluster Disk Data undofile, which stores data used for rolling back transactions.
Note
In MySQL 5.1, only unindexed column data can be stored on disk. Indexes and indexes columns continue to be stored in
memory as with previous versions of MySQL Cluster.
Versions of MySQL prior to 5.1 do not support Disk Data storage and so do not support undofile; thus the Undofile
class is unavailable for NDB API applications written against these MySQL versions.
Methods. The following table lists the public methods of this class and the purpose or use of each method:
Method
Purpose / Use
Undofile()
Class constructor
~Undofile()
Virtual destructor
getPath()
getSize()
getLogfileGroup()
Gets the name of the logfile group to which the undofile belongs
getLogfileGroupId()
getNode()
getFileNo()
getObjectStatus()
getObjectVersion()
getObjectId()
setPath()
setSize()
setLogfileGroup()
Sets the undofile's logfile group using the name of the logfile group or a reference to
the corresponding LogfileGroup object
setNode()
For detailed descriptions, signatures, and examples of use for each of these methods, see Section 2.3.23.1, Undofile Methods.
Types. The Undofile class defines no public types.
Class diagram. This diagram shows all the available methods of the Undofile class:
210
Copy constructor:
Undofile
(
const Undofile& undoFile
)
Parameters. New instance: None. The copy constructor takes a single argument a reference to the Undofile object to be copied.
Return value. An Undofile object.
Destructor. The class defines a virtual destructor which takes no arguments and has the return type void.
2.3.23.1.2. Undofile::getPath()
Description. This method retrieves the path matching the location of the undofile on the data node's file system.
211
Signature.
const char* getPath
(
void
) const
Parameters. None.
Return value. The file system path, a string (as a character pointer).
2.3.23.1.3. Undofile::getSize()
Description. This method gets the size of the undofile in bytes.
Signature.
Uint64 getSize
(
void
) const
Parameters. None.
Return value. The size in bytes of the undofile, as an unsigned 64-bit integer.
2.3.23.1.4. Undofile::getLogfileGroup()
Description. This method retrieves the name of the logfile group to which the undofile belongs.
Signature.
const char* getLogfileGroup
(
void
) const
Parameters. None.
Return value. The name of the logfile group, a string value (as a character pointer).
2.3.23.1.5. Undofile::getLogfileGroupId()
Description. This method retrieves the ID of the logfile group to which the undofile belongs.
Note
It is also possible to obtain the name of the logfile group directly. See Section 2.3.23.1.4, Undofile::getLogfileGroup()
Signature.
Uint32 getLogfileGroupId
(
void
) const
Parameters. None.
Return value. The ID of the logfile group, as an unsigned 32-bit integer.
2.3.23.1.6. Undofile::getNode()
Description. This method is used to retrieve the node ID of the node where the undofile is located.
Signature.
212
Uint32 getNode
(
void
) const
Parameters. None.
Return value. The node ID, as an unsigned 32-bit integer.
2.3.23.1.7. Undofile::getFileNo()
Description. The getFileNo() method gets the number of the undofile in the logfile group to which it belongs.
Signature.
Uint32 getFileNo
(
void
) const
Parameters. None.
Return value. The number of the undofile, as an unsigned 32-bit integer.
2.3.23.1.8. Undofile::getObjectStatus()
Description. This method is used to retrieve the object status of an undofile.
Signature.
virtual Object::Status getObjectStatus
(
void
) const
Parameters. None.
Return value. An Object::Status value see Section 2.3.20.1.3, The Object::Status Type, for details.
2.3.23.1.9. Undofile::getObjectVersion()
Description. This method gets the undofile's object version.
Signature.
virtual int getObjectVersion
(
void
) const
Parameters. None.
Return value. The object version, as an integer.
2.3.23.1.10. Undofile::getObjectId()
Description. This method retrieves the undofile's object ID.
Signature.
virtual int getObjectId
(
void
) const
Parameters. None.
213
2.3.23.1.11. Undofile::setPath()
Description. This method is used to set the file system path of the undofile on the data node where it resides.
Signature.
void setPath
(
const char* path
)
2.3.23.1.12. Undofile::setSize()
Description. Sets the size of the undofile in bytes.
Signature.
void setSize
(
Uint64 size
)
Parameters. The intended size of the undofile in bytes, as an unsigned 64-bit integer.
Return value. None.
2.3.23.1.13. Undofile::setLogfileGroup()
Description. Given either a name or an object reference to a logfile group, the setLogfileGroup() method assigns the undofile to
that logfile group.
Signature. Using a logfile group name:
void setLogfileGroup
(
const char* name
)
Parameters. The name of the logfile group (a character pointer), or a reference to a LogfileGroup instance.
Return value. None.
2.3.23.1.14. Undofile::setNode()
Description. Sets the node on which the logfile group is to reside.
Signature.
void setNode
(
Uint32 nodeId
)
Parameters. The nodeId of the data node where the undofile is to be placed; this is an unsigned 32-bit integer.
214
Note
There is no restriction against instantiating multiple Ndb_cluster_connection objects representing connections to
different management servers in a single application, nor against using these for creating multiple instances of the Ndb
class. Such Ndb_cluster_connection objects (and the Ndb instances based on them) are not required even to connect to the same cluster.
For example, it is entirely possible to perform application-level partitioning of data in such a manner that data meeting one
set of criteria are handed off to one cluster via an Ndb object that makes use of an Ndb_cluster_connection object representing a connection to that cluster, while data not meeting those criteria (or perhaps a different set of criteria)
can be sent to a different cluster through a different instance of Ndb that makes use of an Ndb_cluster_connection
pointing to the second cluster.
It is possible to extend this scenario to develop a single application that accesses an arbitrary number of clusters. However,
in doing so, the following conditions and requirements must be kept in mind:
A cluster management server (ndb_mgmd) can connect to one and only one cluster without being restarted and reconfigured, as it must read the data telling it which data nodes make up the cluster from a configuration file (config.ini).
An Ndb_cluster_connection object belongs to a single management server whose host name or IP address is
used in instantiating this object (passed as the connectstring argument to its constructor); once the object is created, it cannot be used to initiate a connection to a different management server.
(See Section 2.3.24.1.1, Ndb_cluster_connection Class Constructor.)
An Ndb object making use of this connection (Ndb_cluster_connection) cannot be re-used to connect to a different cluster management server (and thus to a different collection of data nodes making up a cluster). Any given instance of Ndb is bound to a specific Ndb_cluster_connection when created, and that
Ndb_cluster_connection is in turn bound to a single and unique management server when it is instantiated.
(See Section 2.3.8.1.1, Ndb Class Constructor.)
The bindings described above persist for the lifetimes of the Ndb and Ndb_cluster_connection objects in question.
Therefore, it is imperative in designing and implementing any application that accesses multiple clusters in a single session, that a separate set of Ndb_cluster_connection and Ndb objects be instantiated for connecting to each cluster
management server, and that no confusion arises as to which of these is used to access which MySQL Cluster.
It is also important to keep in mind that no direct sharing of data or data nodes between different clusters is possible. A
data node can belong to one and only one cluster, and any movement of data between clusters must be accomplished on
the application level.
For examples demonstrating how connections to two different clusters can be made and used in a single application, see
Section 2.4.2, Using Synchronous Transactions and Multiple Clusters, and Section 2.4.8, Event Handling with Multiple
Clusters.
Methods. The following table lists the public methods of this class and the purpose or use of each method:
215
Method
Purpose / Use
Ndb_cluster_connection()
set_name()
set_timeout()
connect()
wait_until_ready()
set_optimized_node_selection()
lock_ndb_objects()
Disables the creation of new Ndb objects.
unlock_ndb_objects()
Enables the creation of new Ndb objects.
get_next_ndb_object()
Used to iterate through multiple Ndb objects.
set_auto_reconnect()
Enables or disables auto-reconnection of API nodes using this
Ndb_cluster_connection.
get_auto_reconnect()
Gets the auto-reconnection setting for API nodes using this
Ndb_cluster_connection.
For detailed descriptions, signatures, and examples of use for each of these methods, see Section 2.3.24.1,
Ndb_cluster_connection Methods.
Class diagram. This diagram shows all the available methods of the Ndb_cluster_connection class:
216
Parameters. This method requires a single parameter a connectstring pointing to the location of the management server.
Return value. An instance of Ndb_cluster_connection.
2.3.24.1.2. Ndb_cluster_connection::set_name()
Description. Sets a name for the connection. If the name is specified, it is reported in the cluster log.
Signature.
void set_name
(
const char* name
)
2.3.24.1.3. Ndb_cluster_connection::set_timeout()
Description. Used to set a timeout for the connection, to limit the amount of time that we may block when connecting.
This method is actually a wrapper for the function ndb_mgm_set_timeout(). For more information, see Section 3.2.4.11,
ndb_mgm_set_timeout().
Signature.
int set_timeout
(
int timeout_ms
)
Parameters. The length of the timeout, in milliseconds (timeout_ms). Currently, only multiples of 1000 are accepted.
Return value. 0 on success; any other value indicates failure.
2.3.24.1.4. Ndb_cluster_connection::connect()
Description. This method connects to a cluster management server.
Signature.
int connect
(
int retries = 0,
int delay
= 1,
int verbose = 0
)
Parameters. This method takes three parameters, all of which are optional:
retries specifies the number of times to retry the connection in the event of failure. The default value (0) means that no additional attempts to connect will be made in the event of failure; a negative value for retries results in the connection attempt being repeated indefinitely.
The delay represents the number of seconds between reconnect attempts; the default is 1 second.
verbose indicates whether the method should output a report of its progress, with 1 causing this reporting to be enabled; the default is 0 (reporting disabled).
Return value. This method returns an int, which can have one of the following 3 values:
217
2.3.24.1.5. Ndb_cluster_connection::wait_until_ready()
Description. This method waits until the requested connection with one or more data nodes is successful.
Signature.
int wait_until_ready
(
int timeoutBefore,
int timeoutAfter
)
timeoutBefore determines the number of seconds to wait until the first live node is detected. If this amount of time is exceeded with no live nodes detected, then the method immediately returns a negative value.
timeoutAfter determines the number of seconds to wait after the first live node is detected for all nodes to become active. If
this amount of time is exceeded without all nodes becoming active, then the method immediately returns a value greater than zero.
> 0: At least one node is live (however, it is not known whether all nodes are live).
2.3.24.1.6. Ndb_cluster_connection::set_optimized_node_selection()
Description. This method can be used to override the connect() method's default behavior as regards which node should be connected to first.
Signature.
void set_optimized_node_selection
(
int value
)
2.3.24.1.7. ndb_cluster_connection::get_next_ndb_object()
Description. This method is used to iterate over a set of Ndb objects, retrieving them one at a time.
Signature.
const Ndb* get_next_ndb_object
(
const Ndb* p
)
218
Parameters. This method takes a single parameter, a pointer to the last Ndb object to have been retrieved or NULL.
Return value. Returns the next Ndb object, or NULL if no more Ndb objects are available.
Iterating over Ndb objects. To retrieve all existing Ndb objects:
1.
Invoke the lock_ndb_objects() method. This prevents the creation of any new instances of Ndb until the unlock_ndb_objects() method is called.
2.
Retrieve the first available Ndb object by passing NULL to get_next_ndb_object(). You can retrieve the second Ndb object by passing the pointer retrieved by the first call to the next get_next_ndb_object() call, and so on. When a pointer to
the last available Ndb instance is used, the method returns NULL.
3.
After you have retrieved all desired Ndb objects, you should re-enable Ndb object creation by calling the unlock_ndb_objects() method.
2.3.24.1.8. ndb_cluster_connection::lock_ndb_objects()
Description. Calling this method prevents the creation of new instances of the Ndb class. This method must be called prior to iterating
over multiple Ndb objects using get_next_ndb_object().
Signature.
void lock_ndb_objects
(
void
)
Parameters. None.
Return value. None.
This method was added in MySQL Cluster NDB 6.1.4. For more information, see Section 2.3.24.1.7,
ndb_cluster_connection::get_next_ndb_object().
2.3.24.1.9. ndb_cluster_connection::unlock_ndb_objects()
Description. This method undoes the effects of the lock_ndb_objects() method, making it possible to create new instances of
Ndb. unlock_ndb_objects() should be called after you have finished retrieving Ndb objects using the
get_next_ndb_object() method.
Signature.
void unlock_ndb_objects
(
void
)
Parameters. None.
Return value. None.
For more information, see Section 2.3.24.1.7, ndb_cluster_connection::get_next_ndb_object().
2.3.24.1.10. Ndb_cluster_connection::set_auto_reconnect()
Description. Prior to MySQL Cluster NDB 6.3.26 and MySQL Cluster NDB 7.0.7, an API node that was disconnected from the cluster
tried to re-use an existing Ndb_cluster_connection object when reconnecting; however, it was discovered that allowing this also
sometimes allowed multiple API nodes to try to connect using the same node ID during a restart of the cluster. (Bug#45921) Beginning
with these versions, API nodes are instead forced to use a new connection object, unless this behavior is overridden by setting
AutoReconnect = 1 in the config.ini file or calling this method with 1 as the input value. Calling the method with 0 for the
219
value has the same effect as setting the AutoReconnect configuration parameter (also introduced in those MySQL Cluster versions)
to 0; that is, API nodes are forced to create new connections.
Important
When called, this method overrides any setting for AutoReconnect made in the config.ini file.
For information about AutoReconnect, see Defining SQL and Other API Nodes in a MySQL Cluster.
Signature.
void set_auto_reconnect
(
int value
)
Parameters. A value of 0 or 1 which determines API node reconnection behavior. 0 forces API nodes to use new connections
(Ndb_cluster_connection objects); 1 allows API nodes to re-use existing connections to the cluster.
Return value. None.
2.3.24.1.11. Ndb_cluster_connection::get_auto_reconnect()
Description. Introduced in MySQL Cluster NDB 6.3.26 and MySQL CLuster NDB 7.0.7, this method retrieves the current AutoReconnect setting for a given Ndb_cluster_connection. For more detailed information, see Section 2.3.24.1.10,
Ndb_cluster_connection::set_auto_reconnect().
Signature.
int get_auto_reconnect
(
void
)
Parameters. None.
Return value. An integer value 0 or 1, corresponding to the current AutoReconnect setting in effect for for this connection. 0
forces API nodes to use new connections to the cluster; 1 allows API nodes to re-use existing connections.
The same NdbRecord can be used simultaneously in multiple operations, transactions, and threads.
An NdbRecord can be created in NDB API programs by calling the createRecord() method of the NdbDictionary class. In
addition, a number of NDB API methods have additional declarations in MySQL Cluster NDB 6.2.3 and later MySQL Cluster releases
that allow the programmer to leverage NdbRecord:
NdbScanOperation::nextResult()
NdbScanOperation::lockCurrentTuple()
220
NdbScanOperation::updateCurrentTuple()
NdbScanOperation::deleteCurrentTuple()
Dictionary::createRecord()
Dictionary::releaseRecord()
NdbTransaction::readTuple()
NdbTransaction::insertTuple()
NdbTransaction::updateTuple()
NdbTransaction::writeTuple()
NdbTransaction::deleteTuple()
NdbTransaction::scanTable()
NdbTransaction::scanIndex()
In addition, new members of NdbIndexScanOperation and NdbDictionary are introduced in MySQL Cluster NDB 6.2.3 for
use with NdbRecord scans:
NdbIndexScanOperation::IndexBound is a structure used to describe index scan bounds. See Section 2.3.29, The IndexBound Structure.
NdbDictionary::RecordSpecification is a structure used to specify columns and range offsets. See Section 2.3.34,
The RecordSpecification Structure.
Beginning with MySQL Cluster NDB 6.3.24 and MySQL Cluster NDB 7.0.4, you can also use NdbRecord in conjunction with the
new Ndb::PartitionSpec structure to perform scans that take advantage of partition pruning, by means of a new variant of NdbIndexScanOperation::setBound(). For more information, see Section 2.3.13.2.5, NdbIndexScanOperation::setBound, and Section 2.3.33, The PartitionSpec Structure.
The purpose and use of each member can be found in the following table:
Name
Description
min_free
???
max_size
???
221
Name
Description
file_size
???
filename_pattern
???
Type
Initial Value
Description
id
unsigned int
The object's ID
type
Object::Type
Object::TypeUndefined
The object's type see Section 2.3.20.1.5, The Object::Type Type for possible values
state
Object::State
Object::StateUndefined
The object's state see Section 2.3.20.1.2, The Object::State Type for possible values
store
Object::Store
Object::StoreUndefined
database
char*
schema
char*
name
char*
Note
For a graphical representation of this class and its parent-child relationships, see Section 2.3.3, The Dictionary
Class.
222
The individual members are described in more detail in the following table:
Name
Type
Description
column
const NdbDictionary::Column*
appStorage
void*
Important
It is the caller's responsibility to ensure that
recAttr
Memory pointed to by appStorage is not reused or freed until after the execute() call returns.
NdbRecAttr*
Important
Currently, blob reads cannot be specified using GetValueSpec.
For more information, see Section 2.3.25, The NdbRecord Interface.
Type
Description
low_key
const char*
Row containing lower bound for scan (or NULL for scan from the
start).
low_key_count
Uint32
Name
Type
Description
low_inclusive
bool
high_key
const char*
Row containing upper bound for scan (or NULL for scan to the
end).
high_key_count
Uint32
high_inclusive
bool
range_no
Uint32
Type
Initial Value
Description
ptr
const void*
none
len
unsigned
none
Error status: This describes the impact of an error on the application, and reflects what the application should do when the error is
encountered.
The error status is described by a value of the Status type. See Section 2.3.31.1.1, The NdbError::Status Type, for possible Status values and how they should be interpreted.
2.
3.
Error code: This is an NDB API internal error code which uniquely identifies the error.
Important
224
It is not recommended to write application programs which are dependent on specific error codes. Instead, applications
should check error status and classification. More information about errors can also be obtained by checking error messages and (when available) error detail messages. However like error codes these error messages and error detail
messages are subject to change.
A listing of current error codes, broken down by classification, is provided in Section 5.2.2, NDB Error Codes and Messages.
This listing will be updated periodically, or you can check the file storage/ndb/src/ndbapi/ndberror.c in the MySQL
5.1 sources.
4.
MySQL Error code: This is the corresponding MySQL Server error code. MySQL error codes are not discussed in this document;
please see Server Error Codes and Messages, in the MySQL Manual, for information about these.
5.
6.
Error details: This can often provide additional information (not found in the error message) about an error, specific to the circumstances under which the error is encountered. However, it is not available in all cases.
Where not specified, the error detail message is NULL.
Note
This property is deprecated as of MySQL Cluster NDB 6.2.19, MySQL Cluster NDB 6.3.29, and MySQL Cluster NDB
7.0.10. Beginning with these MySQL Cluster releases, for obtaining error details, you should use the
Ndb::getNdbErrorDetail() method instead. See Section 2.3.8.1.16, Ndb::getNdbErrorDetail(), for
more information.
Important
Specific NDB API error codes, messages, and detail messages are subject to change without notice.
Definition. The NdbError structure contains the following members, whose types are as shown here:
Status status
Classification classification
int code
int mysql_code
char* details
Note
details is deprecated as of MySQL Cluster NDB 6.2.19, MySQL Cluster NDB 6.3.29, and MySQL Cluster NDB
7.0.10. Beginning with these MySQL Cluster releases, for obtaining error details, you should use the
225
Status: The error status. See Section 2.3.31.1.1, The NdbError::Status Type.
Classification: The type of error or the logical grouping to which it belongs. See Section 2.3.31.1.2, The NdbError::Classification Type.
Structure Diagram. This diagram shows all the available members and types of the NdbError structure:
Description
Success
TemporaryError
A temporary and usually recoverable error; the application should retry the operation
giving rise to the error
PermanentError
UnknownResult
Note
226
Related information specific to certain error conditions may be found in Section 5.2.3, NDB Error Classifications.
Description
NoError
ApplicationError
NoDataFound
ConstraintViolation
SchemaError
InsufficientSpace
TemporaryResourceError
This type of error is typically encountered when there are too many active transactions.
NodeRecoveryError
This is a temporary failure which was likely caused by a node recovery in progress,
some examples being when information sent between an application and NDB is lost, or
when there is a distribution change.
OverloadError
This type of error is often caused when there is insufficient logfile space.
TimeoutExpired
UnknownResultError
InternalError
FunctionNotImplemented
UnknownErrorCode
This is seen where the NDB error handler cannot determine the correct error code to report.
NodeShutdown
SchemaObjectExists
InternalTemporary
Note
Related information specific to certain error conditions may be found in Section 5.2.2, NDB Error Codes and Messages,
and in Section 5.2.3, NDB Error Classifications.
Note
Most NdbTransaction::*Tuple() methods take a supplementary sizeOfOptions parameter. This is optional,
and is intended to allow the interface implementation to remain backwards compatible with older un-recompiled clients
that may pass an older (smaller) version of the OperationOptions structure. This effect is achieved by passing
sizeof(OperationOptions) into this parameter.
Each option type is marked as present by setting the corresponding bit in optionsPresent. (Only the option types marked in optionsPresent need have sensible data.) All data is copied out of the OperationOptions structure (and any subtended structures) at operation definition time. If no options are required, then NULL may be passed instead.
Members. The makeup of this structure is shown here:
227
The individual members are described in more detail in the following table:
Name
Type
Description
optionsPresent
Uint64
[...]
Flags:
Type of flags.
OO_ABORTOPTION: 0x01
OO_GETVALUE: 0x02
228
Name
Type
Description
OO_SETVALUE: 0x04
OO_PARTITION_ID:
0x08
OO_INTERPRETED: 0x10
OO_ANYVALUE: 0x20
OO_CUSTOMDATA: 0x40
abortOption
AbortOption
extraGetValues
GetValueSpec*
numExtraGetValues
Uint32
extraSetValues
SetValueSpec*
numExtraSetValues
Uint32
partitionId
Uint32
Limit the scan to the partition having this ID; alternatively, you
can supply an Ndb::PartitionSpec here. For index scans,
partitioning information can be supplied for each range.
interpretedCode
const NdbInterpretedCode*
anyValue
Uint32
customData
void*
partitionInfo
const
Ndb::PartitionSpec*
sizeOfPartInfo
Uint32
An array made up of a table's distribution key values for a table with native partitioning.
(MySQL Cluster NDB 7.0.4 and later:) A row in NdbRecord format containing a natively partitioned table's distribution key values.
Attributes. A PartitionSpec has two attributes, a SpecType and a Spec which is a data structure corresponding to that SpecType, as shown in the following table:
SpecType Enumeration
SpecType Value
(Uint32)
Data Structure
Description
PS_NONE
none
No partitioning information is
provided.
PS_USER_DEFINED
UserDefined
229
SpecType Enumeration
SpecType Value
(Uint32)
Data Structure
Description
tioning, a specific partition is identified
by its partition ID.
PS_DISTR_KEY_PART 2
_PTR
KeyPartPtr
KeyRecord
Type
Description
partitionId
Uint32
Type
Description
tableKeyParts
xfrmbuf
void*
xfrmbuflen
Uint32
KeyRecord structure. (MySQL Cluster NDB 7.0.4 and later:) This structure is used when the SpecType is
PS_DISTR_KEY_RECORD.
Attribute
Type
Description
keyRecord
keyRow
const char*
xfrmbuf
void*
xfrmbuflen
Uint32
Definition from Ndb.hpp. Because this is a fairly complex structure, we here provide the original source-code definition of PartitionSpec, as given in storage/ndb/include/ndbapi/Ndb.hpp:
struct PartitionSpec
{
enum SpecType
{
PS_NONE
PS_USER_DEFINED
PS_DISTR_KEY_PART_PTR
= 0,
= 1,
= 2
230
Uint32 partitionId;
} UserDefined;
struct {
const Key_part_ptr* tableKeyParts;
void* xfrmbuf;
Uint32 xfrmbuflen;
} KeyPartPtr;
/* MySQL Cluster NDB 7.0.4 and later: */
struct {
const NdbRecord* keyRecord;
const char* keyRow;
void* xfrmbuf;
Uint32 xfrmbuflen;
} KeyRecord;
};
};
The individual members are described in more detail in the following table:
Name
Type
Description
column
const Column *
offset
Uint32
The offset of data from the beginning of a row. For reading blobs,
the blob handle (NdbBlob*), rather than the actual blob data, is
written into the row. This means that there must be at least
sizeof(NdbBlob*) must be available in the row.
nullbit_byte_offset
Uint32
The offset from the beginning of the row of the byte containing the
NULL bit.
nullbit_bit_in_byte
Uint32
231
Important
nullbit_byte_offset and nullbit_bit_in_byte are not used for non-NULLable columns.
For more information, see Section 2.3.25, The NdbRecord Interface.
232
The individual members are described in more detail in the following table:
Name
Type
Description
optionsPresent
Uint64
[...]
Type:
Type of options.
SO_SCANFLAGS: 0x01
SO_PARALLEL: 0x02
SO_BATCH: 0x04
233
Name
Type
Description
SO_GETVALUE: 0x08
SO_PARTITION_ID:
0x10
SO_INTERPRETED: 0x20
SO_CUSTOMDATA: 0x40
SO_PARTINFO: 0x80
scan_flags
Uint32
Flags controlling scan behavior; see Section 2.3.18.1, The NdbScanOperation::ScanFlag Type, for more information.
parallel
Uint32
batch
Uint32
Batch size for transfers from data nodes to API nodes; 0 (the default) allows this to be selected automatically.
extraGetValues
NdbOperation::GetValueSpec*
Extra values to be read for each row matching the sdcan criteria.
numExtraGetValues
Uint32
partitionId
Uint32
Limit the scan to the partition having this ID; alternatively, you
can supply an Ndb::PartitionSpec here. For index scans,
partitioning information can be supplied for each range.
interpretedCode
const NdbInterpretedCode*
customData
void*
partitionInfo
const
Ndb::PartitionSpec*
sizeOfPartInfo
Uint32
The individual members are described in more detail in the following table:
234
Name
Type
Description
column
const NdbDictionary::Column*
value
void*
Important
Currently, blob values cannot be set using SetValueSpec.
For more information, see Section 2.3.25, The NdbRecord Interface.
235
void
void
void
void
void
void
create_table(MYSQL &);
drop_table(MYSQL &);
do_insert(Ndb &);
do_update(Ndb &);
do_delete(Ndb &);
do_read(Ndb &);
236
237
myOperation->deleteTuple();
myOperation->equal( "ATTR1", 3 );
if (myTransaction->execute(NdbTransaction::Commit) == -1)
APIERROR(myTransaction->getNdbError());
myNdb.closeTransaction(myTransaction);
}
/*****************************
* Read and print all tuples *
*****************************/
static void do_read(Ndb &myNdb)
{
const NdbDictionary::Dictionary* myDict= myNdb.getDictionary();
const NdbDictionary::Table *myTable= myDict->getTable("MYTABLENAME");
if (myTable == NULL)
APIERROR(myDict->getNdbError());
std::cout << "ATTR1 ATTR2" << std::endl;
for (int i = 0; i < 10; i++) {
NdbTransaction *myTransaction= myNdb.startTransaction();
if (myTransaction == NULL) APIERROR(myNdb.getNdbError());
NdbOperation *myOperation= myTransaction->getNdbOperation(myTable);
if (myOperation == NULL) APIERROR(myTransaction->getNdbError());
myOperation->readTuple(NdbOperation::LM_Read);
myOperation->equal("ATTR1", i);
NdbRecAttr *myRecAttr= myOperation->getValue("ATTR2", NULL);
if (myRecAttr == NULL) APIERROR(myTransaction->getNdbError());
if(myTransaction->execute( NdbTransaction::Commit ) == -1)
APIERROR(myTransaction->getNdbError());
if (myTransaction->getNdbError().classification == NdbError::NoDataFound)
if (i == 3)
std::cout << "Detected that deleted tuple doesn't exist!" << std::endl;
else
APIERROR(myTransaction->getNdbError());
if (i != 3) {
printf(" %2d
%2d\n", i, myRecAttr->u_32_value());
}
myNdb.closeTransaction(myTransaction);
}
}
238
*
*/
#include <mysql.h>
#include <NdbApi.hpp>
// Used for cout
#include <stdio.h>
#include <iostream>
static void run_application(MYSQL &, Ndb_cluster_connection &, const char* table, const char* db);
#define PRINT_ERROR(code,msg) \
std::cout << "Error in " << __FILE__ << ", line: " << __LINE__ \
<< ", code: " << code \
<< ", msg: " << msg << "." << std::endl
#define MYSQLERROR(mysql) { \
PRINT_ERROR(mysql_errno(&mysql),mysql_error(&mysql)); \
exit(-1); }
#define APIERROR(error) { \
PRINT_ERROR(error.code,error.message); \
exit(-1); }
the cluster 1
cluster1_connection(connectstring1);
the cluster 2
cluster2_connection(connectstring2);
239
void
void
void
void
void
void
240
241
{
const NdbDictionary::Dictionary* myDict= myNdb.getDictionary();
const NdbDictionary::Table *myTable= myDict->getTable(table);
if (myTable == NULL)
APIERROR(myDict->getNdbError());
std::cout << "ATTR1 ATTR2" << std::endl;
for (int i = 0; i < 10; i++) {
NdbTransaction *myTransaction= myNdb.startTransaction();
if (myTransaction == NULL) APIERROR(myNdb.getNdbError());
NdbOperation *myOperation= myTransaction->getNdbOperation(myTable);
if (myOperation == NULL) APIERROR(myTransaction->getNdbError());
myOperation->readTuple(NdbOperation::LM_Read);
myOperation->equal("ATTR1", i);
NdbRecAttr *myRecAttr= myOperation->getValue("ATTR2", NULL);
if (myRecAttr == NULL) APIERROR(myTransaction->getNdbError());
if(myTransaction->execute( NdbTransaction::Commit ) == -1)
if (i == 3) {
std::cout << "Detected that deleted tuple doesn't exist!" << std::endl;
} else {
APIERROR(myTransaction->getNdbError());
}
if (i != 3) {
printf(" %2d
%2d\n", i, myRecAttr->u_32_value());
}
myNdb.closeTransaction(myTransaction);
}
}
2.
Application errors: These are indicated by APIERROR; they must be handled by the application programmer.
/*
* ndbapi_retries.cpp: Error handling and retrying transactions
*/
#include <mysql.h>
#include <NdbApi.hpp>
// Used for cout
#include <iostream>
// Used for sleep (use your own version of sleep)
#include <unistd.h>
#define TIME_TO_SLEEP_BETWEEN_TRANSACTION_RETRIES 1
#define PRINT_ERROR(code,msg) \
std::cout << "Error in " << __FILE__ << ", line: " << __LINE__ \
<< ", code: " << code \
<< ", msg: " << msg << "." << std::endl
#define MYSQLERROR(mysql) { \
PRINT_ERROR(mysql_errno(&mysql),mysql_error(&mysql)); \
exit(-1); }
//
// APIERROR prints an NdbError object
//
#define APIERROR(error) \
{ std::cout << "API ERROR: " << error.code << " " << error.message \
<< std::endl \
242
<< "
" << "Status: " << error.status \
<< ", Classification: " << error.classification << std::endl\
<< "
" << "File: " << __FILE__ \
<< " (Line: " << __LINE__ << ")" << std::endl \
; \
}
//
// TRANSERROR prints all error info regarding an NdbTransaction
//
#define TRANSERROR(ndbTransaction) \
{ NdbError error = ndbTransaction->getNdbError(); \
std::cout << "TRANS ERROR: " << error.code << " " << error.message \
<< std::endl \
<< "
" << "Status: " << error.status \
<< ", Classification: " << error.classification << std::endl \
<< "
" << "File: " << __FILE__ \
<< " (Line: " << __LINE__ << ")" << std::endl \
; \
printTransactionError(ndbTransaction); \
}
void printTransactionError(NdbTransaction *ndbTransaction) {
const NdbOperation *ndbOp = NULL;
int i=0;
/****************************************************************
* Print NdbError object of every operations in the transaction *
****************************************************************/
while ((ndbOp = ndbTransaction->getNextCompletedOperation(ndbOp)) != NULL) {
NdbError error = ndbOp->getNdbError();
std::cout << "
OPERATION " << i+1 << ": "
<< error.code << " " << error.message << std::endl
<< "
Status: " << error.status
<< ", Classification: " << error.classification << std::endl;
i++;
}
}
//
//
//
//
//
//
//
//
int
Example insert
@param myNdb
@param myTransaction
@param myTable
@param error
@return -1 in case of
}
//
//
//
//
//
int
243
myTransaction->execute(NdbTransaction::Commit)) {
TRANSERROR(myTransaction);
ndberror = myTransaction->getNdbError();
result = -1; // Failure
} else {
result = 1;
// Success
}
/**********************************
* If failure, then analyze error *
**********************************/
if (result == -1) {
switch (ndberror.status) {
case NdbError::Success:
break;
case NdbError::TemporaryError:
std::cout << "Retrying transaction..." << std::endl;
sleep(TIME_TO_SLEEP_BETWEEN_TRANSACTION_RETRIES);
--noOfRetriesLeft;
result = 0;
// No completed transaction yet
break;
case NdbError::UnknownResult:
case NdbError::PermanentError:
std::cout << "No retry of transaction..." << std::endl;
result = -1; // Permanent failure
break;
}
}
/*********************
* Close transaction *
*********************/
if (myTransaction != NULL) {
myNdb->closeTransaction(myTransaction);
}
}
if (result != 1) exit(-1);
return result;
}
/*********************************************************
* Create a table named MYTABLENAME if it does not exist *
*********************************************************/
static void create_table(MYSQL &mysql)
{
if (mysql_query(&mysql,
"CREATE TABLE"
" MYTABLENAME"
"
(ATTR1 INT UNSIGNED NOT NULL PRIMARY KEY,"
"
ATTR2 INT UNSIGNED NOT NULL)"
" ENGINE=NDB"))
MYSQLERROR(mysql);
}
/***********************************
* Drop a table named MYTABLENAME
***********************************/
static void drop_table(MYSQL &mysql)
{
if (mysql_query(&mysql,
"DROP TABLE"
" MYTABLENAME"))
MYSQLERROR(mysql);
}
int main(int argc, char** argv)
{
if (argc != 3)
{
std::cout << "Arguments are <socket mysqld> <connect_string cluster>.\n";
exit(-1);
}
char * mysqld_sock = argv[1];
const char *connectstring = argv[2];
ndb_init();
Ndb_cluster_connection *cluster_connection=
new Ndb_cluster_connection(connectstring); // Object representing the cluster
int r= cluster_connection->connect(5 /* retries
*/,
3 /* delay between retries */,
1 /* verbose
*/);
if (r > 0)
{
std::cout
<< "Cluster connect failed, possibly resolved with more retries.\n";
exit(-1);
}
244
else if (r < 0)
{
std::cout
<< "Cluster connect failed.\n";
exit(-1);
}
if (cluster_connection->wait_until_ready(30,30))
{
std::cout << "Cluster was not ready within 30 secs." << std::endl;
exit(-1);
}
// connect to mysql server
MYSQL mysql;
if ( !mysql_init(&mysql) ) {
std::cout << "mysql_init failed\n";
exit(-1);
}
if ( !mysql_real_connect(&mysql, "localhost", "root", "", "",
0, mysqld_sock, 0) )
MYSQLERROR(mysql);
/********************************************
* Connect to database via mysql-c
*
********************************************/
mysql_query(&mysql, "CREATE DATABASE TEST_DB_1");
if (mysql_query(&mysql, "USE TEST_DB_1") != 0) MYSQLERROR(mysql);
create_table(mysql);
Ndb* myNdb= new Ndb( cluster_connection,
"TEST_DB_1" ); // Object representing the database
if (myNdb->init() == -1) {
APIERROR(myNdb->getNdbError());
exit(-1);
}
const NdbDictionary::Dictionary* myDict= myNdb->getDictionary();
const NdbDictionary::Table *myTable= myDict->getTable("MYTABLENAME");
if (myTable == NULL)
{
APIERROR(myDict->getNdbError());
return -1;
}
/************************************
* Execute some insert transactions *
************************************/
for (int i = 10000; i < 20000; i++) {
executeInsertTransaction(i, myNdb, myTable);
}
delete myNdb;
delete cluster_connection;
drop_table(mysql);
ndb_end(0);
return 0;
}
Ndb_cluster_connection:
connect()
wait_until_ready()
Ndb:
init()
getDictionary()
startTransaction()
closeTransaction()
NdbTransaction:
getNdbScanOperation()
execute()
NdbOperation:
insertTuple()
equal()
setValue()
NdbScanOperation:
getValue()
readTuples()
nextResult()
deleteCurrentTuple()
updateCurrentTuple()
NdbDictionary:
Dictionary::getTable()
See Section 2.3.3, The Dictionary Class.
Table::getColumn()
See Section 2.3.21, The Table Class.
Column::getLength()
See Section 2.3.1, The Column Class.
NdbScanFilter:
begin()
eq()
end()
#include <mysql.h>
#include <mysqld_error.h>
#include <NdbApi.hpp>
// Used for cout
#include <iostream>
#include <stdio.h>
/**
* Helper sleep function
*/
static void
milliSleep(int milliseconds){
struct timeval sleeptime;
sleeptime.tv_sec = milliseconds / 1000;
sleeptime.tv_usec = (milliseconds - (sleeptime.tv_sec * 1000)) * 1000000;
select(0, 0, 0, 0, &sleeptime);
}
/**
* Helper sleep function
*/
#define PRINT_ERROR(code,msg) \
std::cout << "Error in " << __FILE__ << ", line: " << __LINE__ \
<< ", code: " << code \
<< ", msg: " << msg << "." << std::endl
#define MYSQLERROR(mysql) { \
PRINT_ERROR(mysql_errno(&mysql),mysql_error(&mysql)); \
exit(-1); }
#define APIERROR(error) { \
PRINT_ERROR(error.code,error.message); \
exit(-1); }
struct Car
{
/**
* Note memset, so that entire char-fields are cleared
*
as all 20 bytes are significant (as type is char)
*/
Car() { memset(this, 0, sizeof(* this)); }
unsigned int reg_no;
char brand[20];
char color[20];
};
/**
* Function to drop table
*/
void drop_table(MYSQL &mysql)
{
if (mysql_query(&mysql, "DROP TABLE GARAGE"))
MYSQLERROR(mysql);
}
/**
* Function to create table
*/
void create_table(MYSQL &mysql)
{
while (mysql_query(&mysql,
"CREATE TABLE"
" GARAGE"
"
(REG_NO INT UNSIGNED NOT NULL,"
"
BRAND CHAR(20) NOT NULL,"
"
COLOR CHAR(20) NOT NULL,"
"
PRIMARY KEY USING HASH (REG_NO))"
" ENGINE=NDB"))
{
if (mysql_errno(&mysql) != ER_TABLE_EXISTS_ERROR)
MYSQLERROR(mysql);
std::cout << "MySQL Cluster already has example table: GARAGE. "
<< "Dropping it..." << std::endl;
/******************
* Recreate table *
******************/
drop_table(mysql);
create_table(mysql);
}
}
int populate(Ndb * myNdb)
{
int i;
Car cars[15];
const NdbDictionary::Dictionary* myDict= myNdb->getDictionary();
const NdbDictionary::Table *myTable= myDict->getTable("GARAGE");
247
if (myTable == NULL)
APIERROR(myDict->getNdbError());
/**
* Five blue mercedes
*/
for (i = 0; i < 5; i++)
{
cars[i].reg_no = i;
sprintf(cars[i].brand, "Mercedes");
sprintf(cars[i].color, "Blue");
}
/**
* Five black bmw
*/
for (i = 5; i < 10; i++)
{
cars[i].reg_no = i;
sprintf(cars[i].brand, "BMW");
sprintf(cars[i].color, "Black");
}
/**
* Five pink toyotas
*/
for (i = 10; i < 15; i++)
{
cars[i].reg_no = i;
sprintf(cars[i].brand, "Toyota");
sprintf(cars[i].color, "Pink");
}
NdbTransaction* myTrans = myNdb->startTransaction();
if (myTrans == NULL)
APIERROR(myNdb->getNdbError());
for (i = 0; i < 15; i++)
{
NdbOperation* myNdbOperation = myTrans->getNdbOperation(myTable);
if (myNdbOperation == NULL)
APIERROR(myTrans->getNdbError());
myNdbOperation->insertTuple();
myNdbOperation->equal("REG_NO", cars[i].reg_no);
myNdbOperation->setValue("BRAND", cars[i].brand);
myNdbOperation->setValue("COLOR", cars[i].color);
}
int check = myTrans->execute(NdbTransaction::Commit);
myTrans->close();
return check != -1;
}
int scan_delete(Ndb* myNdb,
int column,
const char * color)
{
// Scan all records exclusive and delete
// them one by one
int
retryAttempt = 0;
const int
retryMax = 10;
int deletedRows = 0;
int check;
NdbError
err;
NdbTransaction *myTrans;
NdbScanOperation *myScanOp;
const NdbDictionary::Dictionary* myDict= myNdb->getDictionary();
const NdbDictionary::Table *myTable= myDict->getTable("GARAGE");
if (myTable == NULL)
APIERROR(myDict->getNdbError());
/**
* Loop as long as :
* retryMax not reached
* failed operations due to TEMPORARY erros
*
* Exit loop;
* retyrMax reached
* Permanent error (return -1)
*/
while (true)
{
if (retryAttempt >= retryMax)
{
248
std::cout << "ERROR: has retried this operation " << retryAttempt
<< " times, failing!" << std::endl;
return -1;
}
myTrans = myNdb->startTransaction();
if (myTrans == NULL)
{
const NdbError err = myNdb->getNdbError();
if (err.status == NdbError::TemporaryError)
{
milliSleep(50);
retryAttempt++;
continue;
}
std::cout << err.message << std::endl;
return -1;
}
/**
* Get a scan operation.
*/
myScanOp = myTrans->getNdbScanOperation(myTable);
if (myScanOp == NULL)
{
std::cout << myTrans->getNdbError().message << std::endl;
myNdb->closeTransaction(myTrans);
return -1;
}
/**
* Define a result set for the scan.
*/
if(myScanOp->readTuples(NdbOperation::LM_Exclusive) != 0)
{
std::cout << myTrans->getNdbError().message << std::endl;
myNdb->closeTransaction(myTrans);
return -1;
}
/**
* Use NdbScanFilter to define a search critera
*/
NdbScanFilter filter(myScanOp) ;
if(filter.begin(NdbScanFilter::AND) < 0 ||
filter.cmp(NdbScanFilter::COND_EQ, column, color) < 0 ||
filter.end() < 0)
{
std::cout << myTrans->getNdbError().message << std::endl;
myNdb->closeTransaction(myTrans);
return -1;
}
/**
* Start scan
(NoCommit since we are only reading at this stage);
*/
if(myTrans->execute(NdbTransaction::NoCommit) != 0){
err = myTrans->getNdbError();
if(err.status == NdbError::TemporaryError){
std::cout << myTrans->getNdbError().message << std::endl;
myNdb->closeTransaction(myTrans);
milliSleep(50);
continue;
}
std::cout << err.code << std::endl;
std::cout << myTrans->getNdbError().code << std::endl;
myNdb->closeTransaction(myTrans);
return -1;
}
/**
* start of loop: nextResult(true) means that "parallelism" number of
* rows are fetched from NDB and cached in NDBAPI
*/
while((check = myScanOp->nextResult(true)) == 0){
do
{
if (myScanOp->deleteCurrentTuple() != 0)
{
std::cout << myTrans->getNdbError().message << std::endl;
myNdb->closeTransaction(myTrans);
return -1;
}
deletedRows++;
/**
* nextResult(false) means that the records
* cached in the NDBAPI are modified before
249
250
251
252
*/
NdbRecAttr *
myRecAttr[3];
253
254
}
Ndb myNdb(&cluster_connection,"TEST_DB");
if (myNdb.init(1024) == -1) {
// Set max 1024
APIERROR(myNdb.getNdbError());
exit(-1);
}
parallel transactions
/*******************************************
* Check table definition
*
*******************************************/
int column_color;
{
const NdbDictionary::Dictionary* myDict= myNdb.getDictionary();
const NdbDictionary::Table *t= myDict->getTable("GARAGE");
Car car;
if (t->getColumn("COLOR")->getLength() != sizeof(car.color) ||
t->getColumn("BRAND")->getLength() != sizeof(car.brand))
{
std::cout << "Wrong table definition" << std::endl;
exit(-1);
}
column_color= t->getColumn("COLOR")->getColumnNo();
}
if(populate(&myNdb) > 0)
std::cout << "populate: Success!" << std::endl;
if(scan_print(&myNdb) > 0)
std::cout << "scan_print: Success!" << std::endl
<< std::endl;
<< std::endl;
{
/**
* Note! color1 & 2 need to be of exact the same size as column defined
*/
Car tmp1, tmp2;
sprintf(tmp1.color, "Blue");
sprintf(tmp2.color, "Black");
std::cout << "Going to update all " << tmp1.color
<< " cars to " << tmp2.color << " cars!" << std::endl;
if(scan_update(&myNdb, column_color, tmp1.color, tmp2.color) > 0)
std::cout << "scan_update: Success!" << std::endl << std::endl;
}
if(scan_print(&myNdb) > 0)
std::cout << "scan_print: Success!" << std::endl
<< std::endl;
/**
* Drop table
*/
drop_table(mysql);
return 0;
}
255
4
5
6
7
8
9
14
5
16
7
18
9
#include <mysql.h>
#include <NdbApi.hpp>
// Used for cout
#include <stdio.h>
#include <iostream>
#define PRINT_ERROR(code,msg) \
std::cout << "Error in " << __FILE__ << ", line: " << __LINE__ \
<< ", code: " << code \
<< ", msg: " << msg << "." << std::endl
#define MYSQLERROR(mysql) { \
PRINT_ERROR(mysql_errno(&mysql),mysql_error(&mysql)); \
exit(-1); }
#define APIERROR(error) { \
PRINT_ERROR(error.code,error.message); \
exit(-1); }
int main(int argc, char** argv)
{
if (argc != 3)
{
std::cout << "Arguments are <socket mysqld> <connect_string cluster>.\n";
exit(-1);
}
char * mysqld_sock = argv[1];
const char *connectstring = argv[2];
ndb_init();
MYSQL mysql;
/**************************************************************
* Connect to mysql server and create table
*
**************************************************************/
{
if ( !mysql_init(&mysql) ) {
std::cout << "mysql_init failed\n";
exit(-1);
}
if ( !mysql_real_connect(&mysql, "localhost", "root", "", "",
0, mysqld_sock, 0) )
MYSQLERROR(mysql);
mysql_query(&mysql, "CREATE DATABASE TEST_DB_1");
if (mysql_query(&mysql, "USE TEST_DB_1") != 0) MYSQLERROR(mysql);
if (mysql_query(&mysql,
"CREATE TABLE"
" MYTABLENAME"
"
(ATTR1 INT UNSIGNED,"
"
ATTR2 INT UNSIGNED NOT NULL,"
"
PRIMARY KEY USING HASH (ATTR1),"
"
UNIQUE MYINDEXNAME USING HASH (ATTR2))"
" ENGINE=NDB"))
MYSQLERROR(mysql);
}
/**************************************************************
* Connect to ndb cluster
*
**************************************************************/
Ndb_cluster_connection *cluster_connection=
new Ndb_cluster_connection(connectstring); // Object representing the cluster
if (cluster_connection->connect(5,3,1))
{
std::cout << "Connect to cluster management server failed.\n";
exit(-1);
}
if (cluster_connection->wait_until_ready(30,30))
{
std::cout << "Cluster was not ready within 30 secs.\n";
exit(-1);
}
Ndb* myNdb = new Ndb( cluster_connection,
"TEST_DB_1" ); // Object representing the database
if (myNdb->init() == -1) {
APIERROR(myNdb->getNdbError());
exit(-1);
}
256
257
myTransaction->getNdbIndexOperation(myIndex);
if (myIndexOperation == NULL) APIERROR(myTransaction->getNdbError());
myIndexOperation->deleteTuple();
myIndexOperation->equal( "ATTR2", 3 );
if (myTransaction->execute(NdbTransaction::Commit) == -1)
APIERROR(myTransaction->getNdbError());
myNdb->closeTransaction(myTransaction);
}
/*****************************
* Read and print all tuples *
*****************************/
{
std::cout << "ATTR1 ATTR2" << std::endl;
for (int i = 0; i < 10; i++) {
NdbTransaction *myTransaction= myNdb->startTransaction();
if (myTransaction == NULL) APIERROR(myNdb->getNdbError());
NdbOperation *myOperation= myTransaction->getNdbOperation(myTable);
if (myOperation == NULL) APIERROR(myTransaction->getNdbError());
myOperation->readTuple(NdbOperation::LM_Read);
myOperation->equal("ATTR1", i);
NdbRecAttr *myRecAttr= myOperation->getValue("ATTR2", NULL);
if (myRecAttr == NULL) APIERROR(myTransaction->getNdbError());
if(myTransaction->execute( NdbTransaction::Commit ) == -1)
if (i == 3) {
std::cout << "Detected that deleted tuple doesn't exist!\n";
} else {
APIERROR(myTransaction->getNdbError());
}
if (i != 3) {
printf(" %2d
%2d\n", i, myRecAttr->u_32_value());
}
myNdb->closeTransaction(myTransaction);
}
}
/**************
* Drop table *
**************/
if (mysql_query(&mysql, "DROP TABLE MYTABLENAME"))
MYSQLERROR(mysql);
delete myNdb;
delete cluster_connection;
ndb_end(0);
return 0;
}
258
4
5
6
7
8
9
14
5
16
7
18
9
#include <mysql.h>
#include <NdbApi.hpp>
// Used for cout
#include <stdio.h>
#include <iostream>
#define PRINT_ERROR(code,msg) \
std::cout << "Error in " << __FILE__ << ", line: " << __LINE__ \
<< ", code: " << code \
<< ", msg: " << msg << "." << std::endl
#define MYSQLERROR(mysql) { \
PRINT_ERROR(mysql_errno(&mysql),mysql_error(&mysql)); \
exit(1); }
#define APIERROR(error) { \
PRINT_ERROR(error.code,error.message); \
exit(1); }
int main(int argc, char** argv)
{
if (argc != 3)
{
std::cout << "Arguments are <socket mysqld> <connect_string cluster>.\n";
exit(1);
}
char * mysqld_sock = argv[1];
const char *connectstring = argv[2];
ndb_init();
MYSQL mysql;
/**************************************************************
* Connect to mysql server and create table
*
**************************************************************/
{
if ( !mysql_init(&mysql) ) {
std::cout << "mysql_init failed\n";
exit(1);
}
if ( !mysql_real_connect(&mysql, "localhost", "root", "", "",
0, mysqld_sock, 0) )
MYSQLERROR(mysql);
mysql_query(&mysql, "CREATE DATABASE TEST_DB_1");
if (mysql_query(&mysql, "USE TEST_DB_1") != 0)
MYSQLERROR(mysql);
mysql_query(&mysql, "DROP TABLE MYTABLENAME");
if (mysql_query(&mysql,
"CREATE TABLE"
" MYTABLENAME"
"
(ATTR1 INT UNSIGNED,"
"
ATTR2 INT UNSIGNED NOT NULL,"
"
PRIMARY KEY USING HASH (ATTR1),"
"
UNIQUE MYINDEXNAME USING HASH (ATTR2))"
" ENGINE=NDB"))
MYSQLERROR(mysql);
}
/**************************************************************
* Connect to ndb cluster
*
**************************************************************/
Ndb_cluster_connection *cluster_connection=
new Ndb_cluster_connection(connectstring); // Object representing the cluster
if (cluster_connection->connect(5,3,1))
{
std::cout << "Connect to cluster management server failed.\n";
exit(1);
}
if (cluster_connection->wait_until_ready(30,30))
{
std::cout << "Cluster was not ready within 30 secs.\n";
exit(1);
}
Ndb* myNdb = new Ndb( cluster_connection,
"TEST_DB_1" ); // Object representing the database
if (myNdb->init() == -1) {
APIERROR(myNdb->getNdbError());
259
exit(1);
}
NdbDictionary::Dictionary* myDict= myNdb->getDictionary();
const NdbDictionary::Table *myTable= myDict->getTable("MYTABLENAME");
if (myTable == NULL)
APIERROR(myDict->getNdbError());
const NdbDictionary::Index *myIndex= myDict->getIndex("MYINDEXNAME$unique","MYTABLENAME");
if (myIndex == NULL)
APIERROR(myDict->getNdbError());
/* Create NdbRecord descriptors. */
const NdbDictionary::Column *col1= myTable->getColumn("ATTR1");
if (col1 == NULL)
APIERROR(myDict->getNdbError());
const NdbDictionary::Column *col2= myTable->getColumn("ATTR2");
if (col2 == NULL)
APIERROR(myDict->getNdbError());
/* NdbRecord for primary key lookup. */
NdbDictionary::RecordSpecification spec[2];
spec[0].column= col1;
spec[0].offset= 0;
spec[0].nullbit_byte_offset= 0;
spec[0].nullbit_bit_in_byte= 0;
const NdbRecord *pk_record=
myDict->createRecord(myTable, spec, 1, sizeof(spec[0]));
if (pk_record == NULL)
APIERROR(myDict->getNdbError());
/* NdbRecord for all table attributes (insert/read). */
spec[0].column= col1;
spec[0].offset= 0;
spec[0].nullbit_byte_offset= 0;
spec[0].nullbit_bit_in_byte= 0;
spec[1].column= col2;
spec[1].offset= 4;
spec[1].nullbit_byte_offset= 0;
spec[1].nullbit_bit_in_byte= 0;
const NdbRecord *attr_record=
myDict->createRecord(myTable, spec, 2, sizeof(spec[0]));
if (attr_record == NULL)
APIERROR(myDict->getNdbError());
/* NdbRecord for unique key lookup. */
spec[0].column= col2;
spec[0].offset= 4;
spec[0].nullbit_byte_offset= 0;
spec[0].nullbit_bit_in_byte= 0;
const NdbRecord *key_record=
myDict->createRecord(myIndex, spec, 1, sizeof(spec[0]));
if (key_record == NULL)
APIERROR(myDict->getNdbError());
char row[2][8];
/**************************************************************************
* Using 5 transactions, insert 10 tuples in table: (0,0),(1,1),...,(9,9) *
**************************************************************************/
for (int i = 0; i < 5; i++) {
NdbTransaction *myTransaction= myNdb->startTransaction();
if (myTransaction == NULL) APIERROR(myNdb->getNdbError());
/*
Fill in rows with data. We need two rows, as the data must remain valid
until NdbTransaction::execute() returns.
*/
memcpy(&row[0][0], &i, 4);
memcpy(&row[0][4], &i, 4);
int value= i+5;
memcpy(&row[1][0], &value, 4);
memcpy(&row[1][4], &value, 4);
NdbOperation *myOperation=
myTransaction->insertTuple(attr_record, &row[0][0]);
if (myOperation == NULL)
APIERROR(myTransaction->getNdbError());
myOperation=
myTransaction->insertTuple(attr_record, &row[1][0]);
if (myOperation == NULL)
APIERROR(myTransaction->getNdbError());
if (myTransaction->execute( NdbTransaction::Commit ) == -1)
APIERROR(myTransaction->getNdbError());
myNdb->closeTransaction(myTransaction);
}
/*****************************************
* Read and print all tuples using index *
*****************************************/
260
261
NdbOperation *myOperation=
myTransaction->readTuple(pk_record, &row[0][0],
attr_record, &row[1][0]);
if (myOperation == NULL)
APIERROR(myTransaction->getNdbError());
if (myTransaction->execute( NdbTransaction::Commit,
NdbOperation::AbortOnError ) == -1)
if (i == 3) {
std::cout << "Detected that deleted tuple doesn't exist!\n";
} else {
APIERROR(myTransaction->getNdbError());
}
if (i != 3) {
int value1, value2;
memcpy(&value1, &row[1][0], 4);
memcpy(&value2, &row[1][4], 4);
printf(" %2d
%2d\n", value1, value2);
}
myNdb->closeTransaction(myTransaction);
}
}
/**************
* Drop table *
**************/
if (mysql_query(&mysql, "DROP TABLE MYTABLENAME"))
MYSQLERROR(mysql);
delete myNdb;
delete cluster_connection;
ndb_end(0);
return 0;
}
262
263
eventTableName,
eventColumnName,
noEventColumnName,
merge_events);
// Normal values and blobs are unfortunately handled differently..
typedef union { NdbRecAttr* ra; NdbBlob* bh; } RA_BH;
int i, j, k, l;
j = 0;
while (j < timeout) {
// Start "transaction" for handling events
NdbEventOperation* op;
printf("create EventOperation\n");
if ((op = myNdb->createEventOperation(eventName)) == NULL)
APIERROR(myNdb->getNdbError());
op->mergeEvents(merge_events);
printf("get values\n");
RA_BH recAttr[noEventColumnName];
RA_BH recAttrPre[noEventColumnName];
// primary keys should always be a part of the result
for (i = 0; i < noEventColumnName; i++) {
if (i < 4) {
recAttr[i].ra
= op->getValue(eventColumnName[i]);
recAttrPre[i].ra = op->getPreValue(eventColumnName[i]);
} else if (merge_events) {
recAttr[i].bh
= op->getBlobHandle(eventColumnName[i]);
recAttrPre[i].bh = op->getPreBlobHandle(eventColumnName[i]);
}
}
// set up the callbacks
printf("execute\n");
// This starts changes to "start flowing"
if (op->execute())
APIERROR(op->getNdbError());
NdbEventOperation* the_op = op;
i= 0;
while (i < timeout) {
// printf("now waiting for event...\n");
int r = myNdb->pollEvents(1000); // wait for event or 1000 ms
if (r > 0) {
// printf("got data! %d\n", r);
while ((op= myNdb->nextEvent())) {
assert(the_op == op);
i++;
switch (op->getEventType()) {
case NdbDictionary::Event::TE_INSERT:
printf("%u INSERT", i);
break;
case NdbDictionary::Event::TE_DELETE:
printf("%u DELETE", i);
break;
case NdbDictionary::Event::TE_UPDATE:
printf("%u UPDATE", i);
break;
default:
abort(); // should not happen
}
printf(" gci=%d\n", (int)op->getGCI());
for (k = 0; k <= 1; k++) {
printf(k == 0 ? "post: " : "pre : ");
for (l = 0; l < noEventColumnName; l++) {
if (l < 4) {
NdbRecAttr* ra = k == 0 ? recAttr[l].ra : recAttrPre[l].ra;
if (ra->isNULL() >= 0) { // we have a value
if (ra->isNULL() == 0) { // we have a nonnull value
if (l < 2)
printf("%-5u", ra->u_32_value());
else
printf("%-5.4s", ra->aRef());
} else
printf("%-5s", "NULL");
} else
printf("%-5s", "-"); // no value
} else if (merge_events) {
int isNull;
NdbBlob* bh = k == 0 ? recAttr[l].bh : recAttrPre[l].bh;
bh->getDefined(isNull);
if (isNull >= 0) { // we have a value
if (! isNull) { // we have a nonnull value
Uint64 length = 0;
bh->getLength(length);
// read into buffer
unsigned char* buf = new unsigned char [length];
memset(buf, 'X', length);
264
Uint32 n = length;
bh->readData(buf, n); // n is in/out
assert(n == length);
// pretty-print
bool first = true;
Uint32 i = 0;
while (i < n) {
unsigned char c = buf[i++];
Uint32 m = 1;
while (i < n && buf[i] == c)
i++, m++;
if (! first)
printf("+");
printf("%u%c", m, c);
first = false;
}
printf("[%u]", n);
delete [] buf;
} else
printf("%-5s", "NULL");
} else
printf("%-5s", "-"); // no value
}
}
printf("\n");
}
}
} else
printf("timed out (%i)\n", timeout);
}
// don't want to listen to events anymore
if (myNdb->dropEventOperation(the_op)) APIERROR(myNdb->getNdbError());
the_op = 0;
j++;
}
{
NdbDictionary::Dictionary *myDict = myNdb->getDictionary();
if (!myDict) APIERROR(myNdb->getNdbError());
// remove event from database
if (myDict->dropEvent(eventName)) APIERROR(myDict->getNdbError());
}
delete myNdb;
delete cluster_connection;
ndb_end(0);
return 0;
}
int myCreateEvent(Ndb* myNdb,
const char *eventName,
const char *eventTableName,
const char **eventColumnNames,
const int noEventColumnNames,
bool merge_events)
{
NdbDictionary::Dictionary *myDict= myNdb->getDictionary();
if (!myDict) APIERROR(myNdb->getNdbError());
const NdbDictionary::Table *table= myDict->getTable(eventTableName);
if (!table) APIERROR(myDict->getNdbError());
NdbDictionary::Event myEvent(eventName, *table);
myEvent.addTableEvent(NdbDictionary::Event::TE_ALL);
// myEvent.addTableEvent(NdbDictionary::Event::TE_INSERT);
// myEvent.addTableEvent(NdbDictionary::Event::TE_UPDATE);
// myEvent.addTableEvent(NdbDictionary::Event::TE_DELETE);
myEvent.addEventColumns(noEventColumnNames, eventColumnNames);
myEvent.mergeEvents(merge_events);
// Add event to database
if (myDict->createEvent(myEvent) == 0)
myEvent.print();
else if (myDict->getNdbError().classification ==
NdbError::SchemaObjectExists) {
printf("Event creation failed, event exists\n");
printf("dropping Event...\n");
if (myDict->dropEvent(eventName)) APIERROR(myDict->getNdbError());
// try again
// Add event to database
if ( myDict->createEvent(myEvent)) APIERROR(myDict->getNdbError());
} else
APIERROR(myDict->getNdbError());
return 0;
}
265
<mysql.h>
<ndbapi/NdbApi.hpp>
<mgmapi.h>
<stdio.h>
/*
* export LD_LIBRARY_PATH=../../../libmysql_r/.libs:../../../ndb/src/.libs
*/
#define MGMERROR(h) \
{ \
fprintf(stderr, "code: %d msg: %s\n", \
ndb_mgm_get_latest_error(h), \
ndb_mgm_get_latest_error_msg(h)); \
exit(-1); \
}
#define LOGEVENTERROR(h) \
{ \
fprintf(stderr, "code: %d msg: %s\n", \
ndb_logevent_get_latest_error(h), \
ndb_logevent_get_latest_error_msg(h)); \
exit(-1); \
}
int main(int argc, char** argv)
{
NdbMgmHandle h1,h2;
NdbLogEventHandle le1,le2;
int filter[] = { 15, NDB_MGM_EVENT_CATEGORY_BACKUP,
15, NDB_MGM_EVENT_CATEGORY_CONNECTION,
15, NDB_MGM_EVENT_CATEGORY_NODE_RESTART,
15, NDB_MGM_EVENT_CATEGORY_STARTUP,
15, NDB_MGM_EVENT_CATEGORY_ERROR,
0 };
struct ndb_logevent event1, event2;
if (argc < 3)
{
printf("Arguments are <connect_string cluster 1> <connect_string cluster 2> [<iterations>].\n");
exit(-1);
}
const char *connectstring1 = argv[1];
const char *connectstring2 = argv[2];
int iterations = -1;
if (argc > 3)
iterations = atoi(argv[3]);
ndb_init();
h1= ndb_mgm_create_handle();
h2= ndb_mgm_create_handle();
if ( h1 == 0 || h2 == 0 )
{
printf("Unable to create handle\n");
exit(-1);
}
if (ndb_mgm_set_connectstring(h1, connectstring1) == -1 ||
ndb_mgm_set_connectstring(h2, connectstring1))
{
printf("Unable to set connectstring\n");
exit(-1);
}
if (ndb_mgm_connect(h1,0,0,0)) MGMERROR(h1);
if (ndb_mgm_connect(h2,0,0,0)) MGMERROR(h2);
if ((le1= ndb_mgm_create_logevent_handle(h1, filter)) == 0) MGMERROR(h1);
if ((le2= ndb_mgm_create_logevent_handle(h1, filter)) == 0) MGMERROR(h2);
while (iterations-- != 0)
{
int timeout= 1000;
int r1= ndb_logevent_get_next(le1,&event1,timeout);
if (r1 == 0)
printf("No event within %d milliseconds\n", timeout);
else if (r1 < 0)
LOGEVENTERROR(le1)
else
{
switch (event1.type) {
case NDB_LE_BackupStarted:
printf("Node %d: BackupStarted\n", event1.source_nodeid);
266
267
printf("
break;
case NDB_LE_Connected:
printf("Node %d: Connected\n", event2.source_nodeid);
printf(" node %d\n", event2.Connected.node);
break;
case NDB_LE_Disconnected:
printf("Node %d: Disconnected\n", event2.source_nodeid);
printf(" node %d\n", event2.Disconnected.node);
break;
case NDB_LE_NDBStartCompleted:
printf("Node %d: StartCompleted\n", event2.source_nodeid);
printf(" version %d.%d.%d\n",
event2.NDBStartCompleted.version >> 16 & 0xff,
event2.NDBStartCompleted.version >> 8 & 0xff,
event2.NDBStartCompleted.version >> 0 & 0xff);
break;
case NDB_LE_ArbitState:
printf("Node %d: ArbitState\n", event2.source_nodeid);
printf(" code %d, arbit_node %d\n",
event2.ArbitState.code & 0xffff,
event2.ArbitResult.arbit_node);
break;
default:
break;
}
}
}
ndb_mgm_destroy_logevent_handle(&le1);
ndb_mgm_destroy_logevent_handle(&le2);
ndb_mgm_destroy_handle(&h1);
ndb_mgm_destroy_handle(&h2);
ndb_end(0);
return 0;
}
Note
While the MySQL data type used in the example is actually TEXT, the same principles apply
#include <mysql.h>
#include <mysqld_error.h>
#include <NdbApi.hpp>
/* Used for cout. */
#include <iostream>
#include <stdio.h>
#include <ctype.h>
/**
* Helper debugging macros
*/
#define PRINT_ERROR(code,msg) \
std::cout << "Error in " << __FILE__ << ", line: " << __LINE__ \
<< ", code: " << code \
<< ", msg: " << msg << "." << std::endl
#define MYSQLERROR(mysql) { \
PRINT_ERROR(mysql_errno(&mysql),mysql_error(&mysql)); \
exit(-1); }
#define APIERROR(error) { \
PRINT_ERROR(error.code,error.message); \
exit(-1); }
/* Quote taken from Project Gutenberg. */
const char *text_quote=
"Just at this moment, somehow or other, they began to run.\n"
"\n"
" Alice never could quite make out, in thinking it over\n"
"afterwards, how it was that they began: all she remembers is,\n"
"that they were running hand in hand, and the Queen went so fast\n"
"that it was all she could do to keep up with her: and still the\n"
"Queen kept crying 'Faster! Faster!' but Alice felt she COULD NOT\n"
268
"go faster, though she had not breath left to say so.\n"
"\n"
" The most curious part of the thing was, that the trees and the\n"
"other things round them never changed their places at all:\n"
"however fast they went, they never seemed to pass anything. 'I\n"
"wonder if all the things move along with us?' thought poor\n"
"puzzled Alice. And the Queen seemed to guess her thoughts, for\n"
"she cried, 'Faster! Don't try to talk!'\n"
"\n"
" Not that Alice had any idea of doing THAT. She felt as if she\n"
"would never be able to talk again, she was getting so much out of\n"
"breath: and still the Queen cried 'Faster! Faster!' and dragged\n"
"her along. 'Are we nearly there?' Alice managed to pant out at\n"
"last.\n"
"\n"
" 'Nearly there!' the Queen repeated. 'Why, we passed it ten\n"
"minutes ago! Faster!' And they ran on for a time in silence,\n"
"with the wind whistling in Alice's ears, and almost blowing her\n"
"hair off her head, she fancied.\n"
"\n"
" 'Now! Now!' cried the Queen. 'Faster! Faster!' And they\n"
"went so fast that at last they seemed to skim through the air,\n"
"hardly touching the ground with their feet, till suddenly, just\n"
"as Alice was getting quite exhausted, they stopped, and she found\n"
"herself sitting on the ground, breathless and giddy.\n"
"\n"
" The Queen propped her up against a tree, and said kindly, 'You\n"
"may rest a little now.'\n"
"\n"
" Alice looked round her in great surprise. 'Why, I do believe\n"
"we've been under this tree the whole time! Everything's just as\n"
"it was!'\n"
"\n"
" 'Of course it is,' said the Queen, 'what would you have it?'\n"
"\n"
" 'Well, in OUR country,' said Alice, still panting a little,\n"
"'you'd generally get to somewhere else--if you ran very fast\n"
"for a long time, as we've been doing.'\n"
"\n"
" 'A slow sort of country!' said the Queen. 'Now, HERE, you see,\n"
"it takes all the running YOU can do, to keep in the same place.\n"
"If you want to get somewhere else, you must run at least twice as\n"
"fast as that!'\n"
"\n"
" 'I'd rather not try, please!' said Alice. 'I'm quite content\n"
"to stay here--only I AM so hot and thirsty!'\n"
"\n"
" -- Lewis Carroll, 'Through the Looking-Glass'.";
/*
Function to drop table.
*/
void drop_table(MYSQL &mysql)
{
if (mysql_query(&mysql, "DROP TABLE my_text"))
MYSQLERROR(mysql);
}
/*
Functions to create table.
*/
int try_create_table(MYSQL &mysql)
{
return mysql_query(&mysql,
"CREATE TABLE"
" my_text"
"
(my_id INT UNSIGNED NOT NULL,"
"
my_text TEXT NOT NULL,"
"
PRIMARY KEY USING HASH (my_id))"
" ENGINE=NDB");
}
void create_table(MYSQL &mysql)
{
if (try_create_table(mysql))
{
if (mysql_errno(&mysql) != ER_TABLE_EXISTS_ERROR)
MYSQLERROR(mysql);
std::cout << "MySQL Cluster already has example table: my_text. "
<< "Dropping it..." << std::endl;
/******************
* Recreate table *
******************/
drop_table(mysql);
if (try_create_table(mysql))
MYSQLERROR(mysql);
}
}
269
270
// Scan done.
Uint64 length= 0;
if (myBlobHandle->getLength(length) == -1)
APIERROR(myBlobHandle->getNdbError());
/* Lowercase everything. */
for (Uint64 j= 0; j < length; j++)
buffer[j]= tolower(buffer[j]);
NdbOperation *myUpdateOp= myScanOp->updateCurrentTuple();
if (myUpdateOp == NULL)
APIERROR(myTrans->getNdbError());
NdbBlob *myBlobHandle2= myUpdateOp->getBlobHandle("my_text");
if (myBlobHandle2 == NULL)
APIERROR(myUpdateOp->getNdbError());
if (myBlobHandle2->setValue(buffer, length))
APIERROR(myBlobHandle2->getNdbError());
if (-1 == myTrans->execute(NdbTransaction::NoCommit))
APIERROR(myTrans->getNdbError());
}
if (-1 == myTrans->execute(NdbTransaction::Commit))
APIERROR(myTrans->getNdbError());
myNdb->closeTransaction(myTrans);
return 1;
}
struct ActiveHookData {
char buffer[10000];
Uint32 readLength;
};
271
272
if (myTable == NULL)
APIERROR(myDict->getNdbError());
NdbTransaction *myTrans= myNdb->startTransaction();
if (myTrans == NULL)
APIERROR(myNdb->getNdbError());
NdbOperation *myNdbOperation= myTrans->getNdbOperation(myTable);
if (myNdbOperation == NULL)
APIERROR(myTrans->getNdbError());
myNdbOperation->deleteTuple();
myNdbOperation->equal("my_id", 1);
if (-1 == myTrans->execute(NdbTransaction::Commit))
APIERROR(myTrans->getNdbError());
myNdb->closeTransaction(myTrans);
return 1;
}
int main(int argc, char**argv)
{
if (argc != 3)
{
std::cout << "Arguments are <socket mysqld> <connect_string cluster>.\n";
exit(-1);
}
char *mysqld_sock = argv[1];
const char *connectstring = argv[2];
ndb_init();
MYSQL mysql;
/* Connect to mysql server and create table. */
{
if ( !mysql_init(&mysql) ) {
std::cout << "mysql_init failed.\n";
exit(-1);
}
if ( !mysql_real_connect(&mysql, "localhost", "root", "", "",
0, mysqld_sock, 0) )
MYSQLERROR(mysql);
mysql_query(&mysql, "CREATE DATABASE TEST_DB");
if (mysql_query(&mysql, "USE TEST_DB") != 0)
MYSQLERROR(mysql);
create_table(mysql);
}
/* Connect to ndb cluster. */
Ndb_cluster_connection cluster_connection(connectstring);
if (cluster_connection.connect(4, 5, 1))
{
std::cout << "Unable to connect to cluster within 30 secs." << std::endl;
exit(-1);
}
/* Optionally connect and wait for the storage nodes (ndbd's). */
if (cluster_connection.wait_until_ready(30,0) < 0)
{
std::cout << "Cluster was not ready within 30 secs.\n";
exit(-1);
}
Ndb myNdb(&cluster_connection,"TEST_DB");
if (myNdb.init(1024) == -1) {
// Set max 1024 parallel transactions
APIERROR(myNdb.getNdbError());
exit(-1);
}
if(populate(&myNdb) > 0)
std::cout << "populate: Success!" << std::endl;
if(update_key(&myNdb) > 0)
std::cout << "update_key: Success!" << std::endl;
if(update_scan(&myNdb) > 0)
std::cout << "update_scan: Success!" << std::endl;
if(fetch_key(&myNdb) > 0)
std::cout << "fetch_key: Success!" << std::endl;
if(update2_key(&myNdb) > 0)
std::cout << "update2_key: Success!" << std::endl;
if(delete_key(&myNdb) > 0)
std::cout << "delete_key: Success!" << std::endl;
/* Drop table. */
273
drop_table(mysql);
return 0;
}
Note
While the MySQL data type used in the example is actually TEXT, the same principles apply
#include <mysql.h>
#include <mysqld_error.h>
#include <NdbApi.hpp>
/* Used for cout. */
#include <iostream>
#include <stdio.h>
#include <ctype.h>
/**
* Helper debugging macros
*/
#define PRINT_ERROR(code,msg) \
std::cout << "Error in " << __FILE__ << ", line: " << __LINE__ \
<< ", code: " << code \
<< ", msg: " << msg << "." << std::endl
#define MYSQLERROR(mysql) { \
PRINT_ERROR(mysql_errno(&mysql),mysql_error(&mysql)); \
exit(-1); }
#define APIERROR(error) { \
PRINT_ERROR(error.code,error.message); \
exit(-1); }
/* Quote taken from Project Gutenberg. */
const char *text_quote=
"Just at this moment, somehow or other, they began to run.\n"
"\n"
" Alice never could quite make out, in thinking it over\n"
"afterwards, how it was that they began: all she remembers is,\n"
"that they were running hand in hand, and the Queen went so fast\n"
"that it was all she could do to keep up with her: and still the\n"
"Queen kept crying 'Faster! Faster!' but Alice felt she COULD NOT\n"
"go faster, though she had not breath left to say so.\n"
"\n"
" The most curious part of the thing was, that the trees and the\n"
"other things round them never changed their places at all:\n"
"however fast they went, they never seemed to pass anything. 'I\n"
"wonder if all the things move along with us?' thought poor\n"
"puzzled Alice. And the Queen seemed to guess her thoughts, for\n"
"she cried, 'Faster! Don't try to talk!'\n"
"\n"
" Not that Alice had any idea of doing THAT. She felt as if she\n"
"would never be able to talk again, she was getting so much out of\n"
"breath: and still the Queen cried 'Faster! Faster!' and dragged\n"
"her along. 'Are we nearly there?' Alice managed to pant out at\n"
"last.\n"
"\n"
" 'Nearly there!' the Queen repeated. 'Why, we passed it ten\n"
"minutes ago! Faster!' And they ran on for a time in silence,\n"
"with the wind whistling in Alice's ears, and almost blowing her\n"
"hair off her head, she fancied.\n"
"\n"
" 'Now! Now!' cried the Queen. 'Faster! Faster!' And they\n"
"went so fast that at last they seemed to skim through the air,\n"
"hardly touching the ground with their feet, till suddenly, just\n"
"as Alice was getting quite exhausted, they stopped, and she found\n"
"herself sitting on the ground, breathless and giddy.\n"
"\n"
" The Queen propped her up against a tree, and said kindly, 'You\n"
"may rest a little now.'\n"
"\n"
" Alice looked round her in great surprise. 'Why, I do believe\n"
"we've been under this tree the whole time! Everything's just as\n"
"it was!'\n"
"\n"
" 'Of course it is,' said the Queen, 'what would you have it?'\n"
274
"\n"
" 'Well, in OUR country,' said Alice, still panting a little,\n"
"'you'd generally get to somewhere else--if you ran very fast\n"
"for a long time, as we've been doing.'\n"
"\n"
" 'A slow sort of country!' said the Queen. 'Now, HERE, you see,\n"
"it takes all the running YOU can do, to keep in the same place.\n"
"If you want to get somewhere else, you must run at least twice as\n"
"fast as that!'\n"
"\n"
" 'I'd rather not try, please!' said Alice. 'I'm quite content\n"
"to stay here--only I AM so hot and thirsty!'\n"
"\n"
" -- Lewis Carroll, 'Through the Looking-Glass'.";
/* NdbRecord objects. */
const NdbRecord *key_record;
const NdbRecord *blob_record;
const NdbRecord *full_record;
/* The row is 4 bytes of primary key + space for blob handle pointer. */
#define ROWSIZE (4 + sizeof(NdbBlob *))
static void setup_records(Ndb *myNdb)
{
NdbDictionary::RecordSpecification spec[2];
NdbDictionary::Dictionary *myDict= myNdb->getDictionary();
const NdbDictionary::Table *myTable= myDict->getTable("my_text");
if (myTable == NULL)
APIERROR(myDict->getNdbError());
const NdbDictionary::Column *col1= myTable->getColumn("my_id");
if (col1 == NULL)
APIERROR(myDict->getNdbError());
const NdbDictionary::Column *col2= myTable->getColumn("my_text");
if (col2 == NULL)
APIERROR(myDict->getNdbError());
spec[0].column= col1;
spec[0].offset= 0;
spec[0].nullbit_byte_offset=
spec[0].nullbit_bit_in_byte=
spec[1].column= col2;
spec[1].offset= 4;
spec[1].nullbit_byte_offset=
spec[1].nullbit_bit_in_byte=
0;
0;
0;
0;
275
276
/* Uppercase everything. */
for (Uint64 j= 0; j < chunk_length; j++)
buffer[j]= toupper(buffer[j]);
if (-1 == myBlobHandle->setPos(pos))
APIERROR(myBlobHandle->getNdbError());
if (-1 == myBlobHandle->writeData(buffer, chunk_length))
APIERROR(myBlobHandle->getNdbError());
/* Commit on the final update. */
if (-1 == myTrans->execute(chunk ?
NdbTransaction::NoCommit :
NdbTransaction::Commit))
APIERROR(myTrans->getNdbError());
}
myNdb->closeTransaction(myTrans);
return 1;
}
int update_scan(Ndb *myNdb)
{
/*
Lowercase all characters in TEXT field, using a scan with
updateCurrentTuple().
*/
char buffer[10000];
char row[ROWSIZE];
NdbTransaction *myTrans= myNdb->startTransaction();
if (myTrans == NULL)
APIERROR(myNdb->getNdbError());
NdbScanOperation *myScanOp=
myTrans->scanTable(blob_record, NdbOperation::LM_Exclusive);
if (myScanOp == NULL)
APIERROR(myTrans->getNdbError());
NdbBlob *myBlobHandle= myScanOp->getBlobHandle("my_text");
if (myBlobHandle == NULL)
APIERROR(myScanOp->getNdbError());
if (myBlobHandle->getValue(buffer, sizeof(buffer)))
APIERROR(myBlobHandle->getNdbError());
/* Start the scan. */
if (-1 == myTrans->execute(NdbTransaction::NoCommit))
APIERROR(myTrans->getNdbError());
const char *out_row;
int res;
for (;;)
{
res= myScanOp->nextResult(out_row, true);
if (res==1)
break;
else if (res)
APIERROR(myScanOp->getNdbError());
// Scan done.
Uint64 length= 0;
if (myBlobHandle->getLength(length) == -1)
APIERROR(myBlobHandle->getNdbError());
/* Lowercase everything. */
for (Uint64 j= 0; j < length; j++)
buffer[j]= tolower(buffer[j]);
NdbOperation *myUpdateOp=
myScanOp->updateCurrentTuple(myTrans, blob_record, row);
if (myUpdateOp == NULL)
APIERROR(myTrans->getNdbError());
NdbBlob *myBlobHandle2= myUpdateOp->getBlobHandle("my_text");
if (myBlobHandle2 == NULL)
APIERROR(myUpdateOp->getNdbError());
if (myBlobHandle2->setValue(buffer, length))
APIERROR(myBlobHandle2->getNdbError());
if (-1 == myTrans->execute(NdbTransaction::NoCommit))
APIERROR(myTrans->getNdbError());
}
if (-1 == myTrans->execute(NdbTransaction::Commit))
APIERROR(myTrans->getNdbError());
myNdb->closeTransaction(myTrans);
return 1;
}
struct ActiveHookData {
277
char buffer[10000];
Uint32 readLength;
};
int myFetchHook(NdbBlob* myBlobHandle, void* arg)
{
ActiveHookData *ahd= (ActiveHookData *)arg;
ahd->readLength= sizeof(ahd->buffer) - 1;
return myBlobHandle->readData(ahd->buffer, ahd->readLength);
}
int fetch_key(Ndb *myNdb)
{
char key_row[ROWSIZE];
char out_row[ROWSIZE];
/*
Fetch and show the blob field, using setActiveHook().
*/
NdbTransaction *myTrans= myNdb->startTransaction();
if (myTrans == NULL)
APIERROR(myNdb->getNdbError());
Uint32 id= 1;
memcpy(&key_row[0], &id, 4);
NdbOperation *myNdbOperation=
myTrans->readTuple(key_record, key_row, blob_record, out_row);
if (myNdbOperation == NULL)
APIERROR(myTrans->getNdbError());
NdbBlob *myBlobHandle= myNdbOperation->getBlobHandle("my_text");
if (myBlobHandle == NULL)
APIERROR(myNdbOperation->getNdbError());
struct ActiveHookData ahd;
if (myBlobHandle->setActiveHook(myFetchHook, &ahd) == -1)
APIERROR(myBlobHandle->getNdbError());
/*
Execute Commit, but calling our callback set up in setActiveHook()
before actually committing.
*/
if (-1 == myTrans->execute(NdbTransaction::Commit))
APIERROR(myTrans->getNdbError());
myNdb->closeTransaction(myTrans);
/* Our fetch callback will have been called during the execute(). */
ahd.buffer[ahd.readLength]= '\0';
std::cout << "Fetched data:" << std::endl << ahd.buffer << std::endl;
return 1;
}
int update2_key(Ndb *myNdb)
{
char buffer[10000];
char row[ROWSIZE];
/* Simple setValue() update. */
NdbTransaction *myTrans= myNdb->startTransaction();
if (myTrans == NULL)
APIERROR(myNdb->getNdbError());
Uint32 id= 1;
memcpy(&row[0], &id, 4);
NdbOperation *myNdbOperation=
myTrans->updateTuple(key_record, row, blob_record, row);
if (myNdbOperation == NULL)
APIERROR(myTrans->getNdbError());
NdbBlob *myBlobHandle= myNdbOperation->getBlobHandle("my_text");
if (myBlobHandle == NULL)
APIERROR(myNdbOperation->getNdbError());
memset(buffer, ' ', sizeof(buffer));
if (myBlobHandle->setValue(buffer, sizeof(buffer)) == -1)
APIERROR(myBlobHandle->getNdbError());
if (-1 == myTrans->execute(NdbTransaction::Commit))
APIERROR(myTrans->getNdbError());
myNdb->closeTransaction(myTrans);
return 1;
}
int delete_key(Ndb *myNdb)
{
char row[ROWSIZE];
278
279
/* Drop table. */
drop_table(mysql);
return 0;
}
280
Important
You should not share an NdbMgmHandle between threads. While it is possible to do so (if you implement your own
locks), this is not recommended; each thread should use its own management server handle.
A function can return any of the following:
A nonconstant pointer value. A NULL value indicates an error; otherwise, the return value must be freed by the programmer.
A constant pointer value, with a NULL value indicating an error. The returned value should not be freed.
Error conditions can be identified by using the appropriate error-reporting functions ndb_mgm_get_latest_error() and
ndb_mgm_error().
Here is an example using the MGM API (without error handling for brevity's sake):
NdbMgmHandle handle= ndb_mgm_create_handle();
ndb_mgm_connect(handle,0,0,0);
struct ndb_mgm_cluster_state *state= ndb_mgm_get_status(handle);
for(int i=0; i < state->no_of_nodes; i++)
{
struct ndb_mgm_node_state *node_state= &state->node_states[i];
printf("node with ID=%d ", node_state->node_id);
if(node_state->version != 0)
printf("connected\n");
else
printf("not connected\n");
}
free((void*)state);
ndb_mgm_destroy_handle(&handle);
2.
3.
The log event data is available in the structure ndb_logevent. The data which is specific to a particular event is stored in a union between structures; use ndb_logevent::type to decide which structure is valid.
Note
Available log event types are listed in Section 3.3.4, The Ndb_logevent_type Type, as well as in the file /
storage/ndb/include/mgmapi/ndb_logevent.h in the MySQL 5.1 sources.
3.2.1.1. ndb_mgm_listen_event()
Description. This function is used to listen to log events, which are read from the return file descriptor. Events use a text-based format,
the same as in the cluster log.
Signature.
int ndb_mgm_listen_event
(
NdbMgmHandle handle,
const int
filter[]
)
282
An NdbMgmHandle handle.
A filter which consists of a series of {level, ndb_mgm_event_category} pairs (in a single array) that are pushed to a
file descriptor. Use 0 for the level to terminate the list.
Return value. The file descriptor from which events are to be read.
3.2.1.2. ndb_mgm_create_logevent_handle()
Description. This function is used to create a log event handle.
Signature.
NdbLogEventHandle ndb_mgm_create_logevent_handle
(
NdbMgmHandle handle,
const int
filter[]
)
An NdbMgmHandle handle.
A filter which consists of a series of {level, ndb_mgm_event_category} pairs (in a single array) that are pushed to a
file descriptor. Use 0 for the level to terminate the list.
3.2.1.3. ndb_mgm_destroy_logevent_handle()
Description. Use this function to destroy a log event handle when there is no further need for it.
Signature.
void ndb_mgm_destroy_logevent_handle
(
NdbLogEventHandle* handle
)
3.2.1.4. ndb_logevent_get_fd()
Description. This function retrieves a file descriptor from an NdbMgmLogEventHandle. It was implemented in MySQL 5.1.12.
Warning
Do not attempt to read from the file descriptor returned by this function.
Signature.
int ndb_logevent_get_fd
(
const NdbLogEventHandle handle
)
Parameters. A LogEventHandle.
Return value. A file descriptor. In the event of failure, -1 is returned.
3.2.1.5. ndb_logevent_get_next()
283
Description. This function is used to retrieve the next log event, using the event's data to fill in the supplied ndb_logevent structure.
Signature.
int ndb_logevent_get_next
(
const NdbLogEventHandle handle,
struct ndb_logevent*
logevent,
unsigned
timeout
)
An NdbLogEventHandle
The number of milliseconds to wait for the event before timing out; passing 0 for this parameter causes the function to block until
the next log event is received
> 0: The event exists, and it data was retrieved into the logevent
0: A timeout occurred while waiting for the event (more than timeout milliseconds elapsed)
If the return value is less than or equal to zero, then the logevent is not altered or affected in any way.
3.2.1.6. ndb_logevent_get_latest_error()
Description. This function retrieves the error code from the most recent error.
Note
You may prefer to use ndb_logevent_get_latest_error_msg() instead. See Section 3.2.1.7,
ndb_logevent_get_latest_error_msg()
Signature.
int ndb_logevent_get_latest_error
(
const NdbLogEventHandle handle
)
3.2.1.7. ndb_logevent_get_latest_error_msg()
Description. Retrieves the text of the most recent error obtained while trying to read log events.
Signature.
const char* ndb_logevent_get_latest_error_msg
(
const NdbLogEventHandle handle
)
284
3.2.2.1. ndb_mgm_get_latest_error()
Description. This function is used to get the latest error code associated with a given management server handle.
Signature.
int ndb_mgm_get_latest_error
(
const NdbMgmHandle handle
)
Parameters. An NdbMgMHandle.
Return value. An error code corresponding to an ndb_mgm_error value; see Section 3.3.3, The ndb_mgm_error Type. You
can obtain the related error message using ndb_mgm_get_latest_error_msg(); see Section 3.2.2.2,
ndb_mgm_get_latest_error_msg().
3.2.2.2. ndb_mgm_get_latest_error_msg()
Description. This function is used to obtain the latest general error message associated with an NdbMgmHandle.
Signature.
const char* ndb_mgm_get_latest_error_msg
(
const NdbMgmHandle handle
)
Parameters. An NdbMgmHandle.
Return value. The error message text. More specific information can be obtained using ndb_mgm_get_latest_error_desc();
see Section 3.2.2.3, ndb_mgm_get_latest_error_desc(), for details.
3.2.2.3. ndb_mgm_get_latest_error_desc()
Description. Get the most recent error description associated with an NdbMgmHandle; this description provides additional information regarding the error message.
Signature.
const char* ndb_mgm_get_latest_error_desc
(
const NdbMgmHandle handle
)
Parameters. An NdbMgmHandle.
Return value. The error description text.
3.2.2.4. ndb_mgm_set_error_stream()
Description. The function can be used to set the error output stream.
Signature.
void ndb_mgm_set_error_stream
(
285
NdbMgmHandle handle,
FILE*
file
)
An NdbMgmHandle
3.2.3.1. ndb_mgm_create_handle()
Description. This function is used to create a handle to a management server.
Signature.
NdbMgmHandle ndb_mgm_create_handle
(
void
)
Parameters. None.
Return value. An NdbMgmHandle.
3.2.3.2. ndb_mgm_set_name()
Description. This function can be used to set a name for the management server handle, which is then reported in the Cluster log.
Signature.
void ndb_mgm_set_name
(
NdbMgmHandle handle,
const char* name
)
3.2.3.3. ndb_mgm_set_ignore_sigpipe()
Description. Beginning with MySQL Cluster NDB 6.3.19, the MGM API by default installs a signal handler that ignores all SIGPIPE
signals that might occur when writing to asocket that has been closed or reset. An application that provides its own handler for SIGPIPE should call this function after creating the management server handle and before using the handle to connect to the management
server. (In other words, call this function after using ndb_mgm_create_handle() but before calling ndb_mgm_connect(),
which causes the MGM API's SIGPIPE handler to be installed unless overridden.)
Note
Previous to MySQL Cluster NDB 6.3.19, MGM API applications simply exited without returning an error whenever the
286
An integer value which determines whether to ignore SIGPIPE errors. Set this to 1 (the default) to cause the MGM API to ignore SIGPIPE; set to zero if you wish for SIGPIPE to propagate to your MGM API application.
3.2.3.4. ndb_mgm_destroy_handle()
Description. This function destroys a management server handle
Signature.
void ndb_mgm_destroy_handle
(
NdbMgmHandle* handle
)
3.2.4.1. ndb_mgm_get_connectstring()
Description. This function retrieves the connectstring used for a connection.
Note
This function returns the default connectstring if no call to ndb_mgm_set_connectstring() has been performed. In
addition, the returned connectstring may be formatted slightly differently than the original in that it may contain specifiers
not present in the original.
The connectstring format is the same as that discussed for Section 3.2.4.9, ndb_mgm_set_connectstring().
Signature.
const char* ndb_mgm_get_connectstring
(
NdbMgmHandle handle,
char*
buffer,
int
size
)
An NdbMgmHandle.
287
Return value. The connectstring this is the same value that is pushed to the buffer.
3.2.4.2. ndb_mgm_get_configuration_nodeid()
Description. This function gets the ID of the node to which the connection is being (or was) made.
Signature.
int ndb_mgm_get_configuration_nodeid
(
NdbMgmHandle handle
)
3.2.4.3. ndb_mgm_get_connected_port()
Description. This function retrieves the number of the port used by the connection.
Signature.
int ndb_mgm_get_connected_port
(
NdbMgmHandle handle
)
Parameters. An NdbMgmHandle.
Return value. A port number.
3.2.4.4. ndb_mgm_get_connected_host()
Description. This function is used to obtain the name of the host to which the connection is made.
Signature.
const char* ndb_mgm_get_connected_host
(
NdbMgmHandle handle
)
3.2.4.5. ndb_mgm_is_connected()
Description. Used to determine whether a connection has been established.
Note
This function does not determine whether or not there is a live management server at the other end of the connection.
Beginning with MySQL 5.1.17, you can use ndb_mgm_check_connection() to accomplish that task. See Section 3.2.4.6, ndb_mgm_check_connection(), for more information.
Signature.
int ndb_mgm_is_connected
(
NdbMgmHandle handle
288
Any nonzero value: A connection has been established with the management node.
3.2.4.6. ndb_mgm_check_connection()
Description. This function can be used to determine whether a management server is running on a given connection from a management client.
Prior to MySQL 5.1.17, this function was available but required extremely large timeouts to be configured for it to be effective.
Signature.
int ndb_mgm_check_connection
(
NdbMgmHandle handle
)
3.2.4.7. ndb_mgm_number_of_mgmd_in_connect_string()
Description. This is a convenience function which provides an easy way to determine the number of management servers referenced in
a connectstring as set using ndb_mgm_set_connectstring().
This function was added in MySQL 5.1.18.
Signature.
int ndb_mgm_number_of_mgmd_in_connect_string
(
NdbMgmHandle handle
)
3.2.4.8. ndb_mgm_set_bindaddress()
Description. This function allows you to set a local bind address for the management server. If used, it must be called before connecting to the management server.
This function was added in MySQL 5.1.18.
Signature.
int ndb_mgm_set_bindaddress
(
NdbMgmHandle handle,
const char* address
)
0 indicates success
Any nonzero value indicates failure (the address was not valid)
Important
Errors caused by binding an otherwise valid local address are not reported until the connection to the management is actually attempted.
3.2.4.9. ndb_mgm_set_connectstring()
Description. This function is used to set the connectstring for a management server connection to a node.
Signature.
int ndb_mgm_set_connectstring
(
NdbMgmHandle handle,
const char* connectstring
)
(It is possible to establish connections with multiple management servers using a single connectstring.)
nodeid-specification := nodeid=id
host-specification := host[:port]
3.2.4.10. ndb_mgm_set_configuration_nodeid()
Description. This function sets the connection node ID.
Signature.
int ndb_mgm_set_configuration_nodeid
(
NdbMgmHandle handle,
int
id
)
290
An NdbMgmHandle.
3.2.4.11. ndb_mgm_set_timeout()
Description. Normally, network operations time out after 60 seconds. This function allows you to vary this time.
This function was introduced in MySQL 5.1.18.
Signature.
int ndb_mgm_set_timeout
(
NdbMgmHandle handle,
unsigned int timeout
)
Note
The timeout must be an even multiple of 1000 that is, it must be equivalent to an integral number of seconds. Fractional seconds are not supported.
Return value. Returns 0 on success, with any other value representing failure.
3.2.4.12. ndb_mgm_connect()
Description. This function establishes a connection to a management server specified by the connectstring set by Section 3.2.4.9,
ndb_mgm_set_connectstring().
Signature.
int ndb_mgm_connect
(
NdbMgmHandle handle,
int
retries,
int
delay,
int
verbose
)
The number of retries to make when attempting to connect. 0 for this value means that one connection attempt is made.
3.2.4.13. ndb_mgm_disconnect()
291
Parameters. An NdbMgmHandle.
Return value. Returns -1 if unable to disconnect.
3.2.5.1. ndb_mgm_get_status()
Description. This function is used to obtain the status of the nodes in a MySQL Cluster.
Note
The caller must free the pointer returned by this function.
Signature.
struct ndb_mgm_cluster_state* ndb_mgm_get_status
(
NdbMgmHandle handle
)
3.2.5.2. ndb_mgm_dump_state()
Description. This function can be used to dump debugging information to the cluster log. The MySQL Cluster management client
DUMP command is a wrapper for this function.
Important
ndb_mgm_dump_state(), like the DUMP command, can cause a running MySQL Cluster to malfunction or even to
fail completely if it is used improperly. Be sure to consult the relevant documentation before using this function. For more
information on the DUMP command, and for a listing of current DUMP codes and their effects, see Section 6.2, DUMP
Commands.
This function became available in MySQL Cluster NDB 6.1.2.17 and MySQL Cluster NDB 6.3.19.
Signature.
int ndb_mgm_dump_state
(
NdbMgmHandle handle,
int nodeId,
const int* arguments,
int numberOfArguments,
struct ndb_mgm_reply* reply
)
292
An array of arguments. The first of these is the DUMP code to be executed. Subsequent arguments can be passed in this array if
needed by or desired for the corresponding DUMP command.
An ndb_mgm_reply which cntains a return code along with a response or error message (see Section 3.4.4, The
ndb_mgm_reply Structure, for more information).
3.2.6.1. ndb_mgm_start()
Description. This function can be used to start one or more Cluster nodes. The nodes to be started must have been started with the nostart option (-n), meaning that the data node binary was started and is waiting for a START management command which actually enables the node.
Signature.
int ndb_mgm_start
(
NdbMgmHandle handle,
int
number,
const int*
list
)
An NdbMgmHandle.
A number of nodes to be started. Use 0 to start all of the data nodes in the cluster.
293
Return value. The number of nodes actually started; in the event of failure, -1 is returned.
3.2.6.2. ndb_mgm_stop()
Description. This function stops one or more data nodes.
Signature.
int ndb_mgm_stop
(
NdbMgmHandle handle,
int
number,
const int*
list
)
An NdbMgmHandle.
The number of nodes to be stopped. Use 0 to stop all of the data nodes in the cluster.
Calling this function is equivalent to calling ndb_mgm_stop2(handle, number, list, 0). See Section 3.2.6.3,
ndb_mgm_stop2().
Return value. The number of nodes actually stopped; in the event of failure, -1 is returned.
3.2.6.3. ndb_mgm_stop2()
Description. Like ndb_mgm_stop(), this function stops one or more data nodes. However, it offers the ability to specify whether or
not the nodes shut down gracefully.
Signature.
int ndb_mgm_stop2
(
NdbMgmHandle
int
const int*
int
)
handle,
number,
list,
abort
An NdbMgmHandle.
The number of nodes to be stopped. Use 0 to stop all of the data nodes in the cluster.
The value of abort determines how the nodes will be shut down. 1 indicates the nodes will shut down immediately; 0 indicates
that the nodes will stop gracefully.
Return value. The number of nodes actually stopped; in the event of failure, -1 is returned.
3.2.6.4. ndb_mgm_stop3()
Description. Like ndb_mgm_stop() and ndb_mgm_stop2(), this function stops one or more data nodes. Like
ndb_mgm_stop2(), it offers the ability to specify whether the nodes should shut down gracefully. In addition, it provides for a way
to check to see whether disconnection is required prior to stopping a node.
Signature.
int ndb_mgm_stop3
294
(
NdbMgmHandle
int
const int*
int
int*
handle,
number,
list,
abort,
disconnect
An NdbMgmHandle.
The number of nodes to be stopped. Use 0 to stop all of the data nodes in the cluster.
The value of abort determines how the nodes will be shut down. 1 indicates the nodes will shut down immediately; 0 indicates
that the nodes will stop gracefully.
If disconnect returns 1 (true), this means the you must disconnect before you can apply the command to stop. For example,
disconnecting is required when stopping the management server to which the handle is connected.
Return value. The number of nodes actually stopped; in the event of failure, -1 is returned.
3.2.6.5. ndb_mgm_restart()
Description. This function can be used to restart one or more Cluster data nodes.
Signature.
int ndb_mgm_restart
(
NdbMgmHandle handle,
int
number,
const int*
list
)
An NdbMgmHandle.
The number of nodes to be stopped. Use 0 to stop all of the data nodes in the cluster.
3.2.6.6. ndb_mgm_restart2()
Description. Like ndb_mgm_restart(), this function can be used to restart one or more Cluster data nodes. However,
ndb_mgm_restart2() provides additional restart options, including initial restart, waiting start, and immediate (forced) restart.
Signature.
int ndb_mgm_restart2
(
NdbMgmHandle handle,
int
number,
const int*
list,
int
initial
int
nostart,
int
abort
295
An NdbMgmHandle.
The number of nodes to be stopped. Use 0 to stop all of the data nodes in the cluster.
If initial is true (1), then each node undergoes an initial restart that is, its file system is removed.
If nostart is true, then the nodes are not actually started, but instead are left ready for a start command.
If abort is true, then the nodes are restarted immediately, bypassing any graceful restart.
3.2.6.7. ndb_mgm_restart3()
Description. Like ndb_mgm_restart2(), this function can be used to cause an initial restart, waiting restart, and immediate
(forced) restart on one or more Cluster data nodes. However, ndb_mgm_restart3() provides additional the additional options of
checking whether disconnection is required prior to the restart.
Signature.
int ndb_mgm_restart3
(
NdbMgmHandle handle,
int
number,
const int*
list,
int
initial
int
nostart,
int
abort,
int*
disconnect
)
An NdbMgmHandle.
The number of nodes to be stopped. Use 0 to stop all of the data nodes in the cluster.
If initial is true (1), then each node undergoes an initial restart that is, its file system is removed.
If nostart is true, then the nodes are not actually started, but instead are left ready for a start command.
If abort is true, then the nodes are forced to restart immediately without performing a graceful restart.
If disconnect returns 1 (true), this means the you must disconnect before you can apply the command to restart. For example,
disconnecting is required when stopping the management server to which the handle is connected.
3.2.7.1. ndb_mgm_get_clusterlog_severity_filter()
Description. This function is used to retrieve the cluster log severity filter currently in force.
296
Important
The parameters and return type of this function changed significantly between MySQL 5.1.13 and 5.1.14. The changes are
detailed in the Signature, Parameters, and Return Type sections that follow.
These changes were done in order to make this function thread-safe. The pre-5.1.14 version is still supported for backward
compatibility, but you should protect it with a mutex if you intend to call it from more than one thread.
Signature. As of MySQL 5.1.14:
int ndb_mgm_get_clusterlog_severity_filter
(
NdbMgmHandle handle,
struct ndb_mgm_severity* severity,
unsigned int size
)
In MySQL 5.1.13 and earlier, this function took only a single parameter, as shown here:
const unsigned int* ndb_mgm_get_clusterlog_severity_filter
(
NdbMgmHandle handle
)
Return value. This function's return type changed beginning with MySQL 5.1.14.
3.2.7.2. ndb_mgm_set_clusterlog_severity_filter()
Description. This function is used to set a cluster log severity filter.
Signature.
int ndb_mgm_set_clusterlog_severity_filter
(
NdbMgmHandle
handle,
enum ndb_mgm_event_severity severity,
int
enable,
struct ndb_mgm_reply*
reply
297
A flag to enable or disable the filter; 1 enables and 0 disables the filter.
A pointer to an ndb_mgm_reply structure for a reply message. See Section 3.4.4, The ndb_mgm_reply Structure.
3.2.7.3. ndb_mgm_get_clusterlog_loglevel()
Description. This function, added in MySQL 5.1.16, is used to obtain log category and level information. It replaces the older
ndb_mgm_get_loglevel_clusterlog() function, which performed the same purpose, but was not thread-safe. (See later in
this section for a brief description of the deprecated version of the function.)
Signature.
int ndb_mgm_get_clusterlog_loglevel
(
NdbMgmHandle handle,
struct ndb_mgm_loglevel* loglevel,
unsigned int size
)
A loglevel (log level) vector consisting of twelve elements, each of which is an ndb_mgm_loglevel structure and which represents a log level of the corresponding category.
Return value. This function returns the number of returned loglevels or -1 in the event of an error.
Note
Prior to MySQL 5.1.14, this function was known as ndb_mgm_get_loglevel_clusterlog(), and had the following signature:
const unsigned int* ndb_mgm_get_loglevel_clusterlog
(
NdbMgmHandle handle
)
This version of the function is now deprecated, but is still available for backward compatibility; however, in new applications, it is recommended that you use ndb_mgm_get_clusterlog_loglevel(), since it is thread-safe, and the
older function is not.
3.2.7.4. ndb_mgm_set_clusterlog_loglevel()
Description. This function is used to set the log category and levels for the cluster log.
Signature.
int ndb_mgm_set_clusterlog_loglevel
(
NdbMgmHandle
handle,
int
id,
enum ndb_mgm_event_category category,
int
level,
298
struct ndb_mgm_reply*
reply)
An NdbMgmHandle.
An event category this is one of the values listed in Section 3.3.7, The ndb_mgm_event_category Type .
A logging level.
A pointer to an ndb_mgm_reply structure for the reply message. (See Section 3.4.4, The ndb_mgm_reply Structure.)
3.2.8.1. ndb_mgm_start_backup()
Description. This function is used to initiate a backup of a MySQL Cluster.
Signature.
int ndb_mgm_start_backup
(
NdbMgmHandle
int
unsigned int*
struct ndb_mgm_reply*
)
handle,
wait,
id,
reply
Note
No backup id is returned if wait is set equal to 0.
A pointer to an ndb_mgm_reply structure to accommodate a reply. See Section 3.4.4, The ndb_mgm_reply Structure.
3.2.8.2. ndb_mgm_abort_backup()
Description. This function is used to stop a Cluster backup.
Signature.
int ndb_mgm_abort_backup
(
299
NdbMgmHandle
handle,
unsigned int
id,
struct ndb_mgm_reply* reply)
An NdbMgmHandle.
3.2.9.1. ndb_mgm_enter_single_user()
Description. This function is used to enter single-user mode on a given node.
Signature.
int ndb_mgm_enter_single_user
(
NdbMgmHandle
handle,
unsigned int
id,
struct ndb_mgm_reply* reply
)
An NdbMgmHandle.
3.2.9.2. ndb_mgm_exit_single_user()
Description. This function is used to exit single-user mode and to return to normal operation.
Signature.
int ndb_mgm_exit_single_user
(
NdbMgmHandle
handle,
struct ndb_mgm_reply* reply
)
An NdbMgmHandle.
A pointer to an ndb_mgm_reply.
Note
The types described in this section are all defined in the file /storage/ndb/include/mgmapi/mgmapi.h, with
the exception of Ndb_logevent_type, ndb_mgm_event_severity, ndb_mgm_logevent_handle_error,
and ndb_mgm_event_category, which are defined in /storage/ndb/include/mgmapi/ndb_logevent.h.
Description
NDB_MGM_NODE_TYPE_UNKNOWN
Unknown
NDB_MGM_NODE_TYPE_API
NDB_MGM_NODE_TYPE_NDB
Data node
NDB_MGM_NODE_TYPE_MGM
Management node
Description
NDB_MGM_NODE_STATUS_UNKNOWN
NDB_MGM_NODE_STATUS_NO_CONTACT
NDB_MGM_NODE_STATUS_NOT_STARTED
NDB_MGM_NODE_STATUS_STARTING
NDB_MGM_NODE_STATUS_STARTED
NDB_MGM_NODE_STATUS_SHUTTING_DOWN
NDB_MGM_NODE_STATUS_RESTARTING
NDB_MGM_NODE_STATUS_SINGLEUSER
NDB_MGM_NODE_STATUS_RESUME
301
Category
Type
Description
(Connection events)
NDB_MGM_EVENT_CATEGORY_CONNECTI
ON
NDB_LE_Connected
NDB_LE_Disconnected
NDB_LE_CommunicationClosed
NDB_LE_CommunicationOpened
NDB_LE_ConnectedApiVersion
NDB_MGM_EVENT_CATEGORY_CHECKPOI
NT
NDB_LE_GlobalCheckpointStarted
NDB_LE_LCPFragmentCompleted
NDB_MGM_EVENT_CATEGORY_STARTUP
NDB_LE_NDBStartStarted
NDB_LE_NDBStartCompleted
NDB_LE_STTORRYRecieved
NDB_LE_StartPhaseCompleted
NDB_LE_CM_REGCONF
NDB_LE_CM_REGREF
NDB_LE_FIND_NEIGHBOURS
NDB_LE_NDBStopStarted
NDB_LE_NDBStopCompleted
NDB_LE_NDBStopForced
NDB_LE_NDBStopAborted
302
Category
Type
Description
pens, for example, when a STOP command was issued in the management
client for a node such that the cluster
would no longer be able to keep all
data available if the node were shut
down
NDB_LE_StartREDOLog
NDB_LE_StartLog
NDB_LE_UNDORecordsExecuted
The node has read and executed all records from the redo log
NDB_LE_StartReport
NDB_MGM_EVENT_CATEGORY_NODE_RES
TART
NDB_LE_NR_CopyDict
NDB_LE_NR_CopyDistr
NDB_LE_NR_CopyFragsStarted
NDB_LE_NR_CopyFragDone
NDB_LE_NR_CopyFragsCompleted
NDB_MGM_EVENT_CATEGORY_NODE_RES
TART
NDB_LE_NodeFailCompleted
NDB_LE_NODE_FAILREP
NDB_LE_ArbitState
This event is used to report on the current state of arbitration in the cluster
NDB_LE_ArbitResult
NDB_LE_GCP_TakeoverStarted
NDB_LE_GCP_TakeoverCompleted
NDB_LE_LCP_TakeoverStarted
NDB_LE_LCP_TakeoverCompleted
NDB_MGM_EVENT_CATEGORY_STATISTI
C
NDB_LE_TransReportCounters
NDB_LE_OperationReportCounters
NDB_LE_TableCreated
NDB_LE_UndoLogBlocked
303
Category
Type
Description
NDB_LE_JobStatistic
NDB_LE_SendBytesStatistic
Indicates a report of the average number of bytes transmitted per send operation by this node
NDB_LE_ReceiveBytesStatistic
Indicates a report of the average number of bytes received per send operation to this node
NDB_LE_MemoryUsage
A DUMP 1000 command has been issued to this node, and it is reporting its
memory usage in turn
(Errors and warnings)
NDB_MGM_EVENT_CATEGORY_ERROR
NDB_LE_TransporterError
NDB_LE_TransporterWarning
NDB_LE_MissedHeartbeat
NDB_LE_DeadDueToHeartbeat
A data node has missed at least 3 heartbeats in succssion from another data
node, and is reporting that it can no
longer communicate with that data
node
NDB_LE_WarningEvent
NDB_MGM_EVENT_CATEGORY_INFO
NDB_LE_SentHeartbeat
NDB_LE_CreateLogBytes
[Single-User Mode]
NDB_LE_InfoEvent
NDB_LE_SingleUser
NDB_LE_EventBufferStatus
NDB_MGM_EVENT_CATEGORY_BACKUP
NDB_LE_BackupStarted
NDB_LE_BackupFailedToStart
NDB_LE_BackupCompleted
NDB_LE_BackupAborted
304
Value
Description
NDB_MGM_ILLEGAL_EVENT_SEVERITY
NDB_MGM_EVENT_SEVERITY_ON
NDB_MGM_EVENT_SEVERITY_DEBUG
NDB_MGM_EVENT_SEVERITY_INFO
Informational messages
NDB_MGM_EVENT_SEVERITY_WARNING
Conditions that are not errors as such, but that might require special handling
NDB_MGM_EVENT_SEVERITY_ERROR
NDB_MGM_EVENT_SEVERITY_CRITICAL
NDB_MGM_EVENT_SEVERITY_ALERT
NDB_MGM_EVENT_SEVERITY_ALL
Description
NDB_LEH_NO_ERROR
No error
NDB_LEH_READ_ERROR
Read error
NDB_LEH_MISSING_EVENT_SPECIFIER
NDB_LEH_UNKNOWN_EVENT_TYPE
NDB_LEH_UNKNOWN_EVENT_VARIABLE
NDB_LEH_INTERNAL_ERROR
Internal error
Description
NDB_MGM_ILLEGAL_EVENT_CATEGORY
NDB_MGM_EVENT_CATEGORY_STARTUP
NDB_MGM_EVENT_CATEGORY_SHUTDOWN
NDB_MGM_EVENT_CATEGORY_STATISTIC
NDB_MGM_EVENT_CATEGORY_CHECKPOINT
NDB_MGM_EVENT_CATEGORY_NODE_RESTART
NDB_MGM_EVENT_CATEGORY_CONNECTION
NDB_MGM_EVENT_CATEGORY_BACKUP
NDB_MGM_EVENT_CATEGORY_CONGESTION
NDB_MGM_EVENT_CATEGORY_INFO
NDB_MGM_EVENT_CATEGORY_ERROR
void* handle: An NdbLogEventHandle, set by ndb_logevent_get_next(). This handle is used only for purposes of
comparison.
See Section 3.2.1.5, ndb_logevent_get_next().
unsigned time: The time at which the log event was registered with the management server.
unsigned level: The log event level. This is a value in the range of 0 to 15, inclusive.
unsigned source_nodeid: The node ID of the node that reported this event.
The 8th member of this structure contains data specific to the log event, and is dependent on its type. It is defined as the union of a number of data structures, each corresponding to a log event type. Which structure to use is determined by the value of type, and is shown
in the following table:
Ndb_logevent_type Value
Structure
NDB_LE_Connected
Connected:
unsigned node
NDB_LE_Disconnected
Disconnected:
unsigned node
NDB_LE_CommunicationClosed
CommunicationClosed:
unsigned node
NDB_LE_CommunicationOpened
CommunicationOpened:
unsigned node
NDB_LE_ConnectedApiVersion
ConnectedApiVersion:
unsigned node
unsigned version
NDB_LE_GlobalCheckpointStarted
GlobalCheckpointStarted:
unsigned gci
306
Ndb_logevent_type Value
Structure
NDB_LE_GlobalCheckpointCompleted
GlobalCheckpointCompleted:
unsigned gci
NDB_LE_LocalCheckpointStarted
LocalCheckpointStarted:
unsigned lci
unsigned keep_gci
unsigned restore_gci
NDB_LE_LocalCheckpointCompleted
LocalCheckpointCompleted:
unsigned lci
NDB_LE_LCPStoppedInCalcKeepGci
LCPStoppedInCalcKeepGci:
unsigned data
NDB_LE_LCPFragmentCompleted
LCPFragmentCompleted:
unsigned node
unsigned table_id
unsigned fragment_id
NDB_LE_UndoLogBlocked
UndoLogBlocked:
unsigned acc_count
unsigned tup_count
NDB_LE_NDBStartStarted
NDBStartStarted:
unsigned version
NDB_LE_NDBStartCompleted
NDBStartCompleted:
unsigned version
NDB_LE_STTORRYRecieved
STTORRYRecieved:
[NONE]
NDB_LE_StartPhaseCompleted
StartPhaseCompleted:
unsigned phase
unsigned starttype
NDB_LE_CM_REGCONF
CM_REGCONF:
unsigned own_id
unsigned president_id
unsigned dynamic_id
NDB_LE_CM_REGREF
CM_REGREF:
unsigned own_id
unsigned other_id
unsigned cause
NDB_LE_FIND_NEIGHBOURS
FIND_NEIGHBOURS:
unsigned
unsigned
unsigned
unsigned
NDB_LE_NDBStopStarted
own_id
left_id
right_id
dynamic_id
NDBStopStarted:
unsigned stoptype
307
Ndb_logevent_type Value
Structure
NDB_LE_NDBStopCompleted
NDBStopCompleted:
unsigned action
unsigned signum
NDB_LE_NDBStopForced
NDBStopForced:
unsigned
unsigned
unsigned
unsigned
unsigned
NDB_LE_NDBStopAborted
action
signum
error
sphase
extra
NDBStopAborted:
[NONE]
NDB_LE_StartREDOLog
StartREDOLog:
unsigned
unsigned
unsigned
unsigned
NDB_LE_StartLog
node
keep_gci
completed_gci
restorable_gci
StartLog:
unsigned
unsigned
unsigned
unsigned
NDB_LE_UNDORecordsExecuted
log_part
start_mb
stop_mb
gci
UNDORecordsExecuted:
unsigned
unsigned
unsigned
unsigned
unsigned
unsigned
unsigned
unsigned
unsigned
unsigned
unsigned
NDB_LE_NR_CopyDict
block
data1
data2
data3
data4
data5
data6
data7
data8
data9
data10
NR_CopyDict:
[NONE]
NDB_LE_NR_CopyDistr
NR_CopyDistr:
[NONE]
NDB_LE_NR_CopyFragsStarted
NR_CopyFragsStarted:
unsigned dest_node
NDB_LE_NR_CopyFragDone
NR_CopyFragDone:
unsigned dest_node
unsigned table_id
unsigned fragment_id
NDB_LE_NR_CopyFragsCompleted
NR_CopyFragsCompleted:
unsigned dest_node
NDB_LE_NodeFailCompleted
NodeFailCompleted:
unsigned block
unsigned failed_node
308
Ndb_logevent_type Value
Structure
unsigned completing_node
NODE_FAILREP:
unsigned failed_node
unsigned failure_state
NDB_LE_ArbitState
ArbitState:
unsigned
unsigned
unsigned
unsigned
NDB_LE_ArbitResult
code
arbit_node
ticket_0
ticket_1
ArbitResult:
unsigned
unsigned
unsigned
unsigned
NDB_LE_GCP_TakeoverStarted
code
arbit_node
ticket_0
ticket_1
GCP_TakeoverStarted:
[NONE]
NDB_LE_GCP_TakeoverCompleted
GCP_TakeoverCompleted:
[NONE]
NDB_LE_LCP_TakeoverStarted
LCP_TakeoverStarted:
[NONE]
NDB_LE_TransReportCounters
TransReportCounters:
unsigned
unsigned
unsigned
unsigned
unsigned
unsigned
unsigned
unsigned
unsigned
unsigned
NDB_LE_OperationReportCounters
trans_count
commit_count
read_count
simple_read_count
write_count
attrinfo_count
conc_op_count
abort_count
scan_count
range_scan_count
OperationReportCounters:
unsigned ops
NDB_LE_TableCreated
TableCreated:
unsigned table_id
NDB_LE_JobStatistic
JobStatistic:
unsigned mean_loop_count
NDB_LE_SendBytesStatistic
SendBytesStatistic:
unsigned to_node
unsigned mean_sent_bytes
NDB_LE_ReceiveBytesStatistic
ReceiveBytesStatistic:
unsigned from_node
unsigned mean_received_bytes
NDB_LE_MemoryUsage
MemoryUsage:
309
Ndb_logevent_type Value
Structure
int
unsigned
unsigned
unsigned
unsigned
NDB_LE_TransporterError
gth
page_size_kb
pages_used
pages_total
block
TransporterError:
unsigned to_node
unsigned code
NDB_LE_TransporterWarning
TransporterWarning:
unsigned to_node
unsigned code
NDB_LE_MissedHeartbeat
MissedHeartbeat:
unsigned node
unsigned count
NDB_LE_DeadDueToHeartbeat
DeadDueToHeartbeat:
unsigned node
NDB_LE_WarningEvent
WarningEvent:
[NOT YET IMPLEMENTED]
NDB_LE_SentHeartbeat
SentHeartbeat:
unsigned node
NDB_LE_CreateLogBytes
CreateLogBytes:
unsigned node
NDB_LE_InfoEvent
InfoEvent:
[NOT YET IMPLEMENTED]
NDB_LE_EventBufferStatus
EventBufferStatus:
unsigned
unsigned
unsigned
unsigned
unsigned
unsigned
unsigned
NDB_LE_BackupStarted
usage
alloc
max
apply_gci_l
apply_gci_h
latest_gci_l
latest_gci_h
BackupStarted:
unsigned starting_node
unsigned backup_id
NDB_LE_BackupFailedToStart
BackupFailedToStart:
unsigned starting_node
unsigned error
NDB_LE_BackupCompleted
BackupCompleted:
unsigned
unsigned
unsigned
unsigned
unsigned
unsigned
unsigned
unsigned
310
starting_node
backup_id
start_gci
stop_gci
n_records
n_log_records
n_bytes
n_log_bytes
Ndb_logevent_type Value
Structure
NDB_LE_BackupAborted
BackupAborted:
unsigned starting_node
unsigned backup_id
unsigned error
NDB_LE_SingleUser
SingleUser:
unsigned type
unsigned node_id
NDB_LE_StartReport
StartReport:
unsigned
unsigned
unsigned
unsigned
report_type
remaining_time
bitmask_size
bitmask_data[1]
int connect_count: The number of times this node has connected to or disconnected from the management server.
char connect_address[]: The IP address of the node when it connected to the management server.
This value will be empty if the management server has been restarted since the node last connected.
311
int return_code: For a successful operation, this value is 0; otherwise, it contains an error code.
For error codes, see Section 3.3.3, The ndb_mgm_error Type.
312
Important
MySQL Cluster Connector for Java is currently considered beta quality software, indicating that it is appropriate for use
with new development, and that its features and compatibility should remain consistent. However, as with all beta releases,
MySQL Cluster Connector for Java may contain numerous and major unaddressed bugs. Although MySQL Cluster Connector for Java is feature-complete, some implementation details may change prior to a final release; thus, this documentation is currently also subject to change without notice.
JDBC and mysqld. JDBC works by sending SQL statements to the MySQL Server and returning result sets. When using JDBC,
you must write the SQL, manage the connection, and copy any data from the result set that you want to use in your program as objects. The JDBC implementation most often used with the MySQL Server is MySQL Connector/J.
Java Persistence API (JPA) and JDBC. JPA uses JDBC to connect to the MySQL Server. Unlike JDBC, JPA provides an object
view of the data in the database.
ClusterJ. ClusterJ uses a JNI bridge to the NDB API for direct access to NDBCLUSTER. It employs a style of data access that is
based on a domain object model, similar in many ways to that employed by JPA. ClusterJ does not depend on the MySQL Server
for data access.
ClusterJPA. ClusterJPA is an adapter for the OpenJPA implementation. It can use either of two different access paths JDBC or
ClusterJ to MySQL Cluster data, depending on the type of operation to be performed. This can significantly improve performance for some uses, bypassing SQL, JDBC, and the MySQL Server entirely when it is more efficient to do so.
313
JDBC and mysqld. Connector/J provides standard access via the MySQL JDBC driver. Using Connector/J, JDBC applications can
be written to work with a MySQL server acting as a MySQL Cluster SQL node in much the same way that other Connector/J applications work with any other MySQL Server instance.
For more information, see Section 4.2.4, Using Connector/J with MySQL Cluster.
ClusterJ. ClusterJ is a native Java Connector for NDBCLUSTER (or NDB), the storage engine for MySQL Cluster, in the style of Hibernate, JPA, and JDO. Like other persistence frameworks, ClusterJ uses the Data Mapper pattern, in which data is represented as domain objects, separate from business logic, mapping Java classes to database tables stored in the NDBCLUSTER storage engine.
Note
The NDBCLUSTER storage engine is often referred to (in MySQL documentation and elsewhere) simply as NDB. The
terms NDB and NDBCLUSTER are synonymous, and you can use either ENGINE=NDB or ENGINE=NDBCLUSTER in a
314
ClusterJPA supports persistent classes, whereas ClusterJ only supports persistent interfaces.
ClusterJPA supports relationships between persistent classes (typically modeled as logical foreign keys), whereas ClusterJ only supports single-valued fields directly mapped to database columns.
ClusterJPA allows you to formulate queries that contain joins based on relationships in the domain object model, while ClusterJ
does not support either relationships or joins.
However, once you retrieve instances using a JPA query, you can update or delete these via the fast path of ClusterJ.
ClusterJPA allows you to use the JPA API to declare some fields as lazily loaded, meaning that the data is only brought into
memory when your program actually references it. ClusterJ, however, reads all mapped columns from the table whenever you access a row.
SessionFactory interface. Sessions are obtained from a SessionFactory, of which there is typically a single instance for each
MySQL Cluster that you want to access from the Java VM. SessionFactory stores configuration information about the cluster,
such as the hostname and port number of the MySQL Cluster management server. It also stores parameters regarding how to connect to
the cluster, including connection delays and timeouts. For more information about SessionFactory and its use in a ClusterJ application,
see Getting the SessionFactory and getting a Session.
Transaction interface. Transactions are not managed by the Session interface; like other modern application frameworks,
ClusterJ separates transaction management from other persistence methods. Transaction demarcation might be done automatically by a
container or in a web server servlet filter. Removing transaction completion methods from Session facilitates this separation of concerns.
315
The Transaction interface supports the standard begin, commit, and rollback behaviors required by a transactional database. In addition, it allows the user to mark a transaction as being rollback-only, which makes it possible for a component that is not responsible
for completing a transaction to indicate that due to an application or database error the transaction must not be allowed to complete normally.
QueryBuilder interface. The QueryBuilder interface allows users to construct criteria queries dynamically, using domain object model properties as query modeling elements. Comparisons between parameters and database column values can be specified, including equal, greater and less than, between, and in operations. These comparisons can be combined using methods corresponding to
the Boolean operators AND, OR, and NOT. Comparison of values to NULL is also supported.
Data model. ClusterJ provides access to data in MySQL Cluster using domain objects, similar in many ways to the way that JPA models data.
In ClusterJ, the domain object mapping has the following characteristics:
All tables map to persistent interfaces. For every NDB table in the cluster, ClusterJ uses one or more interfaces. In many cases, a
single interface is used; but for cases where different columns are needed by different parts of the application, multiple interfaces
can be mapped to the same table.
However, the classes themselves are not persistent.
Users map a subset of columns to persistent properties in interfaces. Thus, all properties map to columns; however, not all columns
necessarily map to properties.
All ClusterJ property names default to column names. The interface provides getter and setter methods for each property, with predictable corresponding method names.
The user view of the application environment and domain objects is illustrated in the following diagram, which shows the logical relationships among the modeling elements of the ClusterJ interfaces:
The SessionFactory is configured by a properties object that might have been loaded from a file or constructed dynamically by the
316
application via some other means (see Section 4.2.2.1, Executing ClusterJ Applications and Sessions).
The application obtains Session instances from the SessionFactory, with at most one thread working with a Session at a time.
A thread can manage multiple Session instances if there is some application requirement for multiple connections to the database.
Each session has its own collection of domain objects, each of which represents the data from one row in the database. The domain objects can represent data in any of the following states:
4.2.1. Getting, Installing, and Setting Up MySQL Cluster Connector for Java
This section discusses how to obtain MySQL Cluster Connector for Java sources, binaries, compiling, installing, getting started.
Obtaining MySQL Cluster Connector for Java. You can obtain the most recent MySQL Cluster NDB 7.1 or later source or binary
release incorporating MySQL Cluster Connector for Java from downloads.mysql.com.
Building and installing MySQL Cluster Connector for Java from source. You can build and install ClusterJ, ClusterJPA, or both as
part of building and installing MySQL Cluster, which always requires you to configure the build using an option that causes NDB support to be included, such as --with-ndbcluster or --with-plugins=max. Other relevant configure options include the
following:
--with-classpath=path: Required for building MySQL Cluster with ClusterJPA support. path must include the path or
paths to the OpenJPA libraries and OpenJPA dependencies on your system.
--with-extra-charsets: ClusterJ uses the ucs2 character set for internal storage, and ClusterJ cannot be built without it.
The simplest way to ensure that this character set is available is to configure using --with-extra-charsets=all. This is
what we recommend that you use, unless you have some reason for not wanting to include all character sets, in which case you
should make sure that ucs2 is specified in the character set list passed to this option.
A typical configuration step in building MySQL Cluster with support for both ClusterJ and ClusterJPA might look like this:
shell> ./configure --with-extra-charsets=all --with-plugins=ndbcluster \
--with-clusterj --with-openjpa --with-classpath=path/to/openjpa/libs \
--prefix=path/to/install/directory
openjpa-1.2.0.jar
geronimo-jta_1.1_spec-1.1.jar
geronimo-jpa_3.0_spec-1.0.jar
serp-1.13.1.jar
317
commons-lang-2.1.jar
commons-collections-3.2.jar
Note
Not all available options for configuring a MySQL Cluster build are shown in this section. For information about other options that can be used, see Installing from the Development Source Tree.
After configuring the build, run make and make install as you normally would to compile and install the MySQL Cluster software. Following installation, the MySQL Cluster Connector for Java jar files can be found in share/mysql/java under the MySQL
installation directory (by default, this is /usr/local/mysql/share/mysql/java).
You can also use the included file storage/ndb/clusterj/pom.xml for building ClusterJ with Maven.
MySQL Cluster Connector for Java jar files. After building and installing MySQL Cluster with MySQL Cluster Connector for Java,
you should find the following JAR files that are needed for using ClusterJ and ClusterJPA in share/mysql/java/ under the
MySQL Cluster installation directory:
clusterj-api.jar: This is the compile-time jar file, required for compiling ClusterJ application code.
clusterj.jar: This is the runtime library required for executing ClusterJ applications.
clusterjpa.jar: This is the runtime library required for executing ClusterJPA applications. This jar file must be in your
classpath when running OpenJPA with ClusterJPA.
Note
The requirements for running ClusterJ applications were somewhat different in MySQL Cluster NDB 7.1.1; see Building
and executing ClusterJ applications in MySQL Cluster NDB 7.1.1, if you are using this release.
318
Note
The precise locations of the ClusterJ jar files and of libndbclient depend on how the MySQL Cluster software was
installed. See Installation Layouts, for more information.
ClusterJ encourages you to use different jar files at compile time and run time. This is to remove the ability of applications to access implementation artifacts accidentally. ClusterJ is intended to be independent of the MySQL Cluster software version, whereas the ndbclient layer is version-specific. This makes it possible to maintain a stable API, so that applications written against it using a given
MySQL Cluster version continue to run following an upgrade of the cluster to a new version.
Building and executing ClusterJ applications in MySQL Cluster NDB 7.1.1. As in later versions, only clusterj-api.jar is
required in your classpath to compile a ClusterJ application. However, in order to run ClusterJ applications in MySQL Cluster NDB
7.1.1, several jar files are needed: clusterj-core.jar, clusterj-tie.jar, jtie.jar, and ndbjtie.jar; in addition,
libndbjtie must be in your java.library.path.
Beginning with MySQL Cluster NDB 7.1.2, the runtime jar files just named have been combined as clusterj.jar, and libndbjtie has been made part of libndbclient.
Getting the SessionFactory and getting a Session. SessionFactory is the source of all ClusterJ sessions that use a given
MySQL Cluster. Usually, there is only a single SessionFactory per MySQL Cluster, per Java Virtual Machine.
SessionFactory can be configured by setting one or more properties. The preferred way to do this is by putting these in a properties file, like this:
com.mysql.clusterj.connectstring=localhost:1186
com.mysql.clusterj.database=mydb
The name of the properties file is arbitrary; howver, by convention, such files are named with a .properties extension. For ClusterJ
applications, it is customary to name the file clusterj.properties.
After editing and saving the file, you can load the its contents into an instance of Properties, as shown here:
File propsFile = new File("clusterj.properties");
InputStream inStream = new FileInputStream(propsFile);
Properties props = new Properties();
props.load(inStream);
It is also possible to set these properties directly, without the use of a properties file:
Properties props = new Properties();
props.put("com.mysql.clusterj.connectstring", "localhost:1186");
props.put("com.mysql.clusterj.database", "mydb");
Once the properties have been set and loaded (using either of the techniques just shown), you can obtain a SessionFactory, and
then from that a Session instance. For this, you use the SessionFactory's getSession() method, as shown here:
SessionFactory factory = ClusterJHelper.getSessionFactory(props);
Session session = factory.getSession();
Note
Session instances must not be shared among threads. Each thread in your application should use its own instance of
Session.
For com.mysql.clusterj.connectstring, we use the default MySQL Cluster connectstring localhost:1186 (see The
MySQL Cluster Connectstring, for more information). For the value of com.mysql.clusterj.database, we use mydb in this
example, but this value can be the name of any database containing NDB tables. For a listing of all SessionFactory properties that
can be set in this manner, see com.mysql.clusterj.Constants.
319
Now that the table has been created in MySQL Cluster, you can map a ClusterJ interface to it using annotations. We show you how to
do this in the next section.
4.2.2.3. Annotations
In ClusterJ (as in JPA), annotations are used to describe how the interface is mapped to tables in a database. An annotated interface
looks like this:
@PersistenceCapable(table="employee")
@Index(name="idx_uhash")
public interface Employee {
@PrimaryKey
int getId();
void setId(int id);
String getFirst();
void setFirst(String first);
String getLast();
void setLast(String last);
@Column(name="municipality")
@Index(name="idx_municipality")
String getCity();
void setCity(String city);
Date getStarted();
void setStarted(Date date);
Date getEnded();
void setEnded(Date date);
Integer getDepartment();
void setDepartment(Integer department);
}
This interface maps seven columns: id, first, last, municipality started, ended, and department. The annotation
@PersistenceCapable(table="employee") is used to let ClusterJ know which database table to map the Employee to (in
this case, the employee table). The @Column annotation is used because the city property name implied by the getCity() and
setCity() methods is different from the mapped column name municipality. The annotations @PrimaryKey and @Index inform ClusterJ about indexes in the database table.
The implementation of this interface is created dynamically by ClusterJ at runtime. When the newInstance() method is called,
ClusterJ creates an implementation class for the Employee interface; this class stores the values in an internal object array.
ClusterJ does not require an annotation for every attribute. ClusterJ automatically detects the primary keys of tables; while there is an
annotation in ClusterJ to allow the user to describe the primary keys of a table (see previous example), when specified, it is currently ignored. (The intended use of this annotation is for the generation of schemas from the domain object model interfaces, but this is not yet
supported.)
The annotations themselves must be imported from the ClusterJ API. They can be found in package
com.mysql.clusterj.annotation, and can be imported like this:
import
import
import
import
com.mysql.clusterj.annotation.Column;
com.mysql.clusterj.annotation.Index;
com.mysql.clusterj.annotation.PersistenceCapable;
com.mysql.clusterj.annotation.PrimaryKey;
320
Creating new instances, setting their properties, and saving them to the database
Constructing and executing queries to fetch a set of rows meeting certain criteria from the database
Creating new rows. To insert a new row into the table, first create a new instance of Employee. This can be accomplished by calling
the Session method newInstance(), as shown here:
Employee newEmployee = session.newInstance(Employee.class);
Set the Employee instance properties corresponding with the desired employee table columns. For example, the following sets the
id, firstName, lastName, and started properties.
emp.setId(988);
newEmployee.setFirstName("John");
newEmployee.setLastName("Jones");
newEmployee.setStarted(new Date());
Once you are satisfied with the changes, you can persist the Employee instance, causing a new row containing the desired values to be
inserted into the employee table, like this:
session.persist(newEmployee);
If the row with the same id as this Employee instance already exists in the database, the persist() method fails. If you want to
save the data even if the row already exists, use the savePersistent() method instead of the persist() method. The
savePersistent() method updates an existing instance or creates a new instance without throwing an exception.
Values that you have not specified are stored with their Java default values (0 for integral types, 0.0 for numeric types, and null for
reference types).
Primary key lookups. You can find an existing row in an NDB table using the Session's find() method, like this:
Employee theEmployee = session.find(Employee.class, 988);
This is equivalent to the primary key lookup query SELECT * FROM employee WHERE id = 988.
ClusterJ also supports compound primary keys. The find() method can take an object array as a key, where the components of the
object array are used to represent the primary key columns in the order they were declared. In addition, queries are optimized to detect
whether columns of the primary key are specified as part of the query criteria, and if so, a primary key lookup or scan is executed as a
strategy to implement the query.
Note
ClusterJ also supports multiple column ordered btree and unique hash indexes. As with primary keys, if a query specifies
values for ordered or unique index fields, ClusterJ optimizes the query to use the index for scanning the table.
MySQL Cluster automatically spreads table data across multiple data nodes. For some operations find, insert, delete,
and update it is more efficient to tell the cluster on which data node the data is physically located, and to have the transaction execute on that data node. ClusterJ automatically detects the partition key; if the operation can be optimized for a
specific data node, ClusterJ automatically starts the transaction on that node.
321
Update and save a row. To update the value of a given column in the row that we just obtained as theEmployee, use the set*()
method whose name corresponds to the name of that column. For example, to update the started date for this Employee, use the
Employee's setStarted() method, as shown here:
theEmployee.setStarted(new Date(getMillisFor(2010, 01, 04)));
Note
For convenience, we use in this example a method getMillisFor(), which is defined as shown here, in the file AbstractClusterJModelTest.java (found in the storage/
ndb/clusterj/clusterj-test/src/main/java/testsuite/clusterj directory of the MySQL Cluster
source tree):
/** Convert year, month, day into milliseconds after the Epoch, UTC.
* Set hours, minutes, seconds, and milliseconds to zero.
* @param year the year
* @param month the month (0 for January)
* @param day the day of the month
* @return
*/
protected static long getMillisFor(int year, int month, int day) {
Calendar calendar = Calendar.getInstance();
calendar.clear();
calendar.set(Calendar.YEAR, year);
calendar.set(Calendar.MONTH, month);
calendar.set(Calendar.DATE, day);
calendar.set(Calendar.HOUR, 0);
calendar.set(Calendar.MINUTE, 0);
calendar.set(Calendar.SECOND, 0);
calendar.set(Calendar.MILLISECOND, 0);
long result = calendar.getTimeInMillis();
return result;
}
To save the changed row back to the MySQL Cluster database, use the Session's updatePersistent() method, like this:
session.updatePersistent(theEmployee);
Deleting rows. You can delete a single row easily using the deletePersistent() method of Session. In this example, we find
the employee whose ID is 13, then delete this row from the employee table:
Employee exEmployee = session.find(Employee.class, 13);
session.deletePersistent(exEmployee);'
System.out.println("Deleted employee named " + exEmployee.getFirst()
+ " " + exEmployee.getLast() + ".");
There also exists a method for deleting multiple rows, which provides two options:
1.
2.
Both kinds of multi-row delete can be performed using the deletePersistentAll() method. The first variant of this method acts
on a Class. For example, the following statement deletes all rows from the employee table and returns the number of rows deleted,
as shown here:
int numberDeleted = session.deletePersistentAll(Employee);
System.out.println("There used to be "
322
The call to deletePersistentAll() just shown is equivalent to issuing the SQL statement DELETE FROM employee in the
mysql client.
deletePersistentAll() can also be used to delete a collection of rows, as shown in this example:
//
It is not necessary to find the instances in the database before deleting them.
Writing queries. The ClusterJ QueryBuilder interface is used to instantiate queries. The process begins with obtaining an instance
of QueryBuilder, which is supplied by the current Session; we can then obtain a QueryDefinition, as shown here:
QueryBuilder builder = session.getQueryBuilder();
QueryDomainType<Employee> domain = builder.createQueryDefinition(Employee.class);
This is then used to set a column for comparison by the query. Here, we show how to prepare a query that compares the value of the
employee table's department column with the constant value 8.
domain.where( domain.get("department").equal(domain.param("department") );
Query<Employee> query = session.createQuery(domain);
query.setParameter("department", 8);
To obtain the results from the query, invoke the Query's getResultList() method, as shown here;
List<Employee> results = query.getResultList();
The return value is a List that you can iterate over to retrieve and process the rows in the usual manner.
Transactions. The Transaction interface can optionally be used to bound transactions, via the following methods:
It is also possible using Transaction to check whether the transaction is active (via the isActive() method, and to get and set a
rollback-only flag (using getRollbackOnly() and setRollbackOnly(), respectively).
If you do not use the Transaction interface, methods in Session that affect the database such as persist(), deletePersistent(), updatePersistent(), and so on are automatically enclosed in a database transaction.
Note
Since Java does not have native unsigned data types, UNSIGNED columns should be avoided in table schemas if possible.
Compatibility with JDBC mappings. ClusterJ is implemented so as to be bug-compatible with the JDBC driver in terms of mapping
323
from Java types to the database. That is, if you use ClusterJ to store or retrieve data, you obtain the same value as if you used the JDBC
driver directly or through JPA.
The following tables show the mappings used by ClusterJ between common Java data types and MySQL column types. Separate tables
are provided for numeric, floating-point, and variable-width types.
Numeric types. This table shows the ClusterJ mappings between Java numeric data types and MySQL column types:
Java Data Type
boolean, Boolean
BIT(1)
byte, Byte
short, Short
int, Integer
long, Long
float, Float
FLOAT
double, Double
DOUBLE
java.math.BigDecimal
NUMERIC, DECIMAL
java.math.BigInteger
Date and time types. The following table shows the ClusterJ mappings between Java date and time data types and MySQL column
types:
Java Data Type
Java.util.Date
Java.sql.Date
DATE
Java.sql.Time
TIME
Java.sql.Timestamp
DATETIME, TIMESTAMP
Note
ClusterJ maps the MySQL YEAR type to a Java short (or java.lang.Short), as shown in the first table in this section.
java.util.Date represents date and time similar to the way in which Unix does so, but with more precision and a larger range. Where Unix represents a point in time as a 32-bit signed number of seconds since the Unix Epoch (01 January
1970), Java uses a 64-bit signed number of milliseconds since the Epoch.
Variable-width types. The following table shows the ClusterJ mappings between Java data types and MySQL variable-width column
types:
Java Data Type
String
byte[]
Note
No translation binary data is performed when mapping from MySQL BINARY, VARBINARY, or BLOB column values to
Java byte arrays. Data is presented to the application exactly as it is stored.
324
In MySQL Cluster NDB 7.1.2 and later, compiling applications for ClusterJPA is the same as compiling them for OpenJPA. To do this,
you must have the following jar files in your classpath:
openjpa-1.2.0.jar
geronimo-jta_1.1_spec-1.1.jar
geronimo-jpa_3.0_spec-1.0.jar
serp-1.13.1.jar
commons-lang-2.1.jar
commons-collections-3.2.jar
You must also have the OpenJPA jar files to run OpenJPA applications. To run them using ClusterJPA, you also need the
clusterj.jar jar file in your classpath, as well as the MySQL Server JDBC connector jar file mysql-connector-j.jar (see
Connector/J Installation), and your java.library.path must include the directory where libndbclient can be found.
Note
The requirements for compiling and running OpenJPA applications were slightly different in MySQL Cluster NDB 7.1.1.
In that version of MySQL Cluster, in addition to the OpenJPA jar files, clusterj-openjpa.jar was also required
for compilation and execution, and the jar files clusterj-core.jar, clusterj-tie.jar, jtie.jar, and ndbjtie.jar were required to run the application; in addition, you needed libndbjtie to be found in your
java.library.path.
In MySQL Cluster NDB 7.1.2 and later, these multiple ClusterJPA jar files have been merged into clusterj.jar, and
libndbjtie has become part of libndbclient.
You must also update the persistence.xml file, which selects the JPA implementation to be used by the application. The contents
of a sample persistence.xml file are shown here (with the relevant portions shown in emphasized text):
<persistence-unit name="personnel" transaction-type="RESOURCE_LOCAL">
<provider>
org.apache.openjpa.persistence.PersistenceProviderImpl
</provider>
<class>com.mysql.clusterj.jpatest.model.Employee</class>
<properties>
<property name="openjpa.BrokerFactory" value="ndb"/>
<property name="openjpa.ndb.connectString" value="localhost:1186"/>
<property name="openjpa.ConnectionURL" value="jdbc:mysql://localhost:3306/test"/>
<property name="openjpa.ConnectionDriverName" value="com.mysql.jdbc.Driver"/>
<property name="openjpa.ConnectionRetainMode" value="transaction"/>
</properties>
</persistence-unit>
To activate ClusterJPA, the property named openjpa.BrokerFactory must have the value ndb.
The name of the persistence unit is arbitrary; for this example, we have chosen personnel.
325
4.3.1.1.1. Bootstrapping
The helper class com.mysql.clusterj.ClusterJHelper contains methods for creating the
com.mysql.clusterj.SessionFactory. Bootstrapping is the process of identifying a MySQL Cluster and obtaining the SessionFactory for use with the cluster. There is one SessionFactory per cluster per Java VM.
4.3.1.1.1.1. SessionFactory
The com.mysql.clusterj.SessionFactory is configured via properties, which identify the MySQL Cluster that the application connects to:
com.mysql.clusterj.connect.timeout.before is the number of seconds to wait until the first node responds to a connect request
com.mysql.clusterj.connect.timeout.after is the number of seconds to wait until the last node responds to a connect request
4.3.1.1.1.2. Session
The com.mysql.clusterj.Session represents the user's individual connection to the cluster. It contains methods for:
Transaction
The com.mysql.clusterj.Transaction allows users to combine multiple operations into a single database transaction. It contains methods to:
roll back all changes made since the unit of work was begun
QueryBuilder
The com.mysql.clusterj.query.QueryBuilder allows users to build queries. It contains methods to:
equal
lessThan
greaterThan
lessEqual
greaterEqual
between
in
327
4.3.1.2.1. Synopsis
public class com.mysql.clusterj.ClusterJDatastoreException extends com.mysql.clusterj.ClusterJException {
// Public Constructors
public ClusterJDatastoreException(java.lang.String message);
public ClusterJDatastoreException(java.lang.String msg,
int code,
int mysqlCode,
int status,
int classification);
public ClusterJDatastoreException(java.lang.String message,
java.lang.Throwable t);
public ClusterJDatastoreException(java.lang.Throwable t);
// Public Methods
public int getClassification();
public int getStatus();
}
328
User exceptions are caused by user error, for example providing a connect string that refers to an unavailable host or port.
If a user exception is detected during bootstrapping (acquiring a SessionFactory), it is thrown as a fatal exception.
com.mysql.clusterj.ClusterJFatalUserException
If an exception is detected during initialization of a persistent interface, for example annotating a column that doesn't exist in the
mapped table, it is reported as a user exception. com.mysql.clusterj.ClusterJUserException
Datastore exceptions report conditions that result from datastore operations after bootstrapping. For example, duplicate keys on insert, or record does not exist on delete. com.mysql.clusterj.ClusterJDatastoreException
Internal exceptions report conditions that are caused by errors in implementation. These exceptions should be reported as bugs.
com.mysql.clusterj.ClusterJFatalInternalException
4.3.1.3.1. Synopsis
public class com.mysql.clusterj.ClusterJException extends java.lang.RuntimeException {
// Public Constructors
329
4.3.1.4.1. Synopsis
public class com.mysql.clusterj.ClusterJFatalException extends com.mysql.clusterj.ClusterJException {
// Public Constructors
public ClusterJFatalException(java.lang.String string);
330
4.3.1.5.1. Synopsis
public class com.mysql.clusterj.ClusterJFatalInternalException extends com.mysql.clusterj.ClusterJFatalException {
// Public Constructors
331
4.3.1.6.1. Synopsis
public class com.mysql.clusterj.ClusterJFatalUserException extends com.mysql.clusterj.ClusterJFatalException {
// Public Constructors
public ClusterJFatalUserException(java.lang.String string);
public ClusterJFatalUserException(java.lang.String string,
java.lang.Throwable t);
public ClusterJFatalUserException(java.lang.Throwable t);
}
333
4.3.1.7.1. Synopsis
public class com.mysql.clusterj.ClusterJHelper {
// Public Constructors
public ClusterJHelper();
// Public Static Methods
public static T getServiceInstance(java.lang.Class<T> cls);
public static T getServiceInstance(java.lang.Class<T> cls,
java.lang.ClassLoader loader);
public static T getServiceInstance(java.lang.Class<T> cls,
java.lang.String implementationClassName);
334
Methods inherited from java.lang.Object: equals , getClass , hashCode , notify , notifyAll , toString , wait
4.3.1.7.2. getServiceInstance(Class<T>)
public static T getServiceInstance(java.lang.Class<T> cls);
return
Locate a service implementation for a service by services lookup of a specific class loader. The first service instance found is returned.
Parameters
cls
loader
return
335
Locate a service implementation for a service. If the implementation name is not null, use it instead of looking up. If the implementation
class is not loadable or does not implement the interface, throw an exception.
Parameters
cls
implementationClassName
return
Locate all service implementations by services lookup of a specific class loader. Implementations in the services file are instantiated and
returned. Failed instantiations are remembered in the errorMessages buffer.
Parameters
cls
loader
errorMessages
return
4.3.1.7.6. getSessionFactory(Map)
public static com.-mysql.-clusterj.-SessionFactory getSessionFactory(java.util.Map props);
Locate a SessionFactory implementation by services lookup. The class loader used is the thread's context class loader.
Parameters
props
return
Exceptions
ClusterFatalUserException
Locate a SessionFactory implementation by services lookup of a specific class loader. The properties are a Map that might contain im336
loader
return
Exceptions
ClusterFatalUserException
4.3.1.8.1. Synopsis
public class com.mysql.clusterj.ClusterJUserException extends com.mysql.clusterj.ClusterJException {
// Public Constructors
public ClusterJUserException(java.lang.String message);
public ClusterJUserException(java.lang.String message,
java.lang.Throwable t);
public ClusterJUserException(java.lang.Throwable t);
}
337
4.3.1.9.1. Synopsis
public interface com.mysql.clusterj.Constants {
// Public Static Fields
public static final int DEFAULT_PROPERTY_CLUSTER_CONNECT_DELAY = 5;
public static final int DEFAULT_PROPERTY_CLUSTER_CONNECT_RETRIES = 4;
public static final int DEFAULT_PROPERTY_CLUSTER_CONNECT_TIMEOUT_AFTER = 20;
public static final int DEFAULT_PROPERTY_CLUSTER_CONNECT_TIMEOUT_BEFORE = 30;
public static final int DEFAULT_PROPERTY_CLUSTER_CONNECT_VERBOSE = 0;
public static final java.lang.String DEFAULT_PROPERTY_CLUSTER_DATABASE = "test";
public static final int DEFAULT_PROPERTY_CLUSTER_MAX_TRANSACTIONS = 4;
public static final java.lang.String PROPERTY_CLUSTER_CONNECTION_SERVICE = "com.mysql.clusterj.connection.service";
338
4.3.1.9.2. DEFAULT_PROPERTY_CLUSTER_CONNECT_DELAY
public static final int DEFAULT_PROPERTY_CLUSTER_CONNECT_DELAY = 5;
4.3.1.9.3. DEFAULT_PROPERTY_CLUSTER_CONNECT_RETRIES
public static final int DEFAULT_PROPERTY_CLUSTER_CONNECT_RETRIES = 4;
4.3.1.9.4. DEFAULT_PROPERTY_CLUSTER_CONNECT_TIMEOUT_AFTER
public static final int DEFAULT_PROPERTY_CLUSTER_CONNECT_TIMEOUT_AFTER = 20;
339
4.3.1.9.5. DEFAULT_PROPERTY_CLUSTER_CONNECT_TIMEOUT_BEFORE
public static final int DEFAULT_PROPERTY_CLUSTER_CONNECT_TIMEOUT_BEFORE = 30;
4.3.1.9.6. DEFAULT_PROPERTY_CLUSTER_CONNECT_VERBOSE
public static final int DEFAULT_PROPERTY_CLUSTER_CONNECT_VERBOSE = 0;
4.3.1.9.7. DEFAULT_PROPERTY_CLUSTER_DATABASE
public static final java.lang.String DEFAULT_PROPERTY_CLUSTER_DATABASE = "test";
4.3.1.9.8. DEFAULT_PROPERTY_CLUSTER_MAX_TRANSACTIONS
public static final int DEFAULT_PROPERTY_CLUSTER_MAX_TRANSACTIONS = 4;
4.3.1.9.9. PROPERTY_CLUSTER_CONNECT_DELAY
public static final java.lang.String PROPERTY_CLUSTER_CONNECT_DELAY = "com.mysql.clusterj.connect.delay";
The name of the connection delay property. For details, see Ndb_cluster_connection::connect()
4.3.1.9.10. PROPERTY_CLUSTER_CONNECT_RETRIES
public static final java.lang.String PROPERTY_CLUSTER_CONNECT_RETRIES = "com.mysql.clusterj.connect.retries";
The name of the connection retries property. For details, see Ndb_cluster_connection::connect()
4.3.1.9.11. PROPERTY_CLUSTER_CONNECT_TIMEOUT_AFTER
The name of the connection timeout after property. For details, see Ndb_cluster_connection::wait_until_ready()
4.3.1.9.12. PROPERTY_CLUSTER_CONNECT_TIMEOUT_BEFORE
The name of the connection timeout before property. For details, see Ndb_cluster_connection::wait_until_ready()
4.3.1.9.13. PROPERTY_CLUSTER_CONNECT_VERBOSE
public static final java.lang.String PROPERTY_CLUSTER_CONNECT_VERBOSE = "com.mysql.clusterj.connect.verbose";
The name of the connection verbose property. For details, see Ndb_cluster_connection::connect()
4.3.1.9.14. PROPERTY_CLUSTER_CONNECTION_SERVICE
public static final java.lang.String PROPERTY_CLUSTER_CONNECTION_SERVICE = "com.mysql.clusterj.connection.service";
340
4.3.1.9.15. PROPERTY_CLUSTER_CONNECTSTRING
public static final java.lang.String PROPERTY_CLUSTER_CONNECTSTRING = "com.mysql.clusterj.connectstring";
The name of the connection string property. For details, see Ndb_cluster_connection constructor
4.3.1.9.16. PROPERTY_CLUSTER_DATABASE
public static final java.lang.String PROPERTY_CLUSTER_DATABASE = "com.mysql.clusterj.database";
The name of the database property. For details, see the catalogName parameter in the Ndb constructor. Ndb constructor
4.3.1.9.17. PROPERTY_CLUSTER_MAX_TRANSACTIONS
public static final java.lang.String PROPERTY_CLUSTER_MAX_TRANSACTIONS = "com.mysql.clusterj.max.transactions";
The name of the maximum number of transactions property. For details, see Ndb::init()
4.3.1.9.18. PROPERTY_DEFER_CHANGES
public static final java.lang.String PROPERTY_DEFER_CHANGES = "com.mysql.clusterj.defer.changes";
4.3.1.9.19. PROPERTY_JDBC_DRIVER_NAME
public static final java.lang.String PROPERTY_JDBC_DRIVER_NAME = "com.mysql.clusterj.jdbc.driver";
4.3.1.9.20. PROPERTY_JDBC_PASSWORD
public static final java.lang.String PROPERTY_JDBC_PASSWORD = "com.mysql.clusterj.jdbc.password";
4.3.1.9.21. PROPERTY_JDBC_URL
public static final java.lang.String PROPERTY_JDBC_URL = "com.mysql.clusterj.jdbc.url";
4.3.1.9.22. PROPERTY_JDBC_USERNAME
public static final java.lang.String PROPERTY_JDBC_USERNAME = "com.mysql.clusterj.jdbc.username";
4.3.1.9.23. SESSION_FACTORY_SERVICE_CLASS_NAME
public static final java.lang.String SESSION_FACTORY_SERVICE_CLASS_NAME = "com.mysql.clusterj.SessionFactoryService";
4.3.1.9.24. SESSION_FACTORY_SERVICE_FILE_NAME
341
The name of the files with names of implementation classes for session factory service
4.3.1.10.1. Synopsis
public interface com.mysql.clusterj.Query<E> {
// Public Methods
public com.-mysql.-clusterj.-Results<E> execute(java.lang.Object parameter);
public com.-mysql.-clusterj.-Results<E> execute(java.lang.Object[] parameters);
public com.-mysql.-clusterj.-Results<E> execute(java.util.Map<java.-lang.-String, ?> parameters);
public java.-util.-Map<java.--lang.--String, java.--lang.--Object> explain();
public java.-util.-List<E> getResultList();
public void setParameter(java.lang.String parameterName,
java.lang.Object value);
}
Execute the query with one or more named parameters. Parameters are resolved by name.
Parameters
parameters
the parameters
return
the result
4.3.1.10.3. execute(Object...)
public com.-mysql.-clusterj.-Results<E> execute(java.lang.Object[] parameters);
Execute the query with one or more parameters. Parameters are resolved in the order they were declared in the query.
Parameters
parameters
the parameters
342
return
the result
4.3.1.10.4. execute(Object)
public com.-mysql.-clusterj.-Results<E> execute(java.lang.Object parameter);
the parameter
return
the result
4.3.1.10.5. explain()
public java.-util.-Map<java.--lang.--String, java.--lang.--Object> explain();
Explain how this query was executed, after execution. If called before executing the query, returns null. Returns a collection of
key:value pairs that explain how the query was executed.
Parameters
return
4.3.1.10.6. getResultList()
public java.-util.-List<E> getResultList();
the result
value
Results of a query.
4.3.1.11.1. Synopsis
public interface com.mysql.clusterj.Results<E> extends java.lang.Iterable<E> {
// Public Methods
public java.-util.-Iterator<E> iterator();
}
4.3.1.11.2. iterator()
public java.-util.-Iterator<E> iterator();
the iterator
4.3.1.12.1. Synopsis
public interface com.mysql.clusterj.Session {
// Public Methods
public void close();
public com.-mysql.-clusterj.-Query<T> createQuery(com.mysql.clusterj.query.QueryDefinition<T> qd);
public com.-mysql.-clusterj.-Transaction currentTransaction();
public void deletePersistent(java.lang.Object instance);
public int deletePersistentAll(java.lang.Class<T> cls);
public void deletePersistentAll(java.lang.Iterable<?> instances);
344
4.3.1.12.2. close()
public void close();
4.3.1.12.3. createQuery(QueryDefinition<T>)
public com.-mysql.-clusterj.-Query<T> createQuery(com.mysql.clusterj.query.QueryDefinition<T> qd);
345
qd
return
4.3.1.12.4. currentTransaction()
public com.-mysql.-clusterj.-Transaction currentTransaction();
the transaction
4.3.1.12.5. deletePersistent(Object)
public void deletePersistent(java.lang.Object instance);
Delete the instance from the database. Only the id field is used to determine which instance is to be deleted. If the instance does not exist in the database, an exception is thrown.
Parameters
instance
4.3.1.12.6. deletePersistentAll(Class<T>)
public int deletePersistentAll(java.lang.Class<T> cls);
Delete all instances of this class from the database. No exception is thrown even if there are no instances in the database.
Parameters
cls
the class
return
4.3.1.12.7. deletePersistentAll(Iterable<?>)
public void deletePersistentAll(java.lang.Iterable<?> instances);
key
return
4.3.1.12.9. flush()
public void flush();
Flush deferred changes to the back end. Inserts, deletes, and updates made when the deferred update flag is true are sent to the back end.
4.3.1.12.10. getQueryBuilder()
public com.-mysql.-clusterj.-query.-QueryBuilder getQueryBuilder();
Get a QueryBuilder.
Parameters
return
4.3.1.12.11. isClosed()
public boolean isClosed();
4.3.1.12.12. makePersistent(T)
public T makePersistent(T instance);
Insert the instance into the database. If the instance already exists in the database, an exception is thrown.
Parameters
instance
return
the instance
347
See Also
savePersistent(T)
4.3.1.12.13. makePersistentAll(Iterable<?>)
public java.-lang.-Iterable<?> makePersistentAll(java.lang.Iterable<?> instances);
return
the instances
fieldName
4.3.1.12.15. newInstance(Class<T>)
public T newInstance(java.lang.Class<T> cls);
return
4.3.1.12.16. persist(Object)
public void persist(java.lang.Object instance);
Insert the instance into the database. This method has identical semantics to makePersistent.
Parameters
instance
4.3.1.12.17. remove(Object)
348
Delete the instance from the database. This method has identical semantics to deletePersistent.
Parameters
instance
4.3.1.12.18. savePersistent(T)
public T savePersistent(T instance);
Save the instance in the database without checking for existence. The id field is used to determine which instance is to be saved. If the
instance exists in the database it will be updated. If the instance does not exist, it will be created.
Parameters
instance
4.3.1.12.19. savePersistentAll(Iterable<?>)
public java.-lang.-Iterable<?> savePersistentAll(java.lang.Iterable<?> instances);
Set the partition key for the next transaction. The key must be of the same type as the primary key defined by the table. The key parameter is the wrapped version of the primitive type of the key, e.g. Integer for INT key types, Long for BIGINT key types, or String for
char and varchar types. For multi-column primary keys, the key parameter is an Object[], each element of which is a component of the
primary key. The elements must be in the order of primary key declaration.
Parameters
key
Exceptions
ClusterJUserException
if a transaction is enlisted
ClusterJUserException
ClusterJUserException
349
ClusterJUserException
4.3.1.12.21. updatePersistent(Object)
public void updatePersistent(java.lang.Object instance);
Update the instance in the database without necessarily retrieving it. The id field is used to determine which instance is to be updated. If
the instance does not exist in the database, an exception is thrown.
Parameters
instance
4.3.1.12.22. updatePersistentAll(Iterable<?>)
public void updatePersistentAll(java.lang.Iterable<?> instances);
4.3.1.13.1. Synopsis
public interface com.mysql.clusterj.SessionFactory {
// Public Methods
public void close();
public com.-mysql.-clusterj.-Session getSession();
public com.-mysql.-clusterj.-Session getSession(java.util.Map properties);
}
4.3.1.13.2. close()
public void close();
4.3.1.13.3. getSession()
350
Create a Session to use with the cluster, using all the properties of the SessionFactory.
Parameters
return
the session
4.3.1.13.4. getSession(Map)
public com.-mysql.-clusterj.-Session getSession(java.util.Map properties);
Create a session to use with the cluster, overriding some properties. Properties PROPERTY_CLUSTER_CONNECTSTRING, PROPERTY_CLUSTER_DATABASE, and PROPERTY_CLUSTER_MAX_TRANSACTIONS may not be overridden.
Parameters
properties
return
the session
4.3.1.14.1. Synopsis
public interface com.mysql.clusterj.SessionFactoryService {
// Public Methods
Create or get a session factory. If a session factory with the same value for PROPERTY_CLUSTER_CONNECTSTRING has already
been created in the VM, the existing factory is returned, regardless of whether other properties of the factory are the same as specified in
the Map.
Parameters
props
the properties for the session factory, in which the keys are defined in Constants and the values describe the environment
351
return
See Also
com.mysql.clusterj.Constants
4.3.1.15.1. Synopsis
public interface com.mysql.clusterj.Transaction {
// Public Methods
public void begin();
public void commit();
public boolean getRollbackOnly();
public boolean isActive();
public void rollback();
public void setRollbackOnly();
}
4.3.1.15.2. begin()
public void begin();
Begin a transaction.
4.3.1.15.3. commit()
public void commit();
Commit a transaction.
4.3.1.15.4. getRollbackOnly()
public boolean getRollbackOnly();
352
return
4.3.1.15.5. isActive()
public boolean isActive();
4.3.1.15.6. rollback()
public void rollback();
4.3.1.15.7. setRollbackOnly()
public void setRollbackOnly();
Mark this transaction as rollback only. After this method is called, commit() will roll back the transaction and throw an exception; rollback() will roll back the transaction and not throw an exception.
4.3.2.1.1. Synopsis
353
4.3.2.1.2. allowsNull
Whether the column allows null values to be inserted. This overrides the database definition and requires that the application provide
non-null values for the database column.
Parameters
return
4.3.2.1.3. defaultValue
Default value for this column.
Parameters
return
4.3.2.1.4. name
Name of the column.
Parameters
return
4.3.2.2.1. Synopsis
354
4.3.2.2.2. value
The columns annotation information.
Parameters
return
the columns
4.3.2.3.1. Synopsis
4.3.2.3.2. key
The key for the extension (required).
355
Parameters
return
the key
4.3.2.3.3. value
The value for the extension (required).
Parameters
return
the value
4.3.2.3.4. vendorName
Vendor that the extension applies to (required to make the key unique).
Parameters
return
the vendor
4.3.2.4.1. Synopsis
4.3.2.4.2. value
The extensions.
Parameters
return
the extensions
356
4.3.2.5.1. Synopsis
4.3.2.5.2. columns
Columns that compose this index.
Parameters
return
4.3.2.5.3. name
Name of the index
Parameters
return
4.3.2.5.4. unique
Whether this index is unique
Parameters
return
357
4.3.2.6.1. Synopsis
4.3.2.6.2. value
The indices.
Parameters
return
The indices
4.3.2.7.1. Synopsis
358
4.3.2.8.1. Synopsis
4.3.2.9.1. Synopsis
Methods inherited from java.lang.Enum: compareTo , equals , getDeclaringClass , hashCode , name , ordinal ,
toString , valueOf
Methods inherited from java.lang.Object: getClass , notify , notifyAll , wait
359
4.3.2.10.1. Synopsis
4.3.2.10.2. column
Name of the column to use for the partition key
Parameters
return
4.3.2.10.3. columns
360
4.3.2.11.1. Synopsis
4.3.2.11.2. database
Parameters
return
4.3.2.11.3. schema
Parameters
return
4.3.2.11.4. table
Parameters
361
return
4.3.2.12.1. Synopsis
Methods inherited from java.lang.Enum: compareTo , equals , getDeclaringClass , hashCode , name , ordinal ,
toString , valueOf
Methods inherited from java.lang.Object: getClass , notify , notifyAll , wait
4.3.2.13.1. Synopsis
362
4.3.2.13.2. column
Column name where the values are stored for this member.
Parameters
return
4.3.2.13.3. extensions
Non-standard extensions for this member.
Parameters
return
4.3.2.13.4. nullValue
Behavior when this member contains a null value.
Parameters
return
4.3.2.13.5. primaryKey
Whether this member is part of the primary key for the table. This is equivalent to specifying @PrimaryKey as a separate annotation on
the member.
Parameters
return
4.3.2.14.1. Synopsis
4.3.2.14.2. column
Name of the column to use for the primary key
Parameters
return
4.3.2.14.3. columns
The column(s) for the primary key
Parameters
return
4.3.2.14.4. name
Name of the primary key constraint
Parameters
return
364
4.3.3.1.1. Synopsis
public interface com.mysql.clusterj.query.Predicate {
// Public Methods
public com.-mysql.-clusterj.-query.-Predicate and(com.mysql.clusterj.query.Predicate predicate);
public com.-mysql.-clusterj.-query.-Predicate not();
public com.-mysql.-clusterj.-query.-Predicate or(com.mysql.clusterj.query.Predicate predicate);
}
4.3.3.1.2. and(Predicate)
public com.-mysql.-clusterj.-query.-Predicate and(com.mysql.clusterj.query.Predicate predicate);
return
4.3.3.1.3. not()
public com.-mysql.-clusterj.-query.-Predicate not();
this predicate
4.3.3.1.4. or(Predicate)
public com.-mysql.-clusterj.-query.-Predicate or(com.mysql.clusterj.query.Predicate predicate);
365
Parameters
predicate
return
4.3.3.2.1. Synopsis
public interface com.mysql.clusterj.query.PredicateOperand {
// Public Methods
public com.-mysql.-clusterj.-query.-Predicate between(com.mysql.clusterj.query.PredicateOperand lower,
com.mysql.clusterj.query.PredicateOperand upper);
public com.-mysql.-clusterj.-query.-Predicate equal(com.mysql.clusterj.query.PredicateOperand other);
public com.-mysql.-clusterj.-query.-Predicate greaterEqual(com.mysql.clusterj.query.PredicateOperand other);
public com.-mysql.-clusterj.-query.-Predicate greaterThan(com.mysql.clusterj.query.PredicateOperand other);
public com.-mysql.-clusterj.-query.-Predicate in(com.mysql.clusterj.query.PredicateOperand other);
public com.-mysql.-clusterj.-query.-Predicate lessEqual(com.mysql.clusterj.query.PredicateOperand other);
public com.-mysql.-clusterj.-query.-Predicate lessThan(com.mysql.clusterj.query.PredicateOperand other);
}
another PredicateOperand
upper
another PredicateOperand
return
a new Predicate
366
4.3.3.2.3. equal(PredicateOperand)
public com.-mysql.-clusterj.-query.-Predicate equal(com.mysql.clusterj.query.PredicateOperand other);
Return a Predicate representing comparing this to another using "equal to" semantics.
Parameters
other
return
a new Predicate
4.3.3.2.4. greaterEqual(PredicateOperand)
public com.-mysql.-clusterj.-query.-Predicate greaterEqual(com.mysql.clusterj.query.PredicateOperand other);
Return a Predicate representing comparing this to another using "greater than or equal to" semantics.
Parameters
other
return
a new Predicate
4.3.3.2.5. greaterThan(PredicateOperand)
public com.-mysql.-clusterj.-query.-Predicate greaterThan(com.mysql.clusterj.query.PredicateOperand other);
Return a Predicate representing comparing this to another using "greater than" semantics.
Parameters
other
return
a new Predicate
4.3.3.2.6. in(PredicateOperand)
public com.-mysql.-clusterj.-query.-Predicate in(com.mysql.clusterj.query.PredicateOperand other);
Return a Predicate representing comparing this to a collection of values using "in" semantics.
Parameters
other
another PredicateOperand
return
a new Predicate
4.3.3.2.7. lessEqual(PredicateOperand)
public com.-mysql.-clusterj.-query.-Predicate lessEqual(com.mysql.clusterj.query.PredicateOperand other);
367
Return a Predicate representing comparing this to another using "less than or equal to" semantics.
Parameters
other
return
a new Predicate
4.3.3.2.8. lessThan(PredicateOperand)
public com.-mysql.-clusterj.-query.-Predicate lessThan(com.mysql.clusterj.query.PredicateOperand other);
Return a Predicate representing comparing this to another using "less than" semantics.
Parameters
other
return
a new Predicate
4.3.3.3.1. Synopsis
public interface com.mysql.clusterj.query.QueryBuilder {
// Public Methods
public com.-mysql.-clusterj.-query.-QueryDomainType<T> createQueryDefinition(java.lang.Class<T> cls);
}
See Also
getQueryBuilder()
4.3.3.3.2. createQueryDefinition(Class<T>)
public com.-mysql.-clusterj.-query.-QueryDomainType<T> createQueryDefinition(java.lang.Class<T> cls);
return
4.3.3.4.1. Synopsis
public interface com.mysql.clusterj.query.QueryDefinition<E> {
// Public Methods
public com.-mysql.-clusterj.-query.-Predicate not(com.mysql.clusterj.query.Predicate predicate);
public com.-mysql.-clusterj.-query.-PredicateOperand param(java.lang.String parameterName);
public com.-mysql.-clusterj.-query.-QueryDefinition<E> where(com.mysql.clusterj.query.Predicate predicate);
}
4.3.3.4.2. not(Predicate)
public com.-mysql.-clusterj.-query.-Predicate not(com.mysql.clusterj.query.Predicate predicate);
return
4.3.3.4.3. param(String)
public com.-mysql.-clusterj.-query.-PredicateOperand param(java.lang.String parameterName);
return
4.3.3.4.4. where(Predicate)
public com.-mysql.-clusterj.-query.-QueryDefinition<E> where(com.mysql.clusterj.query.Predicate predicate);
369
Parameters
predicate
the Predicate
return
4.3.3.5.1. Synopsis
public interface com.mysql.clusterj.query.QueryDomainType<E> extends com.mysql.clusterj.query.QueryDefinition<E> {
// Public Methods
public com.-mysql.-clusterj.-query.-PredicateOperand get(java.lang.String propertyName);
public java.-lang.-Class<E> getType();
}
4.3.3.5.2. get(String)
public com.-mysql.-clusterj.-query.-PredicateOperand get(java.lang.String propertyName);
return
4.3.3.5.3. getType()
public java.-lang.-Class<E> getType();
return
4.4. MySQL Cluster Connector for Java: Limitations and Known Issues
In this section, we discuss limitations and known issues in the MySQL Cluster Connector for Java APIs.
Joins. With ClusterJ, queries are limited to single tables. This is not a problem with JPA or JDBC, both of which support joins.
Database views. Because MySQL database views do not use the NDB storage engine, ClusterJ applications cannot see views, and
thus cannot access them. To work with views using Java, you should use JPA or JDBC.
Relations and inheritance. ClusterJ does not support relations or inheritance. This means that ClusterJ does not handle foreign keys.
While NDB tables do not support foreign keys, it is possible using JPA to enforce them programmatically.
Known issues in MySQL Cluster. For information about limitations and other known issues with MySQL Cluster, see Known Limitations of MySQL Cluster.
Known issues in JPA. For information about limitations and known issues with OpenJPA, see the OpenJPA documentation.
Known issues in JDBC and Connector/J. For information about limitations and known issues with JDBC and Connector/J, see JDBC
API Implementation Notes, and Connector/J: Common Problems and Solutions.
371
request errors
2.
3.
service errors
4.
backup errors
5.
6.
Description
NDB_MGM_ILLEGAL_CONNECT_STRING
INVALID CONNECTSTRING
NDB_MGM_ILLEGAL_SERVER_HANDLE
NDB_MGM_ILLEGAL_SERVER_REPLY
NDB_MGM_ILLEGAL_NUMBER_OF_NODES
NDB_MGM_ILLEGAL_NODE_STATUS
NDB_MGM_OUT_OF_MEMORY
NDB_MGM_SERVER_NOT_CONNECTED
NDB_MGM_COULD_NOT_CONNECT_TO_SOCKET
Description
NDB_MGM_ALLOCID_ERROR
NDB_MGM_ALLOCID_CONFIG_MISMATCH
Description
NDB_MGM_START_FAILED
STARTUP FAILURE
372
Value
Description
NDB_MGM_STOP_FAILED
SHUTDOWN FAILURE
NDB_MGM_RESTART_FAILED
RESTART FAILURE
Description
NDB_MGM_COULD_NOT_START_BACKUP
NDB_MGM_COULD_NOT_ABORT_BACKUP
Description
NDB_MGM_COULD_NOT_ENTER_SINGLE_USER_MODE
NDB_MGM_COULD_NOT_EXIT_SINGLE_USER_MODE
Description
NDB_MGM_USAGE_ERROR
Important
It is strongly recommended that you not depend on specific error codes in your NDB API applications, as they are subject
to change over time. Instead, you should use the NdbError::Status and error classification in your source code, or
consult the output of perror --ndb error_code to obtain information about a specific error code.
If you find a situation in which you need to use a specific error code in your application, please file a bug report at http://bugs.mysql.com/ so that we can update the corresponding status and classification.
Errors raised during operation definition. Errors generated during operation definition result in a failure return code from the method called. The actual error can be determined by examining the relevant NdbOperation object, or the operation's NdbTransaction object.
Errors raised during operation execution. Errors occurring during operation execution cause the transaction of which they are a part
to be aborted unless the AO_IgnoreError abort option is set for the operation.
Important
If you have worked with older versions of the NDB API, you should be aware that, beginning with MySQL Cluster NDB
6.2.0, the AbortOption type is a member of NdbOperation. See Section 2.3.15.1.1, The NdbOperation::AbortOption Type, for more information.
By default, read operations are run with AO_IgnoreError, and write operations are run with AbortOnError, but this can be overridden by the user. When an error during execution causes a transaction to be aborted, the execute() method returns a failure return
code. If an error is ignored due to AO_IgnoreError being set on the operation, the execute() method returns a success code, and
the user must examine all operations for failure using NdbOperation::getNdbError(). For this reason, the return value of
getNdbError() should usually be checked, even if execute() returns success. If the client application does not keep track of
NdbOperation objects during execution, then NdbTransaction::getNextCompletedOperation() can be used to iterate
over them.
You should also be aware that use of NdbBlob can result in extra operations being added to the batches executed. This means that,
when iterating over completed operations using getNextCompletedOperation(), you may encounter operations related to NdbBlob objects which were not defined by your application.
Note
A read whose LockMode is CommittedRead cannot be AbortOnError. In this case, it is always be
IgnoreError.
In all cases where operation-specific errors arise, an execution error with an operation is marked against both the operation and the associated transaction object. Where there are multiple operation errors in a single NdbTransaction::execute() call, due to operation batching and the use of AO_IgnoreError, only the first is marked against the NdbTransaction object. The remaining errors
are recorded against the corresponding NdbOperation objects only.
It is also possible for errors to occur during execution such as a data node failure which are marked against the transaction object,
but not against the underlying operation objects. This is because these errors apply to the transaction as a whole, and not to individual
operations within the transaction.
For this reason, applications should use NdbTransaction::getNdbError() as the first way to determine whether an NdbTransaction::execute() call failed. If the batch of operations being executed included operations with the AO_IgnoreError
abort option set, then it is possible that there were multiple failures, and the completed operations should be checked individually for errors using NdbOperation::getNdbError().
Implicit NdbTransaction::execute() calls in scan and BLOB methods. Scan operations are executed in the same way as other operations, and also have implicit execute() calls within the NdbScanOperation::nextResult() method. When NdbScanOperation::nextResult() indicates failure (that is, if the method returns -1), the transaction object should be checked for
an error. The NdbScanOperation may also contain the error, but only if the error is not operation-specific.
Some BLOB manipulation methods also have implicit internal execute() calls, and so can experience operation execution failures at
these points. The following NdbBlob methods can generate implicit execute() calls; this means that they also require checks of the
NdbTransaction object for errors via NdbTransaction::getNdbError() if they return an error code:
setNull()
truncate()
readData()
writeData()
Summary. In general, it is possible for an error to occur during execution (resulting in a failure return code) when calling any of the
following methods:
374
NdbTransaction::execute()
NdbBlob::setNull()
NdbBlob::truncate()
NdbBlob::readData()
NdbBlob::writeData()
NdbScanOperation::nextResult()
Note
This method does not perform an implicit execute() call. The NdbBlob methods can cause other defined operations to
be executed when these methods are called; however, nextResult() calls do not do so.
If this happens, the NdbTransaction::getNdbError() method should be called to identify the first error that occurred. When
operations are batched, and there are IgnoreError operations in the batch, there may be multiple operations with errors in the transaction. These can be found by using NdbTransaction::getNextCompletedOperation() to iterate over the set of completed
operations, calling NdbOperation::getNdbError() for each operation.
When IgnoreError has been set on any operations in a batch of operations to be executed, the NdbTransaction::execute()
method indicates success even where errors have actually occurred, as long as none of these errors caused a transaction to be aborted.
To determine whether there were any ignored errors, the transaction error status should be checked using NdbTransaction::getNdbError(). Only if this indicates success can you be certain that no errors occurred. If an error code is returned by
this method, and operations were batched, then you should iterate over all completed operations to find all the operations with ignored
errors.
Example (pseudocode). We begin by executing a transaction which may have batched operations and a mix of AO_IgnoreError
and AbortOnError abort options:
int execResult= NdbTransaction.execute(args);
Note
For the number and permitted values of args, see Section 2.3.19.2.5, NdbTransaction::execute().
Next, because errors on AO_IgnoreError operations do not affect execResult that is, the value returned by execute() we
check for errors on the transaction:
NdbError err= NdbTransaction.getNdbError();
if (err.code != 0)
{
An nonzero value for the error code means that an error was raised on the transaction. This could be due to any of the following conditions:
A transaction-wide error, such as a data node failure, that caused the transaction to be aborted
A single operation-specific error, such as a constraint violation, that caused the transaction to be aborted
A single operation-specific ignored error, such as no data found, that did not cause the transaction to be aborted
The first of many operation-specific ignored errors, such as no data found when batching, that did not cause the transaction to be
aborted
First of a number of operation-specific ignored errors such as no data found (when batching) before an aborting operation error
(transaction aborted)
if (execResult != 0)
{
The transaction has been aborted. The recommended strategy for handling the error in this case is to test the transaction error status and
375
(err.status)
value1:
statement block handling value1 ...
value2:
statement block handling value2 ...
(etc. ...)
valueN:
statement block handling valueN ...
Since the transaction was aborted, it is generally necessary to iterate over the completed operations (if any) and find the errors raised by
each only if you wish to do so for reporting purposes.
}
else
{
The transaction itself was not aborted, but there must be one or more ignored errors. In this case, you should iterate over the operations
to determine what happened and handle the cause accordingly.
}
}
To handle a NdbScanOperation::nextResult() which returns -1, indicating that the operation failed (omitting cases where
the operation was successful):
int nextrc= NdbScanOperation.nextResult(args);
Note
For the number and permitted values of args, see Section 2.3.18.2.2, NdbScanOperation::nextResult().
if (nextrc == -1)
{
First, you should check the NdbScanOperation object for any errors:
NdbError err= NdbScanOperation.getNdbError();
if (err.code == 0)
{
No error was found in the scan operation; the error must belong to the transaction as whole.
}
err= NdbTransaction.getNdbError();
Now you can handle the error based on the error status:
switch
{
case
//
case
//
//
case
//
}
(err.status)
value1:
statement block handling value1 ...
value2:
statement block handling value2 ...
(etc. ...)
valueN:
statement block handling valueN ...
For information about NDB API error classification and status codes, see Section 5.2.3, NDB Error Classifications. While you should
not rely on a specific error code or message text in your NDB API applications since error codes and messages are both subject to
change over time it can be useful to check error codes and messages to help determine why a particular failure occurred. For more
information about these, see Section 5.2.2, NDB Error Codes and Messages. For more about NdbError and the types of information
which can be obtained from NdbError objects, see Section 2.3.31, The NdbError Structure.
This section contains a number of tables, one for each type of NDB API error. The error types include the following:
No error
Schema error
Node shutdown
Application error
Internal temporary
Insufficient space
Internal error
No data found
Overload error
Constraint violation
Timeout expired
Note
You can always obtain the latest error codes and information from the file storage/
ndb/src/ndbapi/ndberror.c.
NE
NO ERROR
281
AE
HA_ERR_NO_CONNECTION
299
DMEC
AE
763
DMEC
AE
823
DMEC
AE
829
DMEC
AE
377
831
AE
DMEC
876
DMEC
AE
876
877
DMEC
AE
877
878
DMEC
AE
878
879
DMEC
AE
879
880
DMEC
AE
884
DMEC
AE
885
DMEC
AE
886
DMEC
AE
897
DMEC
AE
UPDATE ATTEMPT OF PRIMARY KEY VIA NDBCLUSTER INTERNAL API (IF THIS OCCURS VIA
THE MYSQL SERVER IT IS A BUG, PLEASE REPORT)
892
DMEC
AE
4256
DMEC
AE
4257
DMEC
AE
320
DMEC
AE
321
DMEC
AE
INVALID NODEGROUP ID
322
DMEC
AE
323
DMEC
AE
TION
DEGROUP
EXISTING
324
DMEC
AE
242
DMEC
AE
244
DMEC
AE
269
DMEC
AE
874
DMEC
AE
4600
DMEC
AE
4601
DMEC
AE
4602
DMEC
AE
4603
DMEC
AE
4604
DMEC
AE
4605
DMEC
AE
TRANSACTION
EACH OPERATION
4607
DMEC
AE
378
4608
DMEC
AE
4609
DMEC
AE
4232
DMEC
AE
4707
DMEC
AE
4708
DMEC
AE
4709
DMEC
AE
4710
DMEC
AE
4711
DMEC
AE
4712
DMEC
AE
311
DMEC
AE
771
HA_WRONG_CREATE_OPTION
AE
776
DMEC
AE
777
DMEC
AE
778
DMEC
AE
1306
DMEC
AE
1342
DMEC
AE
1343
DMEC
AE
1344
DMEC
AE
1345
DMEC
AE
1346
DMEC
AE
1347
DMEC
AE
1348
DMEC
AE
1349
DMEC
AE
1329
DMEC
AE
1701
DMEC
AE
1702
DMEC
AE
1704
DMEC
AE
720
DMEC
AE
4004
DMEC
AE
CLUSTER
TED
BLE
4100
DMEC
AE
379
4101
AE
DMEC
4102
DMEC
AE
4103
DMEC
AE
4104
DMEC
AE
4105
DMEC
AE
4106
DMEC
AE
CONNECT FAILED
NDB INIT IN WRONG STATE, DESTROY NDB OBJECT AND CREATE A NEW
DEFINED
4114
DMEC
AE
4116
DMEC
AE
4117
DMEC
AE
4118
DMEC
AE
4300
DMEC
AE
4301
DMEC
AE
4302
DMEC
AE
4303
DMEC
AE
4304
DMEC
AE
4305
DMEC
AE
4306
DMEC
AE
4307
DMEC
AE
4308
DMEC
AE
4309
DMEC
AE
BYTES
4310
DMEC
AE
4311
DMEC
AE
4312
DMEC
AE
4313
DMEC
AE
4314
DMEC
AE
4315
DMEC
AE
4316
DMEC
AE
4317
DMEC
AE
4318
DMEC
AE
4319
DMEC
AE
4322
DMEC
AE
NOT PREPARED TO
4323
DMEC
AE
4324
DMEC
AE
4325
DMEC
AE
380
4326
DMEC
AE
4327
DMEC
AE
4328
DMEC
AE
4329
DMEC
AE
BITS
TED
4340
DMEC
AE
4400
DMEC
AE
4401
DMEC
AE
4402
DMEC
AE
4410
DMEC
AE
4411
DMEC
AE
TRANSACTION
GRADE COMPLETE
4501
DMEC
AE
4502
DMEC
AE
4503
DMEC
AE
4504
DMEC
AE
4505
DMEC
AE
4506
DMEC
AE
4507
DMEC
AE
4508
DMEC
AE
4509
DMEC
AE
4510
DMEC
AE
4511
DMEC
AE
4512
DMEC
AE
4513
DMEC
AE
4514
DMEC
AE
4515
DMEC
AE
4516
DMEC
AE
4517
DMEC
AE
SEARCH
INSTEAD
381
4518
AE
DMEC
4519
DMEC
AE
4520
DMEC
AE
4521
DMEC
AE
4522
DMEC
AE
4523
DMEC
AE
4524
DMEC
AE
4535
DMEC
AE
4536
DMEC
AE
4537
DMEC
AE
4538
DMEC
AE
4539
DMEC
AE
4540
DMEC
AE
4542
DMEC
AE
4543
DMEC
AE
4544
DMEC
AE
4545
DMEC
AE
4546
DMEC
AE
4547
DMEC
AE
4548
DMEC
AE
4200
DMEC
AE
4201
DMEC
AE
4202
DMEC
AE
STRUCTURE
ALLOWED
4203
DMEC
AE
4204
DMEC
AE
4205
DMEC
AE
4206
DMEC
AE
4207
DMEC
AE
4208
DMEC
AE
4209
DMEC
AE
4210
DMEC
AE
4211
DMEC
AE
382
4212
AE
DMEC
4213
DMEC
AE
4214
DMEC
AE
4215
DMEC
AE
4216
DMEC
AE
4217
DMEC
AE
4218
DMEC
AE
4219
DMEC
AE
4220
DMEC
AE
4221
DMEC
AE
4222
DMEC
AE
4223
DMEC
AE
4224
DMEC
AE
BE HANDLED
FERENT SUBROUTINE
4225
DMEC
AE
4226
DMEC
AE
4227
DMEC
AE
4228
DMEC
AE
4229
DMEC
AE
4230
DMEC
AE
4231
DMEC
AE
4233
DMEC
AE
4234
DMEC
AE
4235
DMEC
AE
4236
DMEC
AE
4237
DMEC
AE
4238
DMEC
AE
4239
DMEC
AE
4240
DMEC
AE
4241
DMEC
AE
4242
DMEC
AE
4243
DMEC
AE
4247
DMEC
AE
383
4248
DMEC
AE
4249
DMEC
AE
INVALID TABLE
4250
DMEC
AE
4251
HA_ERR_FOUND_DUPP_UNIQUE
AE
4252
DMEC
AE
4253
DMEC
AE
4254
DMEC
AE
4255
DMEC
AE
4258
DMEC
AE
4259
DMEC
AE
4264
DMEC
AE
4265
DMEC
AE
4266
DMEC
AE
4335
DMEC
AE
STATE
4271
DMEC
AE
4272
DMEC
AE
4275
DMEC
AE
4276
DMEC
AE
4277
DMEC
AE
4278
DMEC
AE
4279
DMEC
AE
MALFORMED STRING
4280
DMEC
AE
4281
DMEC
AE
4282
DMEC
AE
4283
DMEC
AE
4284
DMEC
AE
4285
DMEC
AE
4286
DMEC
AE
4287
DMEC
AE
4288
DMEC
AE
384
4289
DMEC
AE
4290
DMEC
AE
4291
DMEC
AE
4292
DMEC
AE
4341
DMEC
AE
4293
DMEC
AE
4294
DMEC
AE
4295
DMEC
AE
4296
DMEC
AE
INVALID ABORTOPTION
4297
DMEC
AE
STRUCTURE
STRUCTURE
4298
DMEC
AE
4299
DMEC
AE
NO_CONTA DMEC
CT_WITH_
PROCESS
AE
WRONG_PR DMEC
OCESS_TY
PE
AE
SEND_OR_ DMEC
RECEIVE_FA
ILED
AE
INVALDMEC
ID_ERROR
_NUMBER
AE
INVALDMEC
ID_TRACE
_NUMBER
AE
INVALDMEC
ID_BLOCK
_NAME
AE
NODE_SHU DMEC
TDOWN_IN
_PROGESS
AE
SYSDMEC
TEM_SHUT
DOWN_IN_
PROGRESS
AE
NODE_SHU DMEC
TDOWN_WO
ULD_CAUS
E_SYSTEM
AE
385
_CRASH
UNSUPDMEC
PORTED_NODE
_SHUTDOW
N
AE
NODE_NOT DMEC
_API_NOD
E
AE
OPERADMEC
TION_NOT
_ALLOWED
_START_S
TOP
AE
NO_CONTA DMEC
CT_WITH_
DB_NODES
AE
626
ND
HA_ERR_KEY_NOT_FOUND
630
CV
HA_ERR_FOUND_DUPP_KEY
839
DMEC
CV
840
DMEC
CV
893
HA_ERR_FOUND_DUPP_KEY
CV
4713
SE
DMEC
703
DMEC
SE
704
DMEC
SE
705
DMEC
SE
707
DMEC
SE
386
708
DMEC
SE
709
HA_ERR_NO_SUCH_TABLE
SE
710
DMEC
SE
723
HA_ERR_NO_SUCH_TABLE
SE
736
DMEC
SE
737
HA_WRONG_CREATE_OPTION
SE
738
HA_WRONG_CREATE_OPTION
SE
739
HA_WRONG_CREATE_OPTION
SE
740
HA_WRONG_CREATE_OPTION
SE
741
DMEC
SE
743
HA_WRONG_CREATE_OPTION
SE
744
DMEC
SE
745
HA_WRONG_CREATE_OPTION
SE
779
HA_WRONG_CREATE_OPTION
SE
791
HA_WRONG_CREATE_OPTION
SE
764
HA_WRONG_CREATE_OPTION
SE
765
DMEC
SE
750
IE
SE
751
DMEC
SE
752
DMEC
SE
753
IE
SE
754
IE
SE
755
HA_WRONG_CREATE_OPTION
SE
INVALID TABLESPACE
756
DMEC
SE
757
DMEC
SE
758
DMEC
SE
759
DMEC
SE
761
DMEC
SE
FILE
GRESS
762
DMEC
SE
766
DMEC
SE
767
DMEC
SE
768
DMEC
SE
769
DMEC
SE
770
DMEC
SE
774
DMEC
SE
790
HA_WRONG_CREATE_OPTION
SE
INVALID HASHMAP
387
241
HA_ERR_TABLE_DEF_CHANGED
SE
283
HA_ERR_NO_SUCH_TABLE
SE
284
HA_ERR_TABLE_DEF_CHANGED
SE
285
DMEC
SE
881
DMEC
SE
906
DMEC
SE
907
DMEC
SE
1224
HA_WRONG_CREATE_OPTION
SE
1225
DMEC
SE
1226
DMEC
SE
1227
HA_WRONG_CREATE_OPTION
SE
1228
DMEC
SE
1229
DMEC
SE
1231
DMEC
SE
1232
DMEC
SE
1503
DMEC
SE
1504
DMEC
SE
1508
DMEC
SE
1509
DMEC
SE
1512
DMEC
SE
1514
DMEC
SE
DEX
SIONS ETC
GROUP
1515
DMEC
SE
1516
DMEC
SE
FILE TO SMALL
773
DMEC
SE
775
DMEC
SE
1407
DMEC
SE
1415
DMEC
SE
1417
DMEC
SE
1418
DMEC
SE
1419
DMEC
SE
1421
DMEC
SE
1422
DMEC
SE
1423
DMEC
SE
AGER
388
1424
DMEC
SE
OUT OF MAXNOOFCONCURRENTSUBOPERATIONS
1425
DMEC
SE
1426
DMEC
SE
TO STOP SUBSCRIBER
NO SUCH SUBSCRIBER
746
DMEC
OE
4244
HA_ERR_TABLE_EXIST
OE
1321
DMEC
UD
4260
DMEC
UD
4261
DMEC
UD
4262
DMEC
UD
623
HA_ERR_RECORD_FILE_FULL
IS
623
624
HA_ERR_RECORD_FILE_FULL
IS
624
625
HA_ERR_INDEX_FILE_FULL
IS
633
HA_ERR_INDEX_FILE_FULL
IS
640
DMEC
IS
826
HA_ERR_RECORD_FILE_FULL
IS
827
HA_ERR_RECORD_FILE_FULL
IS
902
HA_ERR_RECORD_FILE_FULL
IS
903
HA_ERR_INDEX_FILE_FULL
IS
904
HA_ERR_INDEX_FILE_FULL
IS
905
DMEC
IS
389
1601
HA_ERR_RECORD_FILE_FULL
IS
1602
DMEC
IS
NO DATAFILE IN TABLESPACE
747
DMEC
IS
908
DMEC
IS
1303
DMEC
IS
OUT OF RESOURCES
1412
DMEC
IS
1416
DMEC
IS
217
DMEC
TR
217
218
DMEC
TR
OUT OF LONGMESSAGEBUFFER
219
DMEC
TR
219
233
DMEC
TR
275
DMEC
TR
279
DMEC
TR
414
DMEC
TR
414
418
DMEC
TR
419
DMEC
TR
419
245
DMEC
TR
488
DMEC
TR
489
DMEC
TR
490
DMEC
TR
805
DMEC
TR
830
DMEC
TR
873
DMEC
TR
899
DMEC
TR
1217
DMEC
TR
1218
DMEC
TR
1220
DMEC
TR
1222
DMEC
TR
4021
DMEC
TR
390
4022
DMEC
TR
4032
DMEC
TR
1501
DMEC
TR
288
DMEC
TR
289
DMEC
TR
780
DMEC
TR
783
DMEC
TR
785
DMEC
TR
291
DMEC
TR
784
DMEC
TR
788
DMEC
TR
748
DMEC
TR
1350
DMEC
TR
1411
DMEC
TR
SCHEMA TRANSACTION
ING A SUBSCRIBER
1413
DMEC
TR
1414
DMEC
TR
1420
DMEC
TR
2810
DMEC
TR
2811
DMEC
TR
2815
DMEC
TR
FILE SYSTEM
286
DMEC
NR
250
DMEC
NR
499
DMEC
NR
1204
DMEC
NR
4002
DMEC
NR
4010
DMEC
NR
4025
DMEC
NR
391
4027
DMEC
NR
4028
DMEC
NR
4029
DMEC
NR
4031
DMEC
NR
4033
DMEC
NR
4115
DMEC
NR
TRANSACTION WAS COMMITTED BUT ALL READ INFORMATION WAS NOT ""RECEIVED DUE TO NODE
CRASH
4119
DMEC
NR
786
DMEC
NR
1405
DMEC
NR
1427
DMEC
NR
701
DMEC
OL
711
DMEC
OL
410
DMEC
OL
677
DMEC
OL
891
DMEC
OL
1221
DMEC
OL
4006
DMEC
OL
266
HA_ERR_LOCK_WAIT_TIMEOUT
TO
274,
HA_ERR_LOCK_WAIT_TIMEOUT
HA_ERR_L
OCK_WAIT
_TIMEOUT
, TO,
"Time-
TO
392
out in
NDB,
probably
caused
by deadlock" },
{ 237
4351
DMEC
TO
280
DMEC
NS
270
DMEC
NS
1223
DMEC
NS
4023
DMEC
NS
4030
DMEC
NS
4034
DMEC
NS
DOWN
702
DMEC
IT
REQUEST TO NON-MASTER
787
DMEC
IT
1703
DMEC
IT
4007
DMEC
UR
4008
DMEC
UR
4009
HA_ERR_NO_CONNECTION
UR
CLUSTER FAILURE
4012
DMEC
UR
4013
DMEC
UR
4024
DMEC
UR
896
IE
DMEC
901
DMEC
IE
202
DMEC
IE
202
203
DMEC
IE
203
207
DMEC
IE
207
208
DMEC
IE
208
209
DMEC
IE
220
DMEC
IE
220
230
DMEC
IE
230
232
DMEC
IE
232
238
DMEC
IE
238
271
DMEC
IE
272
DMEC
IE
276
DMEC
IE
276
277
DMEC
IE
277
278
DMEC
IE
278
287
DMEC
IE
INDEX CORRUPTED
290
DMEC
IE
293
DMEC
IE
292
DMEC
IE
631
DMEC
IE
631
632
DMEC
IE
632
706
DMEC
IE
781
DMEC
IE
782
DMEC
IE
809
DMEC
IE
809
812
DMEC
IE
812
833
DMEC
IE
833
871
DMEC
IE
871
882
DMEC
IE
882
883
DMEC
IE
883
887
DMEC
IE
887
888
DMEC
IE
888
890
DMEC
IE
890
4000
DMEC
IE
4001
DMEC
IE
4005
DMEC
IE
4011
DMEC
IE
TRIBUTES TO READ
394
4107
DMEC
IE
4108
DMEC
IE
4109
DMEC
IE
4110
DMEC
IE
4111
DMEC
IE
4113
DMEC
IE
4320
DMEC
IE
4321
DMEC
IE
4344
DMEC
IE
4345
DMEC
IE
4346
DMEC
IE
4347
DMEC
IE
4348
DMEC
IE
4349
DMEC
IE
4350
DMEC
IE
4731
DMEC
IE
306
DMEC
IE
772
HA_WRONG_CREATE_OPTION
IE
749
HA_WRONG_CREATE_OPTION
IE
1502
DMEC
IE
1505
DMEC
IE
INVALID FILEGROUP
1506
DMEC
IE
1507
DMEC
IE
1510
DMEC
IE
1511
DMEC
IE
OUT OF MEMORY
1513
DMEC
IE
1300
DMEC
IE
UNDEFINED ERROR
1301
DMEC
IE
1302
DMEC
IE
1304
DMEC
IE
SEQUENCE FAILURE
1305
DMEC
IE
1322
DMEC
IE
1323
DMEC
IE
1323
1324
DMEC
IE
1325
DMEC
IE
1326
DMEC
IE
1327
DMEC
IE
1327
1340
DMEC
IE
1700
DMEC
IE
UNDEFINED ERROR
4263
DMEC
IE
395
4267
DMEC
IE
4268
DMEC
IE
4269
DMEC
IE
4270
DMEC
IE
4273
DMEC
IE
4274
DMEC
IE
4003
NI
DMEC
Description
NE
Success
NO ERROR
AE
Permanent error
APPLICATION ERROR
CE
Permanent error
ND
Permanent error
NO DATA FOUND
CV
Permanent error
CONSTRAINT VIOLATION
SE
Permanent error
SCHEMA ERROR
OE
Permanent error
UD
Permanent error
IS
Permanent error
INSUFFICIENT SPACE
TR
Temporary error
NR
Temporary error
OL
Temporary error
OVERLOAD ERROR
TO
Temporary error
TIMEOUT EXPIRED
NS
Temporary error
NODE SHUTDOWN
IT
Temporary error
INTERNAL TEMPORARY
UR
Unknown result
UE
Unknown result
IE
Permanent error
INTERNAL ERROR
NI
Permanent error
This section contains exit codes and error messages given when a data node process stops prematurely.
Error Classification
Error Text
NDXRE
BD_EXIT_GENE
RIC
GENERIC ERROR
NDXIE
BD_EXIT_PRGE
RR
ASSERTION
NDXCE
BD_EXIT_NODE
_NOT_IN_CONF
IG
NDXIE
BD_EXIT_SYST
EM_ERROR
NDXIE
BD_EXIT_INDE
X_NOTINRANGE
NDXAE
BD_EXIT_ARBI
T_SHUTDOWN
NODE LOST CONNECTION TO OTHER NODES AND CAN NOT FORM A UNPARTITIONED
CLUSTER, PLEASE INVESTIGATE IF THERE ARE ERROR(S) ON OTHER NODE(S)
NDXAE
BD_EXIT_PART
ITIONED_SHUT
DOWN
NDXAE
BD_EXIT_NODE
_DECLARED_DE
AD
NDXIE
BD_EXIT_POIN
TER_NOTINRAN
GE
NDXRE
BD_EXIT_SR_O
THERNODEFAILED
NDXRE
BD_EXIT_NODE
_NOT_DEAD
NDXFI
BD_EXIT_SR_R
EDOLOG
AGAIN
397
Error Code
Error Classification
Error Text
NDXFI
BD_EXIT_SR_S
CHEMAFILE
2311
XIE
NDXCR
BD_EXIT_NO_M
ORE_UNDOLOG
NDXFI
BD_EXIT_SR_U
NDOLOG
NDXRE
BD_EXIT_SING
LE_USER_MODE
DATA NODE IS NOT ALLOWED TO GET ADDED TO THE CLUSTER WHILE IT IS IN SINGLE
NDXCE
BD_EXIT_MEMA
LLOC
NDXIE
BD_EXIT_BLOC
K_JBUFCONGES
TION
NDXIE
BD_EXIT_TIME
_QUEUE_SHORT
NDXIE
BD_EXIT_TIME
_QUEUE_LONG
NDXIE
BD_EXIT_TIME
_QUEUE_DELAY
NDXIE
BD_EXIT_TIME
_QUEUE_INDEX
NDXIE
BD_EXIT_BLOC
K_BNR_ZERO
NDXIE
BD_EXIT_WRON
G_PRIO_LEVEL
NDXIE
BD_EXIT_NDBR
EQUIRE
NDXIE
BD_EXIT_NDBA
SSERT
NDXNE
BD_EXIT_ERRO
R_INSERT
NDXCE
BD_EXIT_INVA
LID_CONFIG
NDXCE
BD_EXIT_RESO
URCE_ALLOC_E
RROR
USER MODE
398
Error Code
Error Classification
Error Text
NDXIE
BD_EXIT_OS_S
IGNAL_RECEIVED
NDXRE
BD_EXIT_SR_R
ESTARTCONFLICT
5.3.1.2. VM Errors
This section contains ndbd error codes that are associated with problems in the VM (virtal machine) NDB kernel block.
Error Code
Error Classification
Error Text
NDXCR
BD_EXIT_OUT_
OF_LONG_SIGN
AL_MEMORY
NDXIE
BD_EXIT_WATC
HDOG_TERMINA
TE
NDXCR
BD_EXIT_SIGN
AL_LOST_SEND
_BUFFER_FULL
NDXIE
BD_EXIT_SIGN
AL_LOST
NDXIE
BD_EXIT_ILLE
GAL_SIGNAL
NDXCE
BD_EXIT_CONN
ECTION_SETUP_F
AILED
Error Classification
Error Text
NDXCE
BD_EXIT_REST
ART_TIMEOUT
TOTAL RESTART TIME TOO LONG, CONSIDER INCREASING STARTFAILURETIMEOUT OR INVESTIGATE ERROR(S) ON OTHER NODE(S)
NDXRE
BD_EXIT_REST
ART_DURING_S
HUTDOWN
NODE STARTED WHILE NODE SHUTDOWN IN PROGRESS. PLEASE WAIT UNTIL SHUTDOWN
COMPLETE BEFORE STARTING NODE
399
Error Classification
Error Text
NDXFL
BD_EXIT_MAX_
CRASHED_REPL
ICAS
NDXRE
BD_EXIT_MAST
ER_FAILURE_D
URING_NR
NDXAE
BD_EXIT_LOST
_NODE_GROUP
NDXFI
BD_EXIT_NO_R
ESTORABLE_REPLICA
Error Classification
NDXCR
BD_EXIT_SR_O
UT_OF_INDEXM
EMORY
Error Text
OUT OF INDEX MEMORY DURING SYSTEM RESTART, PLEASE INCREASE INDEXMEMORY
Error Classification
NDXCR
BD_EXIT_SR_O
UT_OF_DATAME
MORY
Error Text
OUT OF DATA MEMORY DURING SYSTEM RESTART, PLEASE INCREASE DATAMEMORY
Error Classification
NDXIE
BD_EXIT_AFS_
NOPATH
Error Text
NO FILE SYSTEM PATH
400
Error Code
Error Classification
Error Text
2802
XIE
CHANNEL IS FULL
2803
XIE
NO MORE THREADS
NDXIE
BD_EXIT_AFS_
PARAMETER
BAD PARAMETER
NDXCE
BD_EXIT_AFS_
INVALIDPATH
NDXCR
BD_EXIT_AFS_
MAXOPEN
NDXIE
BD_EXIT_AFS_
ALREADY_OPEN
NDXIE
BD_EXIT_AFS_
ENVIRONMENT
NDXIE
BD_EXIT_AFS_
TEMP_NO_ACCE
SS
NDXFF
BD_EXIT_AFS_
DISK_FULL
NDXCE
BD_EXIT_AFS_
PERMISSION_DENIED
NDXCE
BD_EXIT_AFS_
INVALID_PARAM
NDXIE
BD_EXIT_AFS_
UNKNOWN
NDXIE
BD_EXIT_AFS_
NO_MORE_RESO
URCES
NDXFI
BD_EXIT_AFS_
NO_SUCH_FILE
NDXFI
BD_EXIT_AFS_
READ_UNDERFL
OW
READ UNDERFLOW
NDXFI
BD_EXIT_INVA
LID_LCP_FILE
INVALID LCP
NDXRE
BD_EXIT_INSU
FFICENT_NODES
ND-
UNSUPPORTED VERSION
XRE
401
Error Code
Error Classification
Error Text
BD_EXIT_UNSU
PPORTED_VERSION
Error Classification
Error Text
XUE
NO MESSAGE SLOGAN FOUND (PLEASE REPORT A BUG IF YOU GET THIS ERROR CODE)
Error Classification
Error Text
XNE
Success
NO ERROR
XUE
Unknown
UNKNOWN
XIE
XST_R
XCE
Permanent
error, external action needed
CONFIGURATION ERROR
XAE
Temporary
error, restart node
ARBITRATION ERROR
XRE
Temporary
error, restart node
RESTART ERROR
XCR
Permanent
error, external action needed
XFF
Permanent
error, external action needed
XFI
Ndbd file
NDBD FILE SYSTEM INCONSISTENCY ERROR, PLEASE REPORT A BUG
system error, restart
node initial
XFL
Ndbd file
NDBD FILE SYSTEM LIMIT EXCEEDED
system error, restart
node initial
BUG
This section lists error codes, names, and messages that are written to the cluster log in the event of transporter errors.
Error Code Error Name
Error Text
0x00
TE_NO_ERROR
NO ERROR
0x01
TE_ERROR_CLOSING_SOCKET
0x02
TE_ERROR_IN_SELECT_BEFORE_ACCEPT
0x03
TE_INVALID_MESSAGE_LENGTH
0x04
TE_INVALID_CHECKSUM
0x05
TE_COULD_NOT_CREATE_SOCKET
0x06
TE_COULD_NOT_BIND_SOCKET
0x07
TE_LISTEN_FAILED
0x08
TE_ACCEPT_RETURN_ERROR
0x0b
TE_SHM_DISCONNECT
0x0c
TE_SHM_IPC_STAT
0x0d
TE_SHM_UNABLE_TO_CREATE_SEGMENT
0x0e
TE_SHM_UNABLE_TO_ATTACH_SEGMENT
0x0f
TE_SHM_UNABLE_TO_REMOVE_SEGMENT
0x10
TE_TOO_SMALL_SIGID
0x11
TE_TOO_LARGE_SIGID
0x12
TE_WAIT_STACK_FULL
0x13
TE_RECEIVE_BUFFER_FULL
0x14
TE_SIGNAL_LOST_SEND_BUFFER_FULL
0x15
TE_SIGNAL_LOST
0x16
TE_SEND_BUFFER_FULL
0x0017
TE_SCI_LINK_ERROR
0x18
TE_SCI_UNABLE_TO_START_SEQUENCE
COULD NOT START A SEQUENCE, BECAUSE SYSTEM RESOURCES ARE EXUMED OR NO SEQUENCE HAS BEEN
CREATED
0x19
TE_SCI_UNABLE_TO_REMOVE_SEQUENCE
0x1a
TE_SCI_UNABLE_TO_CREATE_SEQUENCE
0x1b
TE_SCI_UNRECOVERABLE_DATA_TFX_ERROR
0x1c
TE_SCI_CANNOT_INIT_LOCALSEGMENT
0x1d
TE_SCI_CANNOT_MAP_REMOTESEGMENT
0x1e
TE_SCI_UNABLE_TO_UNMAP_SEGMENT
403
Error Text
0x1f
TE_SCI_UNABLE_TO_REMOVE_SEGMENT
0x20
TE_SCI_UNABLE_TO_DISCONNECT_SEGMENT
0x21
TE_SHM_IPC_PERMANENT
0x22
TE_SCI_UNABLE_TO_CLOSE_CHANNEL
404
ndb_node_id_out.log
Sample output:
2006-09-12 20:13:24 [ndbd] INFO
-- Angel pid: 13677 ndb pid: 13678
2006-09-12 20:13:24 [ndbd] INFO
-- NDB Cluster -- DB node 1
2006-09-12 20:13:24 [ndbd] INFO
-- Version 5.1.12 (beta) -2006-09-12 20:13:24 [ndbd] INFO
-- Configuration fetched at localhost port 1186
2006-09-12 20:13:24 [ndbd] INFO
-- Start initiated (version 5.1.12)
2006-09-12 20:13:24 [ndbd] INFO
-- Ndbd_mem_manager::init(1) min: 20Mb initial: 20Mb
WOPool::init(61, 9)
RWPool::init(82, 13)
RWPool::init(a2, 18)
RWPool::init(c2, 13)
RWPool::init(122, 17)
RWPool::init(142, 15)
WOPool::init(41, 8)
RWPool::init(e2, 12)
RWPool::init(102, 55)
WOPool::init(21, 8)
Dbdict: name=sys/def/SYSTAB_0,id=0,obj_ptr_i=0
Dbdict: name=sys/def/NDB$EVENTS_0,id=1,obj_ptr_i=1
m_active_buckets.set(0)
ndb_node_id_signal.log
This file contains a log of all signals sent to or from the data node.
Note
This file is created only if the SendSignalId parameter is enabled, which is true only for -debug builds.
ndb_node_id.pid
This file contains the data node's process ID; it is created when the ndbd process is started.
The location of these files is determined by the value of the DataDir configuration parameter. See DataDir.
Files:
data-nodeid.dat
undo-nodeid.dat
405
Directories:
LCP: This directory holds 3 subdirectories, named 0, 1, and 2, which contain local checkpoint data files (one per checkpoint
see Configuring MySQL Cluster Parameters for Local Checkpoints).
These subdirectories each contain a number of files whose names follow the pattern TNFM.Data, where N is a table ID and and
M is a fragment number. Each data node typically has one primary fragment and one backup fragment. This means that, for a
MySQL Cluster having 2 data nodes, and with NoOfReplicas = 2, M is either 0 to 1. For a 4-node cluster with NoOfReplicas = 2, M is either 0 or 2 on node group 1, and either 1 or 3 on node group 2.
In MySQL Cluster NDB 7.0 and later, when using ndbmtd there may be more than one primary fragment per node. In this case,
M is a number in the range of 0 to the number of LQH worker threads in the entire cluster, less 1. The number of fragments on
each data node is equal to the number of LQH on that node times NoOfReplicas.
Note
Increasing MaxNoOfExecutionThreads does not change the number of fragments used by existing tables; only
newly-created tables automatically use the new fragment count. To force the new fragment count to be used by an existing
table after increasing MaxNoOfExecutionThreads, you must perform an ALTER TABLE ... REORGANIZE
PARTITION statement (just as when adding new node groups in MySQL Cluster NDB 7.0 and later).
A set of directories T0, T1, T2, ..., each of which contains an S0.TableList file.
Directories named D8, D9, D10, and D11, each of which contains a directory named DBLQH.
In each case, the DBLQH directory contains N files named S0.Fraglog, S1.FragLog, S2.FragLog, ...,
SN.FragLog, where N is equal to the value of the NoOfFragmentLogFiles configuration parameter.
The DBLQH directories also contain the redo log files.
DBDIH: This directory contains the file PX.sysfile, which records information such as the last GCI, restart status, and
node group membership of each node; its structure is defined in storage/
ndb/src/kernel/blocks/dbdih/Sysfile.hpp in the MySQL Cluster source tree. In addition, the
SX.FragList files keep records of the fragments belonging to each table.
One or more datafiles associated with a tablespace that uses the logfile group for undo logging
Both undo logfiles and datafiles are created in the data directory (DataDir) of each cluster data node. The relationship of these files
406
with their logfile group and tablespace are shown in the following diagram:
Disk Data files and the SQL commands used to create and drop them are discussed in depth in MySQL Cluster Disk Data Tables.
They are intended only for use in troubleshooting, debugging, and similar activities by MySQL developers, QA, and support personnel.
Due to the way in which DUMP commands interact with memory, they can cause a running MySQL Cluster to malfunction or even
to fail completely when used.
The formats, arguments, and even availability of these commands are not guaranteed to be stable. All of this information is subject to
change at any time without prior notice.
For the preceding reasons, DUMP commands are neither intended nor warranted for use in a production environment by end-users.
General syntax:
ndb_mgm> node_id DUMP code [arguments]
407
This causes the contents of one or more NDB registers on the node with ID node_id to be dumped to the Cluster log. The registers affected are determined by the value of code. Some (but not all) DUMP commands accept additional arguments; these are noted and
described where applicable.
Individual DUMP commands are listed by their code values in the sections that follow. For convenience in locating a given DUMP code,
they are divided by thousands.
Each listing includes this information:
The relevant NDB kernel block or blocks (see Section 6.4, NDB Kernel Blocks, for information about these)
The DUMP code symbol where defined; if undefined, this is indicated using a triple dash: ---.
Sample output; unless otherwise stated, it is assumed that each DUMP command is invoked as shown here:
ndb_mgm> 2 DUMP code
Generally, this is from the cluster log; in some cases, where the output may be generated in the node log instead, this is indicated.
Where the DUMP command produces errors, the output is generally taken from the error log.
Where applicable, additional information such as possible extra arguments, warnings, state or other values returned in the DUMP
command's output, and so on. Otherwise its absence is indicated with [N/A].
Note
DUMP command codes are not necessarily defined sequentially. For example, codes 2 through 12 are currently undefined,
and so are not listed. However, individual DUMP code values are subject to change, and there is no guarantee that a given
code value will continue to be defined for the same purpose (or defined at all, or undefined) over time.
There is also no guarantee that a given DUMP code even if currently undefined will not have serious consequences
when used on a running MySQL Cluster.
For information concerning other ndb_mgm client commands, see Commands in the MySQL Cluster Management Client.
Symbol
Kernel Block(s)
---
QMGR
Description. Dumps information about cluster start Phase 1 variables (see Section 6.5.4, STTOR Phase 1).
Sample Output.
Node
Node
Node
Node
Node
2:
2:
2:
2:
2:
creadyDistCom = 1, cpresident = 2
cpresidentAlive = 1, cpresidentCand = 2 (gci: 157807)
ctoStatus = 0
Node 2: ZRUNNING(3)
Node 3: ZRUNNING(3)
6.2.1.2. DUMP 13
Code
Symbol
Kernel Block(s)
13
---
CMVMI, NDBCNTR
408
6.2.1.3. DUMP 14
Code
Symbol
Kernel Block(s)
14
CommitAckMarkersSize
DBLQH, DBTC
6.2.1.4. DUMP 15
Code
Symbol
Kernel Block(s)
15
CommitAckMarkersDump
DBLQH, DBTC
6.2.1.5. DUMP 16
Code
Symbol
Kernel Block(s)
16
DihDumpNodeRestartInfo
DBDIH
6.2.1.6. DUMP 17
Code
Symbol
Kernel Block(s)
17
DihDumpNodeStatusInfo
DBDIH
409
Name
NOT_IN_CLUSTER
ALIVE
STARTING
DIED_NOW
DYING
DEAD
6.2.1.7. DUMP 18
Code
Symbol
Kernel Block(s)
18
DihPrintFragmentation
DBDIH
Description. Prints one entry per table fragment; lists the table number, fragment number, and list of nodes handling this fragment in
order of priority.
Sample Output.
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
6.2.1.8. DUMP 20
Code
Symbol
Kernel Block(s)
20
---
BACKUP
410
Additional Information. Can also be used to set these parameters, for example:
ndb_mgm> 2 DUMP 20 3 3 64 512
Sending dump signal with data:
0x00000014 0x00000003 0x00000003 0x00000040 0x00000200
Node 2: Backup: data: 3145728 log: 3145728 min: 65536 max: 524288
Warning
You must set each of these parameters to the same value on all nodes; otherwise, subsequent issuing of a START
BACKUP command crashes the cluster.
6.2.1.9. DUMP 21
Code
Symbol
Kernel Block(s)
21
---
BACKUP
Description. Sends a GSN_BACKUP_REQ signal to the node, causing that node to initiate a backup.
Sample Output.
Node 2: Backup 1 started from node 2
Node 2: Backup 1 started from node 2 completed
StartGCP: 158515 StopGCP: 158518
#Records: 2061 #LogRecords: 0
Data: 35664 bytes Log: 0 bytes
6.2.1.10. DUMP 22
Code
Symbol
Kernel Block(s)
22 backup_id
---
BACKUP
Description. Sends a GSN_FSREMOVEREQ signal to the node. This should remove the backup having backup ID backup_id from
the backup directory; however, it actually causes the node to crash.
Sample Output.
Time: Friday 16 February 2007 - 10:23:00
Status: Temporary error, restart node
Message: Assertion (Internal error, programming error or missing error message,
please report a bug)
Error: 2301
Error data: ArrayPool<T>::getPtr
Error object: ../../../../../storage/ndb/src/kernel/vm/ArrayPool.hpp line: 395
(block: BACKUP)
Program: ./libexec/ndbd
Pid: 27357
Trace: /usr/local/mysql-5.1/cluster/ndb_2_trace.log.4
Version: Version 5.1.16 (beta)
Additional Information.
Warning
It appears that any invocation of DUMP 22 causes the node or nodes to crash.
6.2.1.11. DUMP 23
Code
Symbol
Kernel Block(s)
23
---
BACKUP
411
Description. Dumps all backup records and file entries belonging to those records.
Note
The example shows a single record with a single file only, but there may be multiple records and multiple file lines within
each record.
Sample Output. With no backup in progress (BackupRecord shows as 0):
Node 2: BackupRecord 0: BackupId: 5 MasterRef: f70002 ClientRef: 0
Node 2: State: 2
Node 2: file 0: type: 3 flags: H'0
State
INITIAL
Description
DEFINING
DEFINED
STARTED
Creating triggers
SCANNING
Scanning fragments
STOPPING
Closing files
CLEANING
Freeing resources
ABORTING
Aborting backup
Types:
Value
Name
CTL_FILE
LOG_FILE
DATA_FILE
LCP_FILE
Flags:
Value
Name
0x01
BF_OPEN
0x02
BF_OPENING
0x04
BF_CLOSING
0x08
BF_FILE_THREAD
0x10
BF_SCAN_THREAD
0x20
BF_LCP_META
6.2.1.12. DUMP 24
412
Code
Symbol
Kernel Block(s)
24
---
BACKUP
2:
2:
2:
2:
Additional Information. If 2424 is passed as an argument (for example, 2 DUMP 24 2424), this causes an LCP.
6.2.1.13. DUMP 25
Code
Symbol
Kernel Block(s)
25
NdbcntrTestStopOnError
NDBCNTR
6.2.1.14. DUMP 70
Code
Symbol
70
NdbcntrStopNodes
Kernel Block(s)
Description.
Sample Output.
Symbol
Kernel Block(s)
400
NdbfsDumpFileStat-
NDBFS
413
Node 2:
Node 2:
Node 2:
Symbol
Kernel Block(s)
401
NdbfsDumpAllFiles
NDBFS
Description. Prints NDB file system file handles and states (OPEN or CLOSED).
Sample Output.
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
files: 27
CLOSED
CLOSED
CLOSED
CLOSED
CLOSED
CLOSED
OPEN
OPEN
OPEN
OPEN
OPEN
OPEN
OPEN
OPEN
OPEN
OPEN
CLOSED
CLOSED
CLOSED
CLOSED
CLOSED
CLOSED
CLOSED
CLOSED
CLOSED
CLOSED
CLOSED
Symbol
Kernel Block(s)
402
NdbfsDumpOpenFiles
NDBFS
Code
Symbol
Kernel Block(s)
403
NdbfsDumpIdleFiles
NDBFS
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
Symbol
Kernel Block(s)
404
---
NDBFS
Symbol
Kernel Block(s)
1000
DumpPageMemory
DBACC, DBTUP
Description. Prints data node mMemory usage (ACC & TUP), as both a number of data pages, and the percentage of DataMemory
and IndexMemory used.
Sample Output.
Node 2: Data usage is 8%(54 32K pages of total 640)
Node 2: Index usage is 1%(24 8K pages of total 1312)
Node 2: Resource 0 min: 0 max: 639 curr: 0
415
Note
When invoked as ALL DUMP 1000, this command reports memory usage for each data node separately, in turn.
Additional Information. Beginning with MySQL Cluster NDB 6.2.3 and MySQL Cluster NDB 6.3.0, you can use the ndb_mgm client REPORT MEMORYUSAGE to obtain this information (see Commands in the MySQL Cluster Management Client). Beginning with
MySQL Cluster NDB 7.1.0, you can also query the ndbinfo database for this information (see The ndbinfo memoryusage
Table).
Symbol
Kernel Block(s)
1223
---
DBDICT
Symbol
Kernel Block(s)
1224
---
DBDICT
Symbol
Kernel Block(s)
1225
---
DBDICT
416
Symbol
Kernel Block(s)
1226
---
DBDICT
Symbol
Kernel Block(s)
1332
LqhDumpAllDefinedTabs
DBACC
Description. Prints the states of all tables known by the local query handler (LQH).
Sample Output.
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
Symbol
Kernel Block(s)
1333
LqhDumpNoLogPages
DBACC
417
Additional Information. The redo log buffer is measured in 32KB pages, so the sample output can be interpreted as follows:
Symbol
Kernel Block(s)
2300
LqhDumpOneScanRec
DBACC
Description. [Unknown]
Sample Output. [Not available]
Additional Information. [N/A]
Symbol
Kernel Block(s)
2301
LqhDumpAllScanRec
DBACC
Symbol
Kernel Block(s)
2302
LqhDumpAllActiveScanRec
DBACC
Description. [Unknown]
Sample Output.
418
Symbol
Kernel Block(s)
2303
LqhDumpLcpState
DBACC
Description. [Unknown]
Sample Output.
Node
Node
Node
Node
Node
Node
Node
Symbol
Kernel Block(s)
2304
---
DBLQH
Description. This command causes all fragment log files and their states to be written to the data node's out file (in the case of the data
node having the node ID 1, this would be ndb_1_out.log). The number of these files is controlled by the NoFragmentLogFiles configuration parameter, whose default value is 16 in MySQL 5.1 and later releases.
Sample Output. The following is taken from ndb_1_out.log for a cluster with 2 data nodes:
LP 2 state: 0
file 0(32)
file 1(33)
file 2(34)
file 3(35)
file 4(36)
file 5(37)
file 6(38)
file 7(39)
file 8(40)
file 9(41)
file 10(42)
file 11(43)
file 12(44)
file 13(45)
file 14(46)
file 15(47)
LP 3 state: 0
file 0(48)
file 1(49)
file 2(50)
file 3(51)
file 4(52)
file 5(53)
file 6(54)
file 7(55)
file 8(56)
file 9(57)
419
file
file
file
file
file
file
10(58)
11(59)
12(60)
13(61)
14(62)
15(63)
FileChangeState:
FileChangeState:
FileChangeState:
FileChangeState:
FileChangeState:
FileChangeState:
0
0
0
0
0
0
logFileStatus:
logFileStatus:
logFileStatus:
logFileStatus:
logFileStatus:
logFileStatus:
1
1
1
1
1
1
currentMbyte:
currentMbyte:
currentMbyte:
currentMbyte:
currentMbyte:
currentMbyte:
0
0
0
0
0
0
currentFilepage
currentFilepage
currentFilepage
currentFilepage
currentFilepage
currentFilepage
0
0
0
0
0
0
Symbol
Kernel Block(s)
2305
---
DBLQH
Description. Show the states of all fragment log files (see Section 6.2.3.5, DUMP 2304), then kills the node.
Sample Output.
Time: Friday 16 February 2007 - 13:11:57
Status: Temporary error, restart node
Message: System error, node killed during node restart by other node
(Internal error, programming error or missing error message, please report a bug)
Error: 2303
Error data: Please report this as a bug. Provide as much info as possible,
expecially all the ndb_*_out.log files, Thanks. Shutting down node due to
failed handling of GCP_SAVEREQ
Error object: DBLQH (Line: 18619) 0x0000000a
Program: ./libexec/ndbd
Pid: 111
Time: Friday 16 February 2007 - 13:11:57
Status: Temporary error, restart node
Message: Error OS signal received (Internal error, programming error or
missing error message, please report a bug)
Error: 6000
Error data: Signal 6 received; Aborted
Error object: main.cpp
Program: ./libexec/ndbd
Pid: 11138
Trace: /usr/local/mysql-5.1/cluster/ndb_2_trace.log.2
Version: Version 5.1.16 (beta)
Additional Information. No error message written to cluster log when the node is killed. Node failure is made evident only by subsequent heartbeat failure messages.
Symbol
Kernel Block(s)
2308
---
DBLQH
420
Code
Symbol
Kernel Block(s)
2315
LqhErrorInsert5042
DBLQH
Description. [Unknown]
Sample Output. [N/A]
Additional Information. [N/A]
Symbol
Kernel Block(s)
---
Description. Dumps all operations on a given data node or data nodes, according to the type and other parameters defined by the operation filter or filters specified.
Sample Output. Dump all operations on data node 2, from API node 5:
ndb_mgm> 2 DUMP 2350 1 5
2006-10-09 13:16:49 [MgmSrvr] INFO
-- Node 2:
2006-10-09 13:16:49 [MgmSrvr] INFO
-- Node 2:
Tab: 4 frag: 0 TC: 3 API: 5(0x8035)transid: 0x31c
2006-10-09 13:16:49 [MgmSrvr] INFO
-- Node 2:
Additional information.
1.
Operation filter values. The operation filter (or filters) can take on the following values:
Value
Filter
table ID
API node ID
2.
Operation states. The normal states that may appear in the output from this command are listed here:
Transactions.
Prepared. The transaction coordinator is idle, waiting for the API to proceed
Completing. The transaction coordinator is completing the commit (after commit, some cleanup is needed)
Scan operations.
InQueue. The scan has not yet started, but rather is waiting in queue for other scans to complete
421
3.
Prepared. The operation is prepared, holding an appropriate lock, and waiting for commit or rollback to complete
Relation to NDB API. It is possible to match the output of DUMP 2350 to specific threads or Ndb objects. First suppose that you
dump all operations on data node 2 from API node 5, using table 4 only, like this:
ndb_mgm> 2 DUMP 2350 1 5 0 4
2006-10-09 13:16:49 [MgmSrvr] INFO
-- Node 2:
2006-10-09 13:16:49 [MgmSrvr] INFO
-- Node 2:
Tab: 4 frag: 0 TC: 3 API: 5(0x8035)transid: 0x31c
2006-10-09 13:16:49 [MgmSrvr] INFO
-- Node 2:
Suppose you are working with an Ndb instance named MyNdb, to which this operation belongs. You can see that this is the case by
calling the Ndb object's getReference() method, like this:
printf("MyNdb.getReference(): 0x%x\n", MyNdb.getReference());
The high 16 bits of the value shown corresponds to the number in parentheses from the OP line in the DUMP command's output
(8035). For more about this method, see Section 2.3.8.1.17, Ndb::getReference().
This command was added in MySQL Cluster NDB 6.1.12 and MySQL Cluster NDB 6.2.2.
Symbol
Kernel Block(s)
---
In this case, there is a single operation reported on node 2, whose operation ID is 3. To obtain the transaction ID and primary key, we
use the node ID and operation ID with DUMP 2352 as shown here:
ndb_mgm> 2 dump 2352 3
2006-10-11 13:31:31 [MgmSrvr] INFO
Additional Information. Use DUMP 2350 to obtain an operation ID. See Section 6.2.3.9, DUMP 2350, and the previous example.
This command was added in MySQL Cluster NDB 6.1.12 and MySQL Cluster NDB 6.2.2.
Symbol
Kernel Block(s)
2400 record_id
AccDumpOneScanRec
DBACC
Additional Information. For dumping all scan records, see Section 6.2.3.12, DUMP 2401.
Symbol
Kernel Block(s)
2401
AccDumpAllScanRec
DBACC
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
Node
Node
Node
Node
Node
Additional Information. If you want to dump a single scan record, given its record ID, see Section 6.2.3.11, DUMP 2400; for
dumping all active scan records, see Section 6.2.3.13, DUMP 2402.
Symbol
Kernel Block(s)
2402
AccDumpAllActiveScanRec
DBACC
Additional Information. To dump all scan records (active or not), see Section 6.2.3.12, DUMP 2401.
Symbol
Kernel Block(s)
2403 record_id
AccDumpOneOperationRec
DBACC
423
Description. [Unknown]
Sample Output. (For 2 DUMP 1:)
Node
Node
Node
Node
Node
Node
Node
Node
Node
2:
2:
2:
2:
2:
2:
2:
2:
2:
Symbol
Kernel Block(s)
2404
AccDumpNumOpRecs
DBACC
Description. Number the number of operation records (total number, and number free).
Sample Output.
Node 2: Dbacc::OperationRecords: num=69012, free=32918
Symbol
2405
AccDumpFreeOpRecs
Kernel Block(s)
Description. Unknown: No output results if this command is called without additional arguments; if an extra argument is used, this
command crashes the data node.
Sample Output. (For 2 DUMP 2405 1:)
Time: Saturday 17 February 2007 - 18:33:54
Status: Temporary error, restart node
Message: Job buffer congestion (Internal error, programming error or
missing error message, please report a bug)
Error: 2334
Error data: Job Buffer Full
Error object: APZJobBuffer.C
Program: ./libexec/ndbd
Pid: 27670
Trace: /usr/local/mysql-5.1/cluster/ndb_2_trace.log.1
Version: Version 5.1.16 (beta)
Symbol
Kernel Block(s)
2406
AccDumpNotFreeOpRecs
DBACC
Description. Unknown: No output results if this command is called without additional arguments; if an extra argument is used, this
command crashes the data node.
Sample Output. (For 2 DUMP 2406 1:)
424
Symbol
Kernel Block(s)
2500
TcDumpAllScanFragRec
DBTC
Symbol
Kernel Block(s)
2501
TcDumpOneScanFragRec
DBTC
Description. No output if called without any additional arguments. With additional arguments, it kills the data node.
Sample Output. (For 2 DUMP 2501 1:)
Time: Saturday 17 February 2007 - 18:41:41
Status: Temporary error, restart node
Message: Assertion (Internal error, programming error or missing error
message, please report a bug)
Error: 2301
Error data: ArrayPool<T>::getPtr
Error object: ../../../../../storage/ndb/src/kernel/vm/ArrayPool.hpp line: 345
(block: DBTC)
Program: ./libexec/ndbd
Pid: 28239
Trace: /usr/local/mysql-5.1/cluster/ndb_2_trace.log.1
Version: Version 5.1.16 (beta)
Symbol
Kernel Block(s)
2502
TcDumpAllScanRec
DBTC
425
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Symbol
Kernel Block(s)
2503
TcDumpAllActiveScanRec
DBTC
Symbol
Kernel Block(s)
2504 record_id
TcDumpOneScanRec
DBTC
Description. Dumps a single scan record having the record ID record_id. (For dumping all scan records, see Section 6.2.3.20,
DUMP 2502.)
Sample Output. (For 2 DUMP 2504 1:)
Node
Node
Node
Node
Additional Information. The attributes in the output of this command are described as follows:
426
Value
State
IDLE
WAIT_SCAN_TAB_INFO
WAIT_AI
WAIT_FRAGMENT_COUNT
RUNNING
CLOSING_SCAN
nextfrag. ID of the next fragment to be scanned. Used by a scan fragment process when it is ready for the next fragment.
Symbol
Kernel Block(s)
2505
TcDumpOneApiConnectRec
DBTC
Description. [Unknown]
Sample Output.
...
Symbol
Kernel Block(s)
2506
TcDumpAllApiConnectRec
DBTC
Description. [Unknown]
Sample Output.
Node
Node
Node
Node
427
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Additional Information. If the default settings are used, the output from this command is likely to exceed the maximum log file size.
Symbol
Kernel Block(s)
2507
TcSetTransactionTimeout
DBTC
Description. Apparently requires an extra argument, but is not currently known with certainty.
Sample Output.
...
Symbol
Kernel Block(s)
2508
TcSetApplTransactionTimeout
DBTC
Description. Apparently requires an extra argument, but is not currently known with certainty.
Sample Output.
...
Symbol
Kernel Block(s)
2509
StartTcTimer
DBTC
Description. [Unknown]
Sample Output.
...
428
Symbol
Kernel Block(s)
2510
StopTcTimer
DBTC
Description. [Unknown]
Sample Output.
...
Symbol
Kernel Block(s)
2511
StartPeriodicTcTimer
DBTC
Description. [Unknown]
Sample Output.
...
Symbol
Kernel Block(s)
2512 [delay]
TcStartDumpIndexOpCount
DBTC
Description. Dumps the value of MaxNoOfConcurrentOperations, and the current resource usage, in a continuous loop. The
delay time between reports can optionally be specified (in seconds), with the default being 1 and the maximum value being 25 (values
greater than 25 are silently coerced to 25).
Sample Output. (Single report:)
Node 2: IndexOpCount: pool: 8192 free: 8192
Additional Information. There appears to be no way to disable the repeated checking of MaxNoOfConcurrentOperations once
started by this command, except by restarting the data node. It may be preferable for this reason to use DUMP 2513 instead (see Section 6.2.3.31, DUMP 2513).
Symbol
2513
TcDumpIndexOpCount
Kernel Block(s)
Description. Dumps the value of MaxNoOfConcurrentOperations, and the current resource usage.
Sample Output.
Node 2: IndexOpCount: pool: 8192 free: 8192
429
Additional Information. Unlike the continuous checking done by DUMP 2512 the check is performed only once (see Section 6.2.3.30, DUMP 2512).
Symbol
Kernel Block(s)
2514
---
DBTC
Description. [Unknown]
Sample Output.
Node
Node
Node
Node
Node
Node
2:
2:
2:
3:
3:
2:
Symbol
Kernel Block(s)
2515
---
DBTC
Description. Appears to kill all data nodes in the cluster. Purpose unknown.
Sample Output. From the node for which the command is issued:
Time: Friday 16 February 2007 - 13:52:32
Status: Temporary error, restart node
Message: Assertion (Internal error, programming error or missing error
message, please report a bug)
Error: 2301
Error data: Illegal signal received (GSN 395 not added)
Error object: Illegal signal received (GSN 395 not added)
Program: ./libexec/ndbd
Pid: 14256
Trace: /usr/local/mysql-5.1/cluster/ndb_2_trace.log.1
Version: Version 5.1.16 (beta)
Symbol
Kernel Block(s)
data_node_id 2550
transaction_filter+
---
---
430
Description. Dumps all transaction from data node data_node_id meeting the conditions established by the transaction filter or filters specified.
Sample Output. Dump all transactions on node 2 which have been inactive for 30 seconds or longer:
ndb_mgm> 2
2006-10-09
2006-10-09
2006-10-09
DUMP 2550 4 30
13:16:49 [MgmSrvr] INFO
13:16:49 [MgmSrvr] INFO
13:16:49 [MgmSrvr] INFO
Additional Information. The following values may be used for transaction filters. The filter value must be followed by one or more
node IDs or, in the case of the last entry in the table, by the time in seconds that transactions have been inactive:
Value
Filter
API node ID
This command was added in MySQL Cluster NDB 6.1.12 and MySQL Cluster NDB 6.2.2.
Symbol
Kernel Block(s)
260
CmvmiDumpConnections
CMVMI
Description. Shows status of connections between all cluster nodes. When the cluster is operating normally, every connection has the
same status.
Sample Output.
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
3:
3:
3:
3:
3:
3:
3:
3:
3:
4:
4:
4:
4:
4:
4:
4:
4:
4:
Connection
Connection
Connection
Connection
Connection
Connection
Connection
Connection
Connection
Connection
Connection
Connection
Connection
Connection
Connection
Connection
Connection
Connection
to
to
to
to
to
to
to
to
to
to
to
to
to
to
to
to
to
to
1 (MGM) is connected
2 (MGM) is trying to connect
3 (DB) does nothing
4 (DB) is connected
7 (API) is connected
8 (API) is connected
9 (API) is trying to connect
10 (API) is trying to connect
11 (API) is trying to connect
1 (MGM) is connected
2 (MGM) is trying to connect
3 (DB) is connected
4 (DB) does nothing
7 (API) is connected
8 (API) is connected
9 (API) is trying to connect
10 (API) is trying to connect
11 (API) is trying to connect
Additional Information. The message is trying to connect actually means that the node in question was not started. This
can also be seen when there are unused [api] or [mysql] sections in the config.ini file nodes configured in other words
when there are spare slots for API or SQL nodes.
Symbol
Kernel Block(s)
2601
CmvmiDumpLongSignalMemory
CMVMI
Description. [Unknown]
Sample Output.
Node 2: Cmvmi: g_sectionSegmentPool size: 4096 free: 4096
431
Symbol
Kernel Block(s)
2602
CmvmiSetRestartOnErrorInsert
CMVMI
Description. [Unknown]
Sample Output.
...
Symbol
Kernel Block(s)
2603
CmvmiTestLongSigWithDelay
CMVMI
Description. [Unknown]
Sample Output.
...
Symbol
Kernel Block(s)
2604
CmvmiDumpSubscriptions
CMVMI
Note
This output appears in the ndb_node_id_out.log file (local to each data node) and not in the management server
(global) cluster log file.
Sample Output.
2007-04-17
2007-04-17
2007-04-17
2007-04-17
2007-04-17
2007-04-17
2007-04-17
2007-04-17
2007-04-17
2007-04-17
2007-04-17
2007-04-17
2007-04-17
2007-04-17
17:10:54
17:10:54
17:10:54
17:10:54
17:10:54
17:10:54
17:10:54
17:10:54
17:10:54
17:10:54
17:10:54
17:10:54
17:10:54
17:10:54
[ndbd]
[ndbd]
[ndbd]
[ndbd]
[ndbd]
[ndbd]
[ndbd]
[ndbd]
[ndbd]
[ndbd]
[ndbd]
[ndbd]
[ndbd]
[ndbd]
INFO
INFO
INFO
INFO
INFO
INFO
INFO
INFO
INFO
INFO
INFO
INFO
INFO
INFO
---------------
List subscriptions:
Subscription: 0, nodeId: 1, ref: 0x80000001
Category 0 Level 7
Category 1 Level 7
Category 2 Level 7
Category 3 Level 7
Category 4 Level 7
Category 5 Level 8
Category 6 Level 7
Category 7 Level 7
Category 8 Level 15
Category 9 Level 7
Category 10 Level 7
Category 11 Level 15
Additional Information. The output lists all event subscriptions; for each subscription a header line and a list of categories with their
current log levels is printed. The following information is included in the output:
432
Category. The cluster log category, as listed in Event Reports Generated in MySQL Cluster (see also the file storage/
ndb/include/mgmapi/mgmapi_config_parameters.h).
Symbol
Kernel Block(s)
5900
LCPContinue
DBLQH
Description. [Unknown]
Sample Output.
...
Symbol
Kernel Block(s)
7000
---
DBDIH
433
Symbol
Kernel Block(s)
7001
---
DBDIH
Symbol
Kernel Block(s)
7002
---
DBDIH
Description. [Unknown]
Sample Output.
Node 2: cnoOfActiveTables = 4, cgcpDelay = 2000
Node 2: cdictblockref = 16384002, cfailurenr = 1
Node 2: con_lineNodes = 2, reference() = 16121858, creceivedfrag = 0
Symbol
Kernel Block(s)
7003
---
DBDIH
Description. [Unknown]
Sample Output.
Node 2: cfirstAliveNode = 2, cgckptflag = 0
Node 2: clocallqhblockref = 16187394, clocaltcblockref = 16056322, cgcpOrderBlocked = 0
Node 2: cstarttype = 0, csystemnodes = 2, currentgcp = 438
Symbol
Kernel Block(s)
7004
---
DBDIH
Description. [Unknown]
Sample Output.
Node 2: cmasterdihref = 16121858, cownNodeId = 2, cnewgcp = 438
Node 2: cndbStartReqBlockref = 16449538, cremainingfrags = 1268
Node 2: cntrlblockref = 16449538, cgcpSameCounter = 16, coldgcp = 437
434
Symbol
Kernel Block(s)
7005
---
DBDIH
Description. [Unknown]
Sample Output.
Node 2: crestartGci = 1
Symbol
Kernel Block(s)
7006
---
DBDIH
Description. [Unknown]
Sample Output.
Node 2: clcpDelay = 20, cgcpMasterTakeOverState = 0
Node 2: cmasterNodeId = 2
Node 2: cnoHotSpare = 0, c_nodeStartMaster.startNode = -256, c_nodeStartMaster.wait = 0
Symbol
Kernel Block(s)
7007
---
DBDIH
Description. [Unknown]
Sample Output.
Node 2: c_nodeStartMaster.failNr = 1
Node 2: c_nodeStartMaster.startInfoErrorCode = -202116109
Node 2: c_nodeStartMaster.blockLcp = 0, c_nodeStartMaster.blockGcp = 0
Symbol
Kernel Block(s)
7008
---
DBDIH
Description. [Unknown]
Sample Output.
Node 2: cfirstDeadNode = -256, cstartPhase = 7, cnoReplicas = 2
Node 2: cwaitLcpSr = 0
435
Symbol
Kernel Block(s)
7009
---
DBDIH
Description. [Unknown]
Sample Output.
Node 2: ccalcOldestRestorableGci = 1, cnoOfNodeGroups = 1
Node 2: cstartGcpNow = 0
Node 2: crestartGci = 1
Symbol
Kernel Block(s)
7010
---
DBDIH
Description. [Unknown]
Sample Output.
Node 2: cminHotSpareNodes = 0, c_lcpState.lcpStatusUpdatedPlace = 9843, cLcpStart = 1
Node 2: c_blockCommit = 0, c_blockCommitNo = 0
Symbol
Kernel Block(s)
7011
---
DBDIH
Description. [Unknown]
Sample Output.
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
2:
Code
Symbol
Kernel Block(s)
7012
---
DBDIH
Description. [Unknown]
Sample Output.
Node
Node
Node
Node
Node
Node
2:
2:
2:
2:
2:
2:
ParticipatingDIH = 0000000000000000
ParticipatingLQH = 0000000000000000
m_LCP_COMPLETE_REP_Counter_DIH = [SignalCounter: m_count=0 0000000000000000]
m_LCP_COMPLETE_REP_Counter_LQH = [SignalCounter: m_count=0 0000000000000000]
m_LAST_LCP_FRAG_ORD = [SignalCounter: m_count=0 0000000000000000]
m_LCP_COMPLETE_REP_From_Master_Received = 0
Symbol
Kernel Block(s)
7013
DihDumpLCPState
DBDIH
Description. [Unknown]
Sample Output.
Node 2: lcpStatus = 0 (update place = 9843)
Node 2: lcpStart = 1 lcpStopGcp = 1 keepGci = 1 oldestRestorable = 1
Node 2: immediateLcpStart = 0 masterLcpNodeId = 2
Symbol
Kernel Block(s)
7014
DihDumpLCPMasterTakeOver
DBDIH
Description. [Unknown]
Sample Output.
Node 2: c_lcpMasterTakeOverState.state = 0 updatePlace = 11756 failedNodeId = -202116109
Node 2: c_lcpMasterTakeOverState.minTableId = 4092851187 minFragId = 4092851187
Symbol
Kernel Block(s)
7015
---
DBDIH
Description. [Unknown]
Sample Output.
Node
Node
Node
Node
Node
Node
437
Node
Node
Node
Node
Node
Node
Symbol
Kernel Block(s)
7016
DihAllAllowNodeStart
DBDIH
Description. [Unknown]
Sample Output.
...
Symbol
Kernel Block(s)
7017
DihMinTimeBetweenLCP
DBDIH
Description. [Unknown]
Sample Output.
...
Symbol
Kernel Block(s)
7018
DihMaxTimeBetweenLCP
DBDIH
Description. [Unknown]
Sample Output.
...
Symbol
Kernel Block(s)
7020
---
DBDIH
Description. This command provides general signal injection functionality. Two additional arguments are always required:
1.
2.
Symbol
Kernel Block(s)
7080
EnableUndoDelayDataWrite
Description. [Unknown]
Sample Output.
...
Symbol
Kernel Block(s)
7090
DihSetTimeBetweenGcp
DBDIH
Description. [Unknown]
Sample Output.
...
Symbol
Kernel Block(s)
7098
---
DBDIH
Description. [Unknown]
Sample Output.
Node 2: Invalid no of arguments to 7098 - startLcpRoundLoopLab - expected
2 (tableId, fragmentId)
Symbol
Kernel Block(s)
7099
DihStartLcpImmediately
DBDIH
Sample Output. In this example, node 2 is the master node and controls LCP/GCP synchronization for the cluster. regardless of the
node_id specified, only the master node responds.
Node 2: Local checkpoint 7 started. Keep GCI = 1003 oldest restorable GCI = 947
Node 2: Local checkpoint 7 completed
Additional Information. You may need to enable a higher logging level to have the checkpoint's completion reported:
ndb_mgmgt; ALL CLUSTERLOG CHECKPOINT=8
Symbol
Kernel Block(s)
7901
---
DBDIH, DBLQH
Symbol
Kernel Block(s)
8004
---
SUMA
2:
2:
2:
2:
2:
2:
2:
Suma:
Suma:
Suma:
Suma:
Suma:
Suma:
Suma:
Additional Information. When subscriberPool ... free becomes and stays very low relative to subscriberPool ...
size, it is often a good idea to increase the value of the MaxNoOfTables configuration parameter (subscriberPool = 2 *
MaxNoOfTables). However, there could also be a problem with API nodes not releasing resources correctly when they are shut
down. DUMP 8004 provides a way to monitor these values.
Symbol
Kernel Block(s)
8005
---
SUMA
Description. [Unknown]
Sample Output.
Node 2: Bucket 0 10-0 switch gci: 0 max_acked_gci: 2961 max_gci: 0 tail: -256 head: -256
Node 2: Bucket 1 00-0 switch gci: 0 max_acked_gci: 2961 max_gci: 0 tail: -256 head: -256
440
Symbol
Kernel Block(s)
8011
---
SUMA
13:17:31
13:17:31
13:17:31
13:17:31
13:17:31
13:17:31
13:17:31
13:17:31
13:17:31
13:17:31
13:17:31
13:17:31
13:17:31
13:17:31
13:17:31
13:17:31
[MgmSrvr]
[MgmSrvr]
[MgmSrvr]
[MgmSrvr]
[MgmSrvr]
[MgmSrvr]
[MgmSrvr]
[MgmSrvr]
[MgmSrvr]
[MgmSrvr]
[MgmSrvr]
[MgmSrvr]
[MgmSrvr]
[MgmSrvr]
[MgmSrvr]
[MgmSrvr]
INFO
INFO
INFO
INFO
INFO
INFO
INFO
INFO
INFO
INFO
INFO
INFO
INFO
INFO
INFO
INFO
-----------------
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
Node
1:
1:
1:
1:
1:
1:
1:
1:
2:
2:
2:
2:
2:
2:
2:
2:
Symbol
Kernel Block(s)
9002
DumpTsman
TSMAN
Description. [Unknown]
Sample Output.
...
Symbol
Kernel Block(s)
9800
DumpTsman
TSMAN
441
Symbol
Kernel Block(s)
9801
---
TSMAN
Symbol
Kernel Block(s)
9802
---
TSMAN
Symbol
Kernel Block(s)
9803
---
TSMAN
442
Program: ./libexec/ndbd
Pid: 30712
Trace: /usr/local/mysql-5.1/cluster/ndb_2_trace.log.1
Version: Version 5.1.16 (beta)
Symbol
Kernel Block(s)
10000
DumpLgman
---
Description. [Unknown]
Sample Output.
...
Symbol
Kernel Block(s)
11000
DumpPgman
---
Description. [Unknown]
Sample Output.
...
Symbol
Kernel Block(s)
12001
TuxLogToFile
DBTUX
Description. [Unknown]
Sample Output.
...
Symbol
Kernel Block(s)
12002
TuxSetLogFlags
DBTUX
443
Description. [Unknown]
Sample Output.
...
Symbol
Kernel Block(s)
12009
TuxMetaDataJunk
DBTUX
Primary key lookup operations. These are performed through the exchange of TCKEY messages.
2.
Unique key lookup operations. These are performed through the exchange of TCINDX messages.
3. Table or index scan operations. These are performed through the exchange of SCANTAB messages.
Data request messages are often accompanied by KEYINFO messages, ATTRINFO messages, or both sorts of messages.
Commits and rollbacks, which are represented by TC_COMMIT and TCROLLBACK request messages, respectively.
444
2.
Transaction record requests that is, transaction record acquisition and release. These requests are handled through the use of,
respectively, TCSEIZE and TCRELEASE request messages.
Response types. A response indicates either the success or the failure of the request to which it is sent in reply:
Response indicating success. This type of response is represented as a CONF (confirmation) message, and is often accompanied by
data, which is packaged as one or more TRANSID_AI messages.
Response indicating failure. This type of response is represented as a REF (refusal) message.
These message types and their relationship to one another are discussed in more detail in Section 6.3.2, Message Naming Conventions
and Structure.
Request (REQ)
Response/Success (CONF)
Response/Failure (REF)
TCKEYCONF
TCKEYREF
TCINDXCONF
TCINDXREF
SCANTABREQ
SCANTABCONF
SCANTABREF
Result Retrieval
(SCAN_NEXT)
SCAN_NEXTREQ
SCANTABCONF
SCANTABREF
TCSEIZEREQ
TCSEIZECONF
TCSEIZEREF
TCRELEASEREQ
TCRELEASECONF
TCRELEASEREF
CONF and REF are shorthand for confirmed and refused, respectively.
Three additional types of messages are used in some instances of inter-node communication. These message types are:
1.
A KEYINFO message contains information about the key used in a TCKEYREQ or TCINDXREQ message. It is employed when the
key data does not fit within the request message. KEYINFO messages are also sent for index scan operations in which bounds are
employed.
2.
An ATTRINFO message contains nonkey attribute values which does not fit within a TCKEYREQ, TCINDXREQ, or SCANTABREQ
message. It is used for:
3.
A TRANSID_AI message contains data returned from a read operation in other words, it is a result set (or part of one).
445
Rollback of a transaction
Primary key lookup. An operation using a primary key lookup is performed as shown in the following diagram:
Note
446
* and + are used here with the meanings zero or more and one or more, respectively.
This process is explained is greater detail here:
1.
The API node sends a TCKEYREQ message to the data node. In the event that the necessary information about the key to be used is
too large to be contained in the TCKEYREQ, the message may be accompanied by any number of KEYINFO messages carrying the
remaining key information. If additional attributes are used for the operation and exceed the space available in the TCKEYREQ, or
if data is to be sent to the data node as part of a write operation, then these are sent with the TCKEYREQ as any number of ATTRINFO messages.
2.
If the operation was successful, the data node sends a TCKEYCONF message to the API node. If the request was for a read operation, then TCKEYCONF is accompanied by a TRANSID_AI message, which contains actual result data. If there is more data
than can be contained in a single TRANSID_AI can carry, more than one of these messages may be sent.
If the operation failed, then the data node sends a TCKEYREF message back to the API node, and no more signalling takes
place until the API node makes a new request.
Unique key lookup. This is performed in a manner similar to that performed in a primary key lookup:
1.
A request is made by the API node using a TCINDXREQ message which may be accompanied by zero or more KEYINFO messages, zero or more ATTRINFO messages, or both.
2.
If the operation was a success, the message is TCINDXCONF. For a successful read operation, this message may be accompanied by one or more TRANSID_AI messages carrying the result data.
447
Table scans and index scans. These are similar in many respects to primary key and unique key lookups, as shown here:
448
1.
A request is made by the API node using a SCAN_TABREQ message, along with zero or more ATTRINFO messages. KEYINFO
messages are also used with index scans in the event that bounds are used.
2.
If the operation was a success, the message is SCAN_TABCONF. For a successful read operation, this message may be accompanied by one or more TRANSID_AI messages carrying the result data. However unlike the case with lookups based on a
primary or unique key it is often necessary to fetch multiple results from the data node. Requests following the first are signalled by the API node using a SCAN_NEXTREQ, which tells the data node to send the next set of results (if there are more results). This is shown here:
449
Committing and rolling back transactions. The process of performing an explicit commit follows the same general pattern as shown
previously. The API node sends a TC_COMMITREQ message to the data node, which responds with either a TC_COMMITCONF (on
success) or a TC_COMMITREF (if the commit failed). This is shown in the following diagram:
450
Note
Some operations perform a COMMIT automatically, so this is not required for every transaction.
Rolling back a transaction also follows this pattern. In this case, however, the API node sends a TCROLLBACKTREQ message to the
data node. Either a TCROLLACKCONF or a TCROLLBACKREF is sent in response, as shown here:
451
Handling of transaction records. Acquiring a transaction record is accomplished when an API node transmits a TCSEIZEREQ message to a data node and receives a TCSEIZECONF or TCSEIZEREF in return, depending on whether or not the request was successful.
This is depicted here:
452
The release of a transaction record is also handled using the request-response pattern. In this case, the API node's request contains a
TCRELEASEREQ message, and the data node's response uses either a TCRELEASECONF (indicating that the record was released) or a
TCRELEASEREF (indicating that the attempt at release did not succeed). This series of events is illustrated in the next diagram:
453
Backup.cpp. Defines methods for node signal handing; also provides output methods for backup status messages to user.
BackupFormat.hpp. Defines the formats used for backup data, .CTL, and log files.
454
Backup.txt. Contains a backup signal diagram (text format). Somewhat dated (from 2003), but still potenitally useful to understanding the sequence of events that is followed during backups.
FsBuffer.hpp. Defines the FsBuffer class, which implements the circular data buffer that is used (together with the NDB file
system) for reading and writing backup data and logs.
read.cpp. Contains some utility functions for reading log and checkpoint files to STDOUT.
Cmvmi.cpp. Implements communication and reporting methods for the Cmvmi class.
Dbacc.hpp. Defines the Dbacc class, along with structures for operation, scan, table, and other records.
DbaccInit.cpp. Dbacc class constructor and destructor; methods for initialising data and records.
The ACC block handles the database index structures, which are stored in 8K pages. Database locks are also handled in the ACC block.
When a new tuple is inserted, the TUP block stores the tuple in a suitable space and returns an index (a reference to the address of the
tuple in memory). ACC stores both the primary key and this tuple index of the tuple in a hash table.
Like the TUP block, the ACC block implements part of the checkpoint protocol. It also performs undo logging. It is implemented by the
Dbacc class, which is defined in storage/ndb/src/kernel/blocks/dbacc/DbaccMain.hpp.
See also Section 6.4.8, The DBTUP Block.
CreateIndex.txt. Contains notes about processes for creating, altering, and dropping indexes and triggers.
Dbdict.cpp. Implements structure for event metadata records (for NDB$EVENTS_0), as well as methods for system start and restart, table and schema file handling, and packing table data into pages. Functionality for determining node status and handling node
failures is also found here. In addition, this file implements data and other initialisation routines for Dbdict.
DictLock.txt. Implementation notes: Describes locking of the master node's DICT against schema operations.
455
Slave_AddTable.sfl. A signal log trace of a table creation operation for DBDICT on a nonmaster node.
CreateTable.new.txt. Notes outlining the table creation process (updated version of CreateTable.txt).
Dbdict.hpp. Defines the Dbdict class; also creates the NDB$EVENTS_0 table. Also defines a number of structures such as table and index records, as well as for table records.
Dbdict.txt. Implementation notes for creating and dropping events and NdbEventOperation objects (see Section 2.3.11,
The NdbEventOperation Class).
Master_AddTable.sfl. A signal log trace of a table creation operation for DBDICT on the master node.
Dbdih.hpp. This file contains the definition of the Dbdih class, as well as the FileRecordPtr type, which is used to keep
storage information about a fragment and its replicas. If a fragment has more than one backup replica, then a list of the additional
ones is attached to this record. This record also stores the status of the fragment, and is 64-byte aligned.
DbdihInit.cpp. Initializes Dbdih data and records; also contains the class destructor.
LCP.txt. Contains developer noted about the exchange of messages between DIH and LQH that takes place during a local checkpoint.
printSysfile.cpp. This file contains the source code for ndb_print_sys_file. For information about using this utility,
see ndb_print_sys_file.
Sysfile.hpp. Contains the definition of the Sysfile structure; in other words, the format of an NDB system file. See Section 6.1, MySQL Cluster File Systems, for more information about NDB system files.
This block often makes use of BACKUP blocks on the data nodes to accomplish distributed tasks, such as global checkpoints and system
restarts.
This block is implemented as the Dbdih class, whose definition may be found in the file storage/
ndb/src/kernel/blocks/dbdih/Dbdih.hpp.
456
Dblqh.hpp. Contains the Dblqh class definition. The code itself includes the following modules:
Start phase 2. Initiate all records within the block; connect LQH with ACC and TUP
Start phase 4. Connect each LQH with every other LQH in the database system. For an initial start, create the fragment log
files. For a system restart or node restart, open the fragment log files and find the end of the log files.
Fragment addition and deletion module. Used by the data dictionary to create new fragments and delete old fragments.
Execution module. This module handles the reception of LQHKEYREQ messages and all processing of operations on behalf of
this request. This also involves reception of various types of ATTRINFO and KEYINFO messages, as well as communications
with ACC and TUP.
Log module. The log module handles the reading and writing of the log. It is also responsible for handling system restarts, and
controls system restart in TUP and ACC as well.
Tramsaction module. This module handles the commit and completion phases.
Scan module. This module contains the code that handles a scan of a particular fragment. It operates under the control of the
transaction coordinator and orders ACC to perform a scan of all tuples in the fragment. TUP performs the necessary search conditions to insure that only valid tuples are returned to the application.
Node recovery module. This is used when a node has failed, copying the effected fragment to a new fragment replica. It also
shuts down all connections to the failed node.
LCP module. This module handles execution and control of local checkpoints in TUP and ACC. It also interacts with DIH to
determine which global checkpoints are recoverable.
Global checkpoint module. Assist DIH in discovering when GCPs are recoverable. It handles the GCP_SAVEREQ message requesting LQH to save a given GCP to disk, and to provide a notification of when this has been done.
Signal reception
Normal operation
File change
Initial start
Error
DblqhInit.cpp. Initialises Dblqh records and data. Also includes the Dblqh class destructor, used for deallocating these.
This directory also has the files listed here in a redoLogReader subdirectory containing the sources for the
ndb_redo_log_reader utility (see ndbd_redo_log_reader):
records.cpp
records.hpp
457
redoLogFileReader.cpp
This block also handles redo logging, and helps oversee the DBACC, DBTUP, LGMAN, TSMAN, PGMAN, and BACKUP blocks. It is implemented as the class Dblqh, defined in the file storage/ndb/src/kernel/blocks/dblqh/Dblqh.hpp.
Dbtc.hpp. Defines the Dbtc class and associated constructs, including the following:
Trigger and index data (TcDefinedTriggerData). A record forming a list of active triggers for each table. These records
are managed by a trigger pool, in which a trigger record is seized whenever a trigger is activated, and released when the trigger
is deactivated.
Fired trigger data (TcFiredTriggerData). A record forming a list of fired triggers for a given transaction.
Index data (TcIndexData). This record forms lists of active indexes for each table. Such records are managed by an index
pool, in which each index record is seized whenever an index is created, and released when the index is dropped.
API connection record (ApiConnectRecord). An API connect record contains the connection record to which the application connects. The application can send one operation at a time. It can send a new operation immediately after sending the previous operation. This means that several operations can be active in a single transaction within the transaction coordinator, which
is achieved by using the API connect record. Each active operation is handled by the TC connect record; as soon as the TC connect record has sent the request to the local query handler, it is ready to receive new operations. The LQH connect record takes
care of waiting for an operation to complete; when an operation has completed on the LQH connect record, a new operation can
be started on the current LQH connect record. ApiConnectRecord is always 256-byte aligned.
Transaction coordinator connection record (TcConnectRecord). A TcConnectRecord) keeps all information required for carrying out a transaction; the transaction controller establishes connections to the different blocks needed to carry out
the transaction. There can be multiple records for each active transaction. The TC connection record cooperates with the API
connection record for communication with the API node, and with the LQH connection record for communication with any local
query handlers involved in the transaction. TcConnectRecord) is permanently connected to a record in DBDICT and another
in DIH, and contains a list of active LQH connection records and a list of started (but not currently active) LQH connection records. It also contains a list of all operations that are being executed with the current TC connection record. TcConnectRecord is always 128-byte aligned.
Cache record (CacheRecord). This record is used between reception of a TCKEYREQ and sending of LQHKEYREQ (see Section 6.3.3, Operations and Signals) This is a separate record, so as to improve the cache hit rate and as well as to minimise
memory storage requirements.
Host record (HostRecord). This record contains the alive status of each node in the system, and is 128-byte aligned.
Table record (TableRecord). This record contains the current schema versions of all tables in the system.
Scan record (ScanRecord). Each scan allocates a ScanRecord to store information about the current scan.
Data buffer (DatabufRecord). This is a buffer used for general data storage.
Attribute information record (AttrbufRecord). This record can contain one (1) ATTRINFO signal, which contains a set
of 32 attribute information words.
Global checkpoint information record (GcpRecord). This record is used to store the globalcheckpoint number, as well as a
counter, during the completion phase of the transaction. A GcpRecord is 32-byte aligned.
TC failure record (TC_FAIL_RECORD). This is used when handling takeover of TC duties from a failed transaction coordinator.
DbtcInit.cpp. Handles allocation and deallocation of Dbtc indexes and data (includes class desctructor).
458
Note
Any data node may act as the transaction coordinator.
The DBTC block is implemented as the Dbtc class.
The transaction coordinator is the kernel interface to which applications send their requests. It establishes connections to different
blocks in the system to carry out the transaction and decides which node will handle each transaction, sending a confirmation signal on
the result to the application so that the application can verify that the result received from the TUP block is correct.
This block also handles unique indexes, which must be co-ordinated across all data nodes simultaneously.
AttributeOffset.hpp. Defines the AttributeOffset class, which models the structure of an attribute, allowing for 4096
attributes, all of which are nullable.
DbtupIndex.cpp. Implements methods for reading and writing tuples using ordered indexes.
tuppage.hpp. Defines structures for fixed and variable size data pages for tuples.
DbtupExecQuery.cpp. Handles execution of queries for tuples and reading from them.
DbtupFixAlloc.cpp. Allocates and frees fixed-size tuples from the set of pages attatched to a fragment. The fixed size is set
per fragment; there can be only one such value per fragment.
DbtupPageMap.cpp. Routines used by Dbtup to map logical page IDs to physical page IDs. The mapping needs the fragment
ID and the logical page ID to provide the physical ID. This part of Dbtup is the exclusive user of a certain set of variables on the
fragment record; it is also the exclusive user of the struct for page ranges (the PageRange struct defined in Dbtup.hpp).
DbtupTabDesMan.cpp. This file contains the routines making up the table descriptor memory manager. Each table has a
descriptor, which is a contiguous array of data words, and which is allocated from a global array using a buddy algorithm, with
free lists existing for each 2N words.
Notes.txt. Contains some developers' implementation notes on tuples, tuple operations, and tuple versioning.
Undo_buffer.hpp. Defines the Undo_buffer class, used for storage of operations that may need to be rolled back.
DbtupPagMan.cpp. This file implements the page memory manager's buddy algorithm. PagMan is invoked when fragments
459
lack sufficient internal page space to accomodate all the data they are requested to store. It is also invoked when fragments deallocate page space back to the free area.
DbtupTrigger.cpp. The routines contained in this file perform handling of NDB internal triggers.
Dbtup.hpp. Contains the Dbtup class definition. Also defines a number of essential structures such as tuple scans, disk allocation units, fragment records, and so on.
DbtupVarAlloc.cpp.
DbtuxCmp.cpp. Implements routines to search by key vs node prefix or entry. The comparison starts at a given attribute position,
which is updated by the number of equal initial attributes found. The entry data may be partial, in which case CmpUnknown may be
returned. The attributes are normalized and have a variable size, given in words.
DbtuxNode.cpp. Implements routines for node creation, allocation, and deletion operations. Also assigns lists of scans to nodes.
Times.txt. Contains some (old) performance figures from tests runs on operations using ordered indexes. Of historical interest
only.
DbtuxMeta.cpp. Routines for creating, setting, and dropping indexes. Also provides means of aborting these operations in the
event of failure.
tuxstatus.html. 2004-01-30 status report on ordered index implementation. Of historical interest only.
460
Among the duties performed by this block is the maintenance of sequences for backup IDs and other distributed identifiers.
lgman.cpp. Implements Lgman for adding, dropping, and working with log files and file groups.
lgman.hpp. Contains the definition for the Lgman class, used to handle undo log files. Handles allocation of log buffer space.
Ndbcntr.hpp. Defines the Ndbcntr class used to implement cluster management functions.
NdbcntrMain.cpp. Implements methods used for starts, restarts, and reading of configuration data.
NdbcntrSysTable.cpp. NDBCNTR creates and initializes system tables on initial system start. The tables are defined in static
structs in this file.
AsyncFile.hpp. Defines the AsyncFile class, which represents an asynchronous file. All actions are executed concurrently
with the other activities carried out by the process. Because all actions are performed in a separate thread, the result of an action is
sent back through a memory channel. For the asyncronous notification of a finished request, each callincludes a request as a parameter. This class is used for writing or reading data to and from disk concurrently with other activities.
AsyncFile.cpp. Defines the actions possible for an asynchronous file, and implements them.
Filename.hpp. Defines the Filename class. Takes a 128-bit value (as a array of four longs) and makes a file name out of it.
This file name encodes information about the file, such as whether it is a file or a directory, and if the former, the type of file. Possible types include data file, fragment log, fragment list, table list, schema log, and system file, among others.
MemoryChannelTest/MemoryChannelTest.cpp. Basic program for testing reads from and writes to a memory channel
(that is, reading from and writing to a circular buffer).
OpenFiles.hpp. Implements an OpenFiles class, which implements some convenience methods for determining whether or
not a given file is already open.
VoidFs.cpp. Used for diskless operation. Generates a dummy acjknowledgement to write operations.
CircularIndex.hpp. The CircularIndex class, defined in this file, serves as the building block for implementing circular
buffers. It increments as a normal index until it reaches maximum size, then resets to zero.
CircularIndex.cpp. Contains only a single #define, not actually used at this time.
pointer-based channel for communication between two threads. It does not copy any data into or out of the channel, so the item that
is put in can not be used untill the other thread has given it back. There is no support for detecting the return of an item.
Ndbfs.hpp. Because an NDB signal request can result in multiple requests to AsyncFile, one class (defined in this file) is responsible for keeping track of all outstanding requests, and when all are finished, reporting the outcome back to the sending block.
Ndbfs.cpp. Implements initialization and signal-handling methods for the Ndbfs class.
Pool.hpp. Creates and manages a pool of objects for use by Ndbfs and other classes in this block.
diskpage.cpp. Initializes sero page headers; includes some output reoutines for reporting and debugging.
pgman.hpp. Defines the Pgman class implementing a number of page and buffer services, including:
Page replacement
Page lists
Page cleanup
pgman.cpp. Implements Pgman methods for initialization and various page management tasks.
Qmgr.hpp. Defines the Qmgr class and associated structures, including those used in detection of node failure and cluster partitioning.
QmgrInit.cpp. Implements data and record initilization methods for Qmgr, as well as its destructor.
QmgrMain.cpp. Contains routines for monitoring of heartbeats, detection and handling of split-brain problems, and management of some startup phases.
timer.hpp. Defines the Timer class, used by NDB to keep strict timekeeping independent of the system clock.
This block also assists in the early phases of data node startup.
The QMGR block is implemented by the Qmgr class, whose definition is found in the file storage/
ndb/src/kernel/blocks/qmgr/Qmgr.hpp.
Suma.hpp. Defines the Suma class and interfaces for managing subscriptions and performing necessary communications with
other SUMA (and other) blocks.
tsman.hpp. Defines the Tsman class, as well as structures representing data files and tablespaces.
Trix.hpp. Defines the Trix class, along with structures representing subscription data and records (for communicating with
SUMA) and node data and ists (needed when communicating with remote TRIX blocks).
Trix.cpp. Implements Trix class methods, including those necessary for taking appropriate action in the event of node failures.
NDBFS
2.
DBTUP
463
3.
DBACC
4.
DBTC
5.
DBLQH
6.
DBTUX
7.
DBDICT
8.
DBDIH
9.
NDBCNTR
10. QMGR
11. TRIX
12. BACKUP
13. DBUTIL
14. SUMA
15. TSMAN
16. LGMAN
17. PGMAN
18. RESTORE
NDBFS is allowed to run before any of the remaining blocks are contacted, in order to make sure that it can start the CMVMI block's
threads.
Note
Connections between the kernel blocks and the NDB file system are also set up during Phase 0. This is necessary to enable
the blocks to communicate easily which parts of a table structure are to be written to disk.
NDB performs memory allocations in two different ways. The first of these is by using the allocRecord() method (defined in
storage/ndb/src/kernel/vm/SimulatedBlock.hpp). This is the traditional method whereby records are accessed using
the ptrCheckGuard macros (defined in storage/ndb/src/kernel/vm/pc.hpp). The other method is to allocate memory
using the setSize() method defined with the help of the template found in storage/ndb/src/kernel/vm/CArray.hpp.
These methods sometimes also initialize the memory, ensuring that both memory allocation and initialization are done with watchdog
protection.
Many blocks also perform block-specific initialization, which often entails building linked lists or doubly-linked lists (and in some cases
hash tables).
Many of the sizes used in allocation are calculated in the Configuration::calcSizeAlt() method, found in storage/
ndb/src/kernel/vm/Configuration.cpp.
Some preparations for more intelligent pooling of memory resources have been made. DataMemory and disk records already belong
to this global memory pool.
Phase 0, as can be seen by inspecting the first value for each element in the ALL_BLOCKS array (defined in src/kernel/blocks/ndbcntr/NdbcntrMain.cpp). In addition, when the STTOR signal is sent to a block, the return signal STTORRY
always contains a list of the start phases in which the block has an interest. Only in those start phases does the block actually receive a
STTOR signal.
STTOR signals are sent out in the order in which the kernel blocks are listed in the ALL_BLOCKS array. While NDBCNTR goes through
start phases 0 to 255, most of these are empty.
Both activities in Phase 0 have to do with initialization of the NDB file system. First, if necessary, NDBFS creates the file system directory for the data node. In the case of an initial start, NDBCNTR clears any existing files from the directory of the data node to ensure that
the DBDIH block does not subsequently discover any system files (if DBDIH were to find any system files, it would not interpret the
start correctly as an initial start). (See also Section 6.4.5, The DBDIH Block.)
Each time that NDBCNTR completes the sending of one start phase to all kernel blocks, it sends a NODE_STATE_REP signal to all
blocks, which effectively updates the NodeState in all blocks.
Each time that NDBCNTR completes a nonempty start phase, it reports this to the management server; in most cases this is recorded in
the cluster log.
Finally, after completing all start phases, NDBCNTR updates the node state in all blocks via a NODE_STATE_REP signal; it also sends
an event report advising that all start phases are complete. In addition, all other cluster data nodes are notified that this node has completed all its start phases to ensure all nodes are aware of one another's state. Each data node sends a NODE_START_REP to all blocks;
however, this is significant only for DBDIH, so that it knows when it can unlock the lock for schema changes on DBDICT.
Note
In the following table, and throughout this text, we sometimes refer to STTOR start phases simply as start phases or
Phase N (where N is some number). NDB_STTOR start phases are always qualified as such, and so referred to as
NDB_STTOR start phases or NDB_STTOR phases.
Kernel Block
NDBFS
DBTC
DBDIH
DBLQH
1, 4
DBACC
DBTUP
DBDICT
1, 3
NDBCNTR
0, 1, 2, 3, 4, 5, 6, 8, 9
CMVMI
1 (prior to QMGR), 3, 8
QMGR
1, 7
TRIX
BACKUP
1, 3, 7
DBUTIL
1, 6
SUMA
DBTUX
1,3,7
TSMAN
1, 3 (both ignored)
LGMAN
1, 2, 3, 4, 5, 6 (all ignored)
PGMAN
RESTORE
Note
This table was current at the time this text was written, but is likely to change over time. The latest information can be
found in the source code.
465
466
As a final step, QMGR also starts the timer handling for which it is responsible. This means that it generates a signal to blocks that have
requested it. This signal is sent 100 times per second even if any one instance of the signal is delayed..
The BACKUP kernel block also begins sending a signal periodically. This is to ensure that excessive amounts of data are not written to
disk, and that data writes are kept within the limits of what has been specified in the cluster configuration file during and after restarts.
467
The DBUTIL block initializes the transaction identity, and DBTUX creates a reference to the DBTUP block, while PGMAN initializes
pointers to the LGMAN and DBTUP blocks. The RESTORE kernel block creates references to the DBLQH and DBTUP blocks to enable
quick access to those blocks when needed.
DBLQH
2.
DBDICT
3.
DBTUP
4.
DBACC
5.
DBTC
6.
DBDIH
(in each case, the block actually sets a variable whose value reflects the type of start or restart). The SUMA block remains inactive during
this phase.
The PGMAN kernel block starts the generation of two repeated signals, the first handling cleanup. This signal is sent every 200 milliseconds. The other signal handles statistics, and is sent once per second.
Note
From this point, there are two parallel paths, one continuing restart and another reading and determining the state of the
redo log files.
The DBDICT block requests information about the cluster data nodes via the READ_NODESREQ signal. DBACC resets the system restart
flag if this is not a system restart; this is used only to verify that no requests are received from DBTUX during system restart. DBTC requests information about all nodes by means of the READ_NODESREQ signal.
DBDIH sets an internal master state and makes other preparations exclusive to initial starts. In the case of an initial start, the nonmaster
nodes perform some initial tasks, the master node doing once all nonmaster nodes have reported that their tasks are completed. (This
delay is actually unnecessary since there is no reason to wait while initializing the master node.)
For node restarts and initial node restarts no more work is done in this phase. For initial starts the work is done when all nodes have created the initial restart information and initialized the system file.
For system restarts this is where most of the work is performed, initiated by sending the NDB_STARTREQ signal from NDBCNTR to
DBDIH in the master. This signal is sent when all nodes in the system restart have reached this point in the restart. This we can mark as
our first synchronization point for system restarts, designated WAITPOINT_4_1.
For a description of the system restart version of Phase 4, see Section 6.5.21, System Restart Handling in Phase 4.
After completing execution of the NDB_STARTREQ signal, the master sends a CNTR_WAITREP signal with WAITPOINT_4_2 to all
nodes. This ends NDB_STTOR phase 3 as well as (STTOR) Phase 4.
For initial starts and system restarts this phase means executing a local checkpoint. This is handled by the master so that the other nodes
will return immediately from this phase. Node restarts and initial node restarts perform the copying of the records from the primary replica to the starting replicas in this phase. Local checkpoints are enabled before the copying process is begun.
Copying the data to a starting node is part of the node takeover protocol. As part of this protocol, the node status of the starting node is
updated; this is communicated using the global checkpoint protocol. Waiting for these events to take place ensures that the new node
status is communicated to all nodes and their system files.
After the node's status has been communicated, all nodes are signaled that we are about to start the takeover protocol for this node. Part
of this protocol consists of Steps 3 - 9 during the system restart phase as described below. This means that restoration of all the fragments, preparation for execution of the redo log, execution of the redo log, and finally reporting back to DBDIH when the execution of
the redo log is completed, are all part of this process.
After preparations are complete, copy phase for each fragment in the node must be performed. The process of copying a fragment involves the following steps:
1.
The DBLQH kernel block in the starting node is informed that the copy process is about to begin by sending it a PREPARE_COPY_FRAGREQ signal.
2.
When DBLQH acknowledges this request a CREATE_FRAGREQ signal is sent to all nodes notify them of the preparation being
made to copy data to this replica for this table fragment.
3.
After all nodes have acknowledged this, a COPY_FRAGREQ signal is sent to the node from which the data is to be copied to the
new node. This is always the primary replica of the fragment. The node indicated copies all the data over to the starting node in response to this message.
4.
After copying has been completed, and a COPY_FRAGCONF message is sent, all nodes are notified of the completion through an
UPDATE_TOREQ signal.
5.
After all nodes have updated to reflect the new state of the fragment, the DBLQH kernel block of the starting node is informed of
the fact that the copy has been completed, and that the replica is now up-to-date and any failures should now be treated as real failures.
6.
The new replica is transformed into a primary replica if this is the role it had when the table was created.
7.
After completing this change another round of CREATE_FRAGREQ messages is sent to all nodes informing them that the takeover
of the fragment is now committed.
8.
After this, process is repeated with the next fragment if another one exists.
9.
When there are no more fragments for takeover by the node, all nodes are informed of this by sending an UPDATE_TOREQ signal
sent to all of them.
10. Wait for the next complete local checkpoint to occur, running from start to finish.
11. The node states are updated, using a complete global checkpoint. As with the local checkpoint in the previous step, the global
checkpoint must be allowed to start and then to finish.
12. When the global checkpoint has completed, it will communicate the successful local checkpoint of this node restart by sending an
END_TOREQ signal to all nodes.
13. A START_COPYCONF is sent back to the starting node informing it that the node restart has been completed.
14. Receiving the START_COPYCONF signal ends NDB_STTOR phase 5. This provides another synchronization point for system restarts, designated as WAITPOINT_5_2.
Note
The copy process in this phase can in theory be performed in parallel by several nodes. However, all messages from the
master to all nodes are currently sent to single node at a time, but can be made completely parallel. This is likely to be
done in the not too distant future.
In an initial and an initial node restart, the SUMA block requests the subscriptions from the SUMA master node. NDBCNTR executes
NDB_STTOR phase 6. No other NDBCNTR activity takes place.
470
The master sets the latest GCI as the restart GCI, and then synchronizes its system file to all other nodes involved in the system restart.
2.
The next step is to synchronize the schema of all the nodes in the system restart. This is performed in 15 passes. The problem we
are trying to solve here occurs when a schema object has been created while the node was up but was dropped while the node was
down, and possibly a new object was even created with the same schema ID while that node was unavailable. In order to handle
this situation, it is necessary first to re-create all objects that are supposed to exist from the viewpoint of the starting node. After
this, any objects that were dropped by other nodes in the cluster while this node was dead are dropped; this also applies to any
tables that were dropped during the outage. Finally, any tables that have been created by other nodes while the starting node was
unavailable are re-created on the starting node. All these operations are local to the starting node. As part of this process, is it also
necessary to ensure that all tables that need to be re-created have been created locally and that the proper data structures have been
set up for them in all kernel blocks.
After performing the procedure described previously for the master node the new schema file is sent to all other participants in the
471
All fragments involved in the restart must have proper parameters as derived from DBDIH. This causes a number of
START_FRAGREQ signals to be sent from DBDIH to DBLQH. This also starts the restoration of the fragments, which are restored
one by one and one record at a time in the course of reading the restore data from disk and applying in parallel the restore data read
from disk into main memory. This restores only the main memory parts of the tables.
4.
Once all fragments have been restored, a START_RECREQ message is sent to all nodes in the starting cluster, and then all undo
logs for any Disk Data parts of the tables are applied.
5.
After applying the undo logs in LGMAN, it is necessary to perform some restore work in TSMAN that requires scanning the extent
headers of the tablespaces.
6.
Next, it is necessary to prepare for execution of the redo log, which log can be performed in up to four phases. For each fragment,
execution of redo logs from several different nodes may be required. This is handled by executing the redo logs in different phases
for a specific fragment, as decided in DBDIH when sending the START_FRAGREQ signal. An EXEC_FRAGREQ signal is sent for
each phase and fragment that requires execution in this phase. After these signals are sent, an EXEC_SRREQ signal is sent to all
nodes to tell them that they can start executing the redo log.
Note
Before starting execution of the first redo log, it is necessary to make sure that the setup which was started earlier (in Phase
4) by DBLQH has finished, or to wait until it does before continuing.
7.
Prior to executing the redo log, it is necessary to calculate where to start reading and where the end of the REDO log should have
been reached. The end of the REDO log should be found when the last GCI to restore has been reached.
8.
After completing the execution of the redo logs, all redo log pages that have been written beyond the last GCI to be restore are invalidated. Given the cyclic nature of the redo logs, this could carry the invalidation into new redo log files past the last one executed.
9.
After the completion of the previous step, DBLQH report this back to DBDIH using a START_RECCONF message.
10. When the master has received this message back from all starting nodes, it sends a NDB_STARTCONF signal back to NDBCNTR.
11. The NDB_STARTCONF message signals the end of STTOR phase 4 to NDBCNTR, which is the only block involved to any significant degree in this phase.
ACC. ACCelerator or ACCess manager. Handles hash indexes of primary keys, providing fast access to records. See Section 6.4.3,
The DBACC Block.
API node. In NDB terms, this is any application that accesses cluster data using the NDB API, including mysqld when functioning
as an API node. (MySQL servers acting in this capacity are also referred to as SQL nodes). Often abbreviated to API.
472
CMVMI. Stands for Cluster Manager Virtual Machine Interface. An NDB kernel handling nonsignal requests to the operating system, as well as configuration management, interaction with the cluster management server, and interaction between various kernel
blocks and the NDB virtual machine. See Section 6.4.2, The CMVMI Block, for more information.
CNTR. Stands for restart CoordiNaToR. See Section 6.4.12, The NDBCNTR Block, for more information.
DBTC. The transaction coordinator (also sometimes written simply as TC). See Section 6.4.7, The DBTC Block, for more information.
DICT. The NDB data DICTionary kernel block. Also DBDICT. See Section 6.4.4, The DBDICT Block.
DIH. DIstribution Handler. An NDB kernel block. See Section 6.4.5, The DBDIH Block.
LGMAN. The Log Group MANager NDB kernel block, used for MySQL Cluster Disk Data tables. See Section 6.4.11, The LGMAN Block.
LQH. Local Query Handler. NDB kernel block, discussed in Section 6.4.6, DBLQH Block.
MGM. ManaGeMent node (or management server). Implemented as the ndb_mgmd server daemon. Responsible for passing
cluster configuration information to data nodes and performing functions such as starting and stopping nodes. Accessed by the user
by means of the cluster management client (ndb_mgm). A discussion of management nodes can be found in ndb_mgmd.
QMGR. The cluster management block in the NDB kernel. It responsibilities include monitoring heartbeats from data and API
nodes. See Section 6.4.15, The QMGR Block, for more information.
RBR. Row-Based Replication. MySQL Cluster Replication is row-based replication. See MySQL Cluster Replication.
SUMA. The cluster SUbscription MAnager. See Section 6.4.17, The SUMA Block.
TC
TC. Transaction Coordinator. See Section 6.4.7, The DBTC Block.
TRIX. Stands for TRansactions and IndeXes, which are managed by the NDB kernel block having this name. See Section 6.4.19,
The TRIX Block.
TSMAN. Table space manager. Handles tablespaces for MySQL Cluster Disk Data. See Section 6.4.18, The TSMAN Block, for
more information.
TUP. TUPle. Unit of data storage. Also used (along with DBTUP) to refer to the NDB kernel's tuple management block, which is
discussed in Section 6.4.8, The DBTUP Block.
473
ndex
A
AbortOption (NdbOperation datatype), 134
AbortOption (NdbTransaction datatype), 167
ACC
and NDB Kernel, 10
defined, 2
Access Manager
defined, 2
ActiveHook (NdbBlob datatype), 85
addColumn() (method of Index), 67
addColumn() (method of Table), 198
addColumnName() (method of Index), 67
addColumnNames() (method of Index), 67
addEventColumn() (method of Event), 60
addEventColumns() (method of Event), 61
addTableEvent() (method of Event), 59
add_reg() (method of NdbInterepretedCode), 115
add_val() (method of NdbInterepretedCode), 127
aggregate() (method of Table), 204
allowsNull (ClusterJ), 354
and (ClusterJ), 365
Annotations (ClusterJ)
Column, 353
Columns, 354
Extension, 355
Extensions, 356
Index, 357
Indices, 358
Lob, 358
NotPersistent, 359
PartitionKey, 360
PersistenceCapable, 361
Persistent, 362
PrimaryKey, 364
API node
defined, 2
application-level partitioning, 215
applications
structure, 4
aRef() (method of NdbRecAttr), 149
ArrayType (Column datatype), 22
AutoGrowSpecification structure, 221
B
backup
defined, 1
begin (ClusterJ), 352
begin() (method of NdbScanFilter), 153
between (ClusterJ), 366
BinaryCondition (NdbScanFilter datatype), 152
BLOB handling
example, 268
example (using NdbRecord), 274
blobsFirstBlob() (method of NdbBlob), 89
blobsNextBlob() (method of NdbBlob), 90
BoundType (NdbIndexScanOperation datatype), 104
branch_col_and_mask_eq_mask() (method of NdbInterpretedCode), 124
branch_col_and_mask_eq_zero() (method of NdbInterpretedCode), 125
branch_col_and_mask_ne_mask() (method of NdbInterpretedCode), 125
branch_col_and_mask_ne_zero() (method of NdbInterpretedCode), 126
C
call_sub() (method of NdbInterepretedCode), 129
char_value() (method of NdbRecAttr), 146
checkpoint
defined, 1
Classes (ClusterJ)
ClusterJHelper, 334
NullValue, 359
PersistenceModifier, 362
Classification (NdbError datatype), 227
clone() (method of NdbRecAttr), 149
close (ClusterJ), 345, 350
close() (method of NdbScanOperation), 162
close() (method of NdbTransaction), 171
closeTransaction() (method of Ndb), 78
ClusterJ
defined, 313
ClusterJDatastoreException (ClusterJ), 328
ClusterJException (ClusterJ), 329
ClusterJFatalException (ClusterJ), 330
ClusterJFatalInternalException (ClusterJ), 331
ClusterJFatalUserException (ClusterJ), 332
ClusterJHelper (ClusterJ), 334
ClusterJPA
defined, 313
ClusterJUserException (ClusterJ), 337
cmp() (method of NdbScanFilter), 154
Column (ClusterJ), 353
column (ClusterJ), 360, 363, 364
Column class, 19
Column::ArrayType, 22
Column::ColumnType, 22
Column::equal(), 25
Column::getArrayType(), 29
Column::getCharset(), 27
Column::getColumnNo(), 25
Column::getDefaultValue(), 34
Column::getInlineSize(), 27
Column::getLength(), 26
Column::getName(), 24
Column::getNullable(), 24
Column::getPartitionKey(), 28
Column::getPartSize(), 27
Column::getPrecision(), 26
474
Index
Column::getPrimaryKey(), 24
Column::getStorageType(), 29
Column::getStripeSize(), 28
Column::getType(), 25
Column::setArrayType(), 33
Column::setCharset(), 32
Column::setDefaultValue(), 34
Column::setLength(), 31
Column::setName(), 29
Column::setNullable(), 29
Column::setPartitionKey(), 33
Column::setPartSize(), 32
Column::setPrecision(), 30
Column::setPrimaryKey(), 30
Column::setScale(), 31
Column::setStorageType(), 33
Column::setStripeSize(), 33
Column::setType(), 30
Column::StorageType, 22
Columns (ClusterJ), 354
columns (ClusterJ), 357, 360, 364
ColumnType (Column datatype), 22
Commit
defined, 4
commit (ClusterJ), 352
commitStatus() (method of NdbTransaction), 172
CommitStatusType (NdbTransaction datatype), 168
computeHash() (method of Ndb), 79
concurrency control, 11
connect() (method of Ndb_cluster_connection), 217
connecting to multiple clusters
example, 238, 266
Connector/J
known issues, 371
Constants (ClusterJ), 338
createDatafile() (method of Dictionary), 46
createEvent() (method of Dictionary), 46
createIndex() (method of Dictionary), 46
createLogfileGroup() (method of Dictionary), 46
createQuery (ClusterJ), 345
createQueryDefinition (ClusterJ), 368
createRecord() (method of Dictionary), 47
createTable() (method of Dictionary), 45
createTablespace() (method of Dictionary), 46
createUndofile() (method of Dictionary), 47
currentTransaction (ClusterJ), 346
D
data node
defined, 2
database (ClusterJ), 361
Datafile class, 34
Datafile::getFileNo(), 38
Datafile::getFree(), 37
Datafile::getNode(), 38
Datafile::getObjectId(), 39
Datafile::getObjectStatus(), 38
Datafile::getObjectVersion(), 38
Datafile::getPath(), 36
Datafile::getSize(), 37
Datafile::getTablespace(), 37
Datafile::getTablespaceId(), 37
Datafile::setNode(), 40
Datafile::setPath(), 39
Datafile::setSize(), 39
Datafile::setTablespace(), 39
defaultValue (ClusterJ), 354
DEFAULT_PROPERTY_CLUSTER_CONNECT_DELAY (ClusterJ),
339
DEFAULT_PROPERTY_CLUSTER_CONNECT_RETRIES
(ClusterJ), 339
DEFAULT_PROPERTY_CLUSTER_CONNECT_TIMEOUT_AFTER
(ClusterJ), 339
DEFAULT_PROPERTY_CLUSTER_CONNECT_TIMEOUT_BEFORE
(ClusterJ), 340
DEFAULT_PROPERTY_CLUSTER_CONNECT_VERBOSE
(ClusterJ), 340
DEFAULT_PROPERTY_CLUSTER_DATABASE (ClusterJ), 340
DEFAULT_PROPERTY_CLUSTER_MAX_TRANSACTIONS
(ClusterJ), 340
def_label() (method of NdbInterepretedCode), 116
def_sub() (method of NdbInterepretedCode), 128
deleteCurrentTuple() (method of NdbScanOperation), 164
deletePersistent (ClusterJ), 346
deletePersistentAll (ClusterJ), 346, 346
deleteTuple() (method of NdbIndexOperation), 102
deleteTuple() (method of NdbOperation), 142
deleteTuple() (method of NdbTransaction), 178
Dictionary class, 40
Dictionary::createDatafile(), 46
Dictionary::createEvent(), 46
Dictionary::createIndex(), 46
Dictionary::createLogfileGroup(), 46
Dictionary::createRecord(), 47
Dictionary::createTable(), 45
Dictionary::createTablespace(), 46
Dictionary::createUndofile(), 47
Dictionary::dropDatafile(), 49
Dictionary::dropEvent(), 48
Dictionary::dropIndex(), 48
Dictionary::dropLogfileGroup(), 49
Dictionary::dropTable(), 48
Dictionary::dropTablespace(), 49
Dictionary::dropUndofile(), 49
Dictionary::Element structure, 222
Dictionary::getDatafile(), 44
Dictionary::getEvent(), 44
Dictionary::getIndex(), 43
Dictionary::getLogfileGroup(), 44
Dictionary::getNdbError(), 45
Dictionary::getTable(), 43
Dictionary::getTablespace(), 44
Dictionary::getUndofile(), 45
Dictionary::invalidateTable(), 50
Dictionary::listIndexes(), 50
Dictionary::listObjects(), 50
Dictionary::releaseRecord(), 51
Dictionary::removeCachedIndex(), 52
Dictionary::removeCachedTable(), 52
double_value() (method of NdbRecAttr), 148
dropDatafile() (method of Dictionary), 49
dropEvent() (method of Dictionary), 48
dropEventOperation() (method of Ndb), 79
dropIndex() (method of Dictionary), 48
dropLogfileGroup() (method of Dictionary), 49
dropTable() (method of Dictionary), 48
dropTablespace() (method of Dictionary), 49
dropUndofile() (method of Dictionary), 49
475
Index
E
Element (Dictionary structure), 222
Elements (ClusterJ)
allowsNull, 354
column, 360, 363, 364
columns, 357, 360, 364
database, 361
defaultValue, 354
extensions, 363
key, 355
name, 354, 357, 364
nullValue, 363
primaryKey, 363
schema, 361
table, 361
unique, 357
value, 355, 356, 356, 358
vendorName, 356
end() (method of NdbScanFilter), 153
end_of_bound() (method of NdbIndexScanOperation), 107
eq() (method of NdbScanFilter), 155
equal (ClusterJ), 367
equal() (method of Column), 25
equal() (method of NdbOperation), 138
equal() (method of Table), 192
error classification (defined), 224
error classifications, 396
error code (defined), 224
Error code types, 376
Error codes, 376
error detail message (defined), 225
error handling
example, 242
overview, 9
error message (defined), 225
Error status, 224
error types
in applications, 242
errors
classifying, 396
Event class, 52
Event::addEventColumn(), 60
Event::addEventColumns(), 61
Event::addTableEvent(), 59
Event::EventDurability, 55
Event::EventReport, 56
Event::getDurability(), 57
Event::getEventColumn(), 58
Event::getName(), 56
Event::getNoOfEventColumns(), 58
Event::getObjectId(), 59
Event::getObjectStatus(), 58
Event::getObjectVersion(), 58
Event::getReport(), 57
Event::getTable(), 56
Event::getTableEvent(), 57
Event::getTableName(), 57
Event::mergeEvents(), 61
Event::setDurability(), 60
Event::setName(), 59
Event::setReport(), 60
Event::setTable(), 59
Event::TableEvent, 55
F
Fields (ClusterJ)
DEFAULT_PROPERTY_CLUSTER_CONNECT_DELAY, 339
DEFAULT_PROPERTY_CLUSTER_CONNECT_RETRIES, 339
DEFAULT_PROPERTY_CLUSTER_CONNECT_TIMEOUT_AFTER,
339
DEFAULT_PROPERTY_CLUSTER_CONNECT_TIMEOUT_BEFOR
E, 340
DEFAULT_PROPERTY_CLUSTER_CONNECT_VERBOSE, 340
DEFAULT_PROPERTY_CLUSTER_DATABASE, 340
DEFAULT_PROPERTY_CLUSTER_MAX_TRANSACTIONS,
340
PROPERTY_CLUSTER_CONNECTION_SERVICE, 340
PROPERTY_CLUSTER_CONNECTSTRING, 341
PROPERTY_CLUSTER_CONNECT_DELAY, 340
PROPERTY_CLUSTER_CONNECT_RETRIES, 340
PROPERTY_CLUSTER_CONNECT_TIMEOUT_AFTER, 340
PROPERTY_CLUSTER_CONNECT_TIMEOUT_BEFORE, 340
PROPERTY_CLUSTER_CONNECT_VERBOSE, 340
PROPERTY_CLUSTER_DATABASE, 341
PROPERTY_CLUSTER_MAX_TRANSACTIONS, 341
PROPERTY_DEFER_CHANGES, 341
PROPERTY_JDBC_DRIVER_NAME, 341
PROPERTY_JDBC_PASSWORD, 341
PROPERTY_JDBC_URL, 341
PROPERTY_JDBC_USERNAME, 341
SESSION_FACTORY_SERVICE_CLASS_NAME, 341
SESSION_FACTORY_SERVICE_FILE_NAME, 341
finalise() (method of NdbInterepretedCode), 129
find (ClusterJ), 346
float_value() (method of NdbRecAttr), 148
flush (ClusterJ), 347
fragment
defined, 2
FragmentType (Object datatype), 182
G
GCP (Global Checkpoint)
defined, 2
ge() (method of NdbScanFilter), 157
476
Index
Index
Index::addColumnName(), 67
Index::addColumnNames(), 67
Index::getColumn(), 65
Index::getLogging(), 65
Index::getName(), 64
Index::getNoOfColumns(), 64
Index::getObjectId(), 66
Index::getObjectStatus(), 66
Index::getObjectVersion(), 66
Index::getTable(), 64
Index::getType(), 65
Index::setName(), 66
Index::setTable(), 67
Index::setType(), 68
Index::Type, 63
Indices (ClusterJ), 358
init() (method of Ndb), 75
initial node restart
defined, 2
insertTuple() (method of NdbOperation), 141
insertTuple() (method of NdbTransaction), 175
int32_value() (method of NdbRecAttr), 146
int64_value() (method of NdbRecAttr), 145
int8_value() (method of NdbRecAttr), 147
integer comparison methods (of NdbScanFilter class), 155
Interfaces (ClusterJ)
Constants, 338
Predicate, 365
PredicateOperand, 366
Query, 342
QueryBuilder, 368
QueryDefinition, 369
QueryDomainType, 370
Results, 343
Session, 344
SessionFactory, 350
SessionFactoryService, 351
Transaction, 352
interpret_exit_nok() (method of NdbInterepretedCode), 127
interpret_exit_ok() (method of NdbInterepretedCode), 126
interpret_last_row() (method of NdbInterepretedCode), 127
invalidateTable() (method of Dictionary), 50
isActive (ClusterJ), 353
isClosed (ClusterJ), 347
isConsistent() (method of NdbEventOperation), 99
isfalse() (method of NdbScanFilter), 153
isnotnull() (method of NdbScanFilter), 158
isNULL() (method of NdbRecAttr), 145
isnull() (method of NdbScanFilter), 157
istrue() (method of NdbScanFilter), 153
iteration
Ndb objects, 218
iterator (ClusterJ), 344
H
hasDefaultValues() (method of Table), 204
Java, 313
JDBC
known issues, 371
in (ClusterJ), 367
Index (ClusterJ), 357
Index class, 61
Index::addColumn(), 67
478
Index
L
LCP (Local Checkpoint)
defined, 2
le() (method of NdbScanFilter), 156
lessEqual (ClusterJ), 367
lessThan (ClusterJ), 368
List class, 72
listIndexes() (method of Dictionary), 50
listObjects() (method of Dictionary), 50
load_const_null() (method of NdbInterepretedCode), 112
load_const_u16() (method of NdbInterepretedCode), 112
load_const_u32() (method of NdbInterepretedCode), 113
load_const_u64() (method of NdbInterepretedCode), 113
Lob (ClusterJ), 358
lock handling
and scan operations, 8
lockCurrentTuple() (method of NdbScanOperation), 162
LockMode (NdbOperation datatype), 134
LogfileGroup class, 68
LogfileGroup::getAutoGrowSpecification(), 70
LogfileGroup::getName(), 70
LogfileGroup::getObjectId(), 71
LogfileGroup::getObjectStatus(), 71
LogfileGroup::getObjectVersion(), 71
LogfileGroup::getUndoBufferSize(), 70
LogfileGroup::getUndoFreeWords(), 71
LogfileGroup::setAutoGrowSpecification(), 72
LogfileGroup::setName(), 71
LogfileGroup::setUndoBufferSize(), 72
lt() (method of NdbScanFilter), 156
M
makePersistent (ClusterJ), 347
makePersistentAll (ClusterJ), 348
management (MGM) node
defined, 2
markModified (ClusterJ), 348
medium_value() (method of NdbRecAttr), 146
mergeEvents() (method of Event), 61
mergeEvents() (method of NdbEventOperation), 100
Methods (ClusterJ)
and, 365
begin, 352
between, 366
close, 345, 350
commit, 352
createQuery, 345
createQueryDefinition, 368
currentTransaction, 346
deletePersistent, 346
deletePersistentAll, 346, 346
equal, 367
execute, 342, 342, 343
explain, 343
find, 346
flush, 347
get, 370
getQueryBuilder, 347
getResultList, 343
getRollbackOnly, 352
getServiceInstance, 335, 335, 335
getServiceInstances, 336
getSession, 350, 351
N
name (ClusterJ), 354, 357, 364
NDB
defined, 2
record structure, 10
NDB API
defined, 3
NDB API classes
overview, 3
Ndb class, 73
Ndb::closeTransaction(), 78
Ndb::computeHash(), 79
Ndb::dropEventOperation(), 79
Ndb::getDatabaseName(), 76
Ndb::getDatabaseSchemaName(), 76
Ndb::getDictionary(), 75
Ndb::getNdbError(), 80
Ndb::getNdbErrorDetail(), 81
Ndb::init(), 75
Ndb::Key_part_ptr structure, 224
Ndb::nextEvent(), 80
Ndb::PartitionSpec structure, 229
Ndb::pollEvents(), 80
Ndb::setDatabaseName(), 76
Ndb::setDatabaseSchemaName(), 76
Ndb::startTransaction(), 77
NdbBlob class, 82
479
Index
NdbBlob::ActiveHook type, 85
NdbBlob::blobsFirstBlob(), 89
NdbBlob::blobsNextBlob(), 90
NdbBlob::getBlobEventName(), 90
NdbBlob::getBlobTableName(), 90
NdbBlob::getColumn(), 89
NdbBlob::getLength(), 87
NdbBlob::getNdbError(), 89
NdbBlob::getNdbOperation(), 91
NdbBlob::getNull(), 87
NdbBlob::getPos(), 88
NdbBlob::getState(), 85
NdbBlob::getValue(), 85
NdbBlob::getVersion(), 86
NdbBlob::readData(), 88
NdbBlob::setActiveHook(), 86
NdbBlob::setNull(), 87
NdbBlob::setPos(), 88
NdbBlob::setValue(), 86
NdbBlob::State type, 85
NdbBlob::truncate(), 88
NdbBlob::writeData(), 89
NdbDictionary class, 91
NdbError structure, 224
NdbError::Classification type, 227
NdbError::Status type, 226
NdbEventOperation class, 93
NdbEventOperation::execute(), 100
NdbEventOperation::getBlobHandle(), 97
NdbEventOperation::getEventType(), 96
NdbEventOperation::getGCI(), 98
NdbEventOperation::getLatestGCI(), 98
NdbEventOperation::getNdbError(), 98
NdbEventOperation::getPreBlobHandle(), 97
NdbEventOperation::getPreValue(), 97
NdbEventOperation::getState(), 96
NdbEventOperation::getValue(), 96
NdbEventOperation::isConsistent(), 99
NdbEventOperation::mergeEvents(), 100
NdbEventOperation::State, 95
NdbEventOperation::tableFragmentationChanged(), 99
NdbEventOperation::tableFrmChanged(), 99
NdbEventOperation::tableNameChanged(), 99
NdbIndexOperation class, 101
example, 5
NdbIndexOperation::deleteTuple(), 102
NdbIndexOperation::getIndex(), 102
NdbIndexOperation::readTuple(), 102
NdbIndexOperation::updateTuple(), 102
NdbIndexScanOperation class, 103
NdbIndexScanOperation::BoundType, 104
NdbIndexScanOperation::end_of_bound(), 107
NdbIndexScanOperation::getDescending(), 105
NdbIndexScanOperation::getSorted(), 105
NdbIndexScanOperation::get_range_no(), 104
NdbIndexScanOperation::readTuples(), 105
NdbIndexScanOperation::reset_bounds(), 107
NdbInterpretedCode register-loading methods, 112
NdbInterpretedCode() (constructor), 112
NdbInterpretedCode::add_reg(), 115
NdbInterpretedCode::add_val(), 127
NdbInterpretedCode::branch_col_and_mask_eq_mask(), 124
NdbInterpretedCode::branch_col_and_mask_eq_zero(), 125
NdbInterpretedCode::branch_col_and_mask_ne_mask(), 125
NdbInterpretedCode::branch_col_and_mask_ne_zero(), 126
NdbInterpretedCode::branch_col_eq(), 120
NdbInterpretedCode::branch_col_eq_null(), 122
NdbInterpretedCode::branch_col_ge(), 122
NdbInterpretedCode::branch_col_gt(), 121
NdbInterpretedCode::branch_col_le(), 121
NdbInterpretedCode::branch_col_like(), 123
NdbInterpretedCode::branch_col_lt(), 121
NdbInterpretedCode::branch_col_ne(), 120
NdbInterpretedCode::branch_col_ne_null(), 123
NdbInterpretedCode::branch_col_notlike(), 124
NdbInterpretedCode::branch_eq(), 118
NdbInterpretedCode::branch_eq_null(), 119
NdbInterpretedCode::branch_ge(), 117
NdbInterpretedCode::branch_gt(), 117
NdbInterpretedCode::branch_label(), 116
NdbInterpretedCode::branch_le(), 118
NdbInterpretedCode::branch_lt(), 118
NdbInterpretedCode::branch_ne(), 118
NdbInterpretedCode::branch_ne_null(), 119
NdbInterpretedCode::call_sub(), 129
NdbInterpretedCode::def_label(), 116
NdbInterpretedCode::def_sub(), 128
NdbInterpretedCode::finalise(), 129
NdbInterpretedCode::getNdbError(), 130
NdbInterpretedCode::getTable(), 129
NdbInterpretedCode::getWordsUsed(), 130
NdbInterpretedCode::interpret_exit_nok(), 127
NdbInterpretedCode::interpret_exit_ok(), 126
NdbInterpretedCode::interpret_last_row(), 127
NdbInterpretedCode::load_const_null(), 112
NdbInterpretedCode::load_const_u16(), 112
NdbInterpretedCode::load_const_u32(), 113
NdbInterpretedCode::load_const_u64(), 113
NdbInterpretedCode::read_attr(), 114
NdbInterpretedCode::ret_sub(), 129
NdbInterpretedCode::sub_reg(), 115
NdbInterpretedCode::sub_val(), 128
NdbInterpretedCode::write_attr(), 114
NdbMgmHandle, 281, 286, 286, 287
NdbOperation class, 130
example, 5
NdbOperation::AbortOption, 134
NdbOperation::deleteTuple(), 142
NdbOperation::equal(), 138
NdbOperation::getBlobHandle(), 136
NdbOperation::getLockMode(), 138
NdbOperation::getNdbError(), 137
NdbOperation::getNdbErrorLine(), 137
NdbOperation::getNdbTransaction(), 138
NdbOperation::getTable(), 137
NdbOperation::getTableName(), 136
NdbOperation::getType(), 137
NdbOperation::getValue(), 135
NdbOperation::insertTuple(), 141
NdbOperation::LockMode, 134
NdbOperation::readTuple(), 142
NdbOperation::setValue(), 139
NdbOperation::Type, 134
NdbOperation::updateTuple(), 142
NdbOperation::writeTuple(), 142
NdbRecAttr class, 143
NdbRecAttr::aRef(), 149
NdbRecAttr::char_value(), 146
NdbRecAttr::clone(), 149
NdbRecAttr::double_value(), 148
480
Index
NdbRecAttr::float_value(), 148
NdbRecAttr::getColumn(), 144
NdbRecAttr::getType(), 145
NdbRecAttr::get_size_in_bytes(), 145
NdbRecAttr::int32_value(), 146
NdbRecAttr::int64_value(), 145
NdbRecAttr::int8_value(), 147
NdbRecAttr::isNULL(), 145
NdbRecAttr::medium_value(), 146
NdbRecAttr::short_value(), 146
NdbRecAttr::u_32_value(), 147
NdbRecAttr::u_64_value(), 147
NdbRecAttr::u_8_value(), 148
NdbRecAttr::u_char_value(), 148
NdbRecAttr::u_medium_value(), 147
NdbRecAttr::u_short_value(), 148
NdbRecord
example, 258, 274
NdbScanFilter class, 150
integer comparison methods, 155
NdbScanFilter::begin(), 153
NdbScanFilter::BinaryCondition, 152
NdbScanFilter::cmp(), 154
NdbScanFilter::end(), 153
NdbScanFilter::eq(), 155
NdbScanFilter::ge(), 157
NdbScanFilter::getNdbError(), 158
NdbScanFilter::getNdbOperation(), 158
NdbScanFilter::Group, 152
NdbScanFilter::gt(), 156
NdbScanFilter::isfalse(), 153
NdbScanFilter::isnotnull(), 158
NdbScanFilter::isnull(), 157
NdbScanFilter::istrue(), 153
NdbScanFilter::le(), 156
NdbScanFilter::lt(), 156
NdbScanFilter::ne(), 155
NdbScanOperation class, 158
NdbScanOperation::close(), 162
NdbScanOperation::deleteCurrentTuple(), 164
NdbScanOperation::getNdbTransaction(), 164
NdbScanOperation::getPruned(), 165
NdbScanOperation::lockCurrentTuple(), 162
NdbScanOperation::nextResult(), 161
NdbScanOperation::readTuples(), 160
NdbScanOperation::restart(), 164
NdbScanOperation::ScanFlag, 160
NdbScanOperation::updateCurrentTuple(), 163
NdbTransaction class, 165
NdbTransaction class methods
using, 4
NdbTransaction::AbortOption (OBSOLETE), 134, 167
NdbTransaction::close(), 171
NdbTransaction::commitStatus(), 172
NdbTransaction::CommitStatusType, 168
NdbTransaction::deleteTuple(), 178
NdbTransaction::ExecType, 168
NdbTransaction::execute(), 170
NdbTransaction::getGCI(), 171
NdbTransaction::getNdbError(), 172
NdbTransaction::getNdbErrorLine(), 173
NdbTransaction::getNdbErrorOperation(), 172
NdbTransaction::getNdbIndexOperation(), 169
NdbTransaction::getNdbIndexScanOperation(), 169
NdbTransaction::getNdbOperation(), 168
NdbTransaction::getNdbScanOperation(), 169
NdbTransaction::getNextCompletedOperation(), 173
NdbTransaction::getTransactionId(), 172
NdbTransaction::insertTuple(), 175
NdbTransaction::readTuple(), 173
NdbTransaction::refresh(), 171
NdbTransaction::scanIndex(), 180
NdbTransaction::scanTable(), 179
NdbTransaction::updateTuple(), 176
NdbTransaction::writeTuple(), 177
ndb_cluster_connection
get_next_ndb_object() method, 218
Ndb_cluster_connection class, 215
Ndb_cluster_connection::connect(), 217
Ndb_cluster_connection::get_auto_reconnect(), 220
Ndb_cluster_connection::set_auto_reconnect(), 219
Ndb_cluster_connection::set_name(), 217
Ndb_cluster_connection::set_optimized_node_selection(), 218
Ndb_cluster_connection::set_timeout(), 217
Ndb_cluster_connection::wait_until_ready(), 218
ndb_logevent structure (MGM API), 306
ndb_logevent_get_fd() function (MGM API), 283
ndb_logevent_get_latest_error() function (MGM API), 284
ndb_logevent_get_latest_error_msg() function (MGM API), 284
ndb_logevent_get_next() function (MGM API), 283
ndb_logevent_handle_error type (MGM API), 305
Ndb_logevent_type type (MGM API), 301
ndb_mgm_abort_backup() function (MGM API), 299
ndb_mgm_check_connection() function (MGM API), 289
ndb_mgm_cluster_state structure (MGM API), 311
ndb_mgm_connect() function (MGM API), 291
ndb_mgm_create_handle() function (MGM API), 286
ndb_mgm_create_logevent_handle() function (MGM API), 283, 283
ndb_mgm_destroy_handle() function (MGM API), 287
ndb_mgm_destroy_logevent_handle() function (MGM API), 283
ndb_mgm_disconnect() function (MGM API), 291
ndb_mgm_dump_state() function (MGM API), 292
ndb_mgm_enter_single_user() function (MGM API), 300
ndb_mgm_error type (MGM API), 301
ndb_mgm_event_category type (MGM API), 305
ndb_mgm_event_severity type (MGM API), 304
ndb_mgm_exit_single_user() function (MGM API), 300
ndb_mgm_get_clusterlog_loglevel() function (MGM API), 298
ndb_mgm_get_clusterlog_severity_filter() function (MGM API), 296
ndb_mgm_get_configuration_nodeid() function (MGM API), 288
ndb_mgm_get_connected_host() function (MGM API), 288
ndb_mgm_get_connected_port() function (MGM API), 288
ndb_mgm_get_connectstring() function (MGM API), 287
ndb_mgm_get_latest_error() function (MGM API), 285
ndb_mgm_get_latest_error_desc() function (MGM API), 285
ndb_mgm_get_latest_error_msg() function (MGM API), 285
ndb_mgm_get_loglevel_clusterlog() function (MGM API) - DEPRECATED, 298
ndb_mgm_get_status() function (MGM API), 292
ndb_mgm_is_connected() function (MGM API), 288
ndb_mgm_listen_event() function (MGM API), 282
ndb_mgm_node_state structure (MGM API), 311
ndb_mgm_node_status type (MGM API), 301
ndb_mgm_node_type type (MGM API), 301
ndb_mgm_number_of_mgmd_in_connect_string() function (MGM
API), 289
ndb_mgm_reply structure (MGM API), 312
ndb_mgm_restart() function (MGM API), 295
ndb_mgm_restart2() function (MGM API), 295
ndb_mgm_restart3() function (MGM API), 296
481
Index
O
Object class, 181
Object::FragmentType, 182
Object::getObjectId(), 184
Object::getObjectStatus(), 184
Object::getObjectVersion(), 184
Object::State, 182
Object::Status, 183
Object::Store, 183
Object::Type, 183
operations
defined, 5
scanning, 6
single-row, 5
transactions and, 5
or (ClusterJ), 365
P
param (ClusterJ), 369
PartitionKey (ClusterJ), 360
PartitionSpec (Ndb structure), 229
persist (ClusterJ), 348
PersistenceCapable (ClusterJ), 361
PersistenceModifier (ClusterJ), 362
Persistent (ClusterJ), 362
pollEvents() (method of Ndb), 80
Predicate (ClusterJ), 365
PredicateOperand (ClusterJ), 366
primaryKey (ClusterJ), 363
PrimaryKey (ClusterJ), 364
PROPERTY_CLUSTER_CONNECTION_SERVICE (ClusterJ), 340
PROPERTY_CLUSTER_CONNECTSTRING (ClusterJ), 341
PROPERTY_CLUSTER_CONNECT_DELAY (ClusterJ), 340
Q
Query (ClusterJ), 342
QueryBuilder (ClusterJ), 368
QueryDefinition (ClusterJ), 369
QueryDomainType (ClusterJ), 370
R
readData() (method of NdbBlob), 88
readTuple() (method of NdbIndexOperation), 102
readTuple() (method of NdbOperation), 142
readTuple() (method of NdbTransaction), 173
readTuples() (method of NdbIndexScanOperation), 105
readTuples() (method of NdbScanOperation), 160
read_attr() (method of NdbInterepretedCode), 114
record structure
NDB, 10
refresh() (method of NdbTransaction), 171
Register-loading methods (NdbInterepretedCode), 112
releaseRecord() (method of Dictionary), 51
remove (ClusterJ), 348
removeCachedIndex() (method of Dictionary), 52
removeCachedTable() (method of Dictionary), 52
replica
defined, 2
reset_bounds() (method of NdbIndexScanOperation), 107
restart() (method of NdbScanOperation), 164
restore
defined, 1
Results (ClusterJ), 343
ret_sub() (method of NdbInterepretedCode), 129
rollback (ClusterJ), 353
S
savePersistent (ClusterJ), 349
savePersistentAll (ClusterJ), 349
scan operations, 6
characteristics, 6
used for updates or deletes, 8
with lock handling, 8
ScanFlag (NdbScanOperation datatype), 160
scanIndex() (method of NdbTransaction), 180
scans
performing with NdbScanFilter and NdbScanOperation, 245
types supported, 1
using secondary indexes
example, 255
example (using NdbRecord), 258
scanTable() (method of NdbTransaction), 179
schema (ClusterJ), 361
482
Index
T
table (ClusterJ), 361
Table class, 184
Table::addColumn(), 198
Table::aggregate(), 204
Table::equal(), 192
Table::getColumn(), 190
Table::getDefaultNoPartitionsFlag(), 197
Table::getFragmentCount(), 194
Table::getFragmentData(), 193
Table::getFragmentDataLen(), 193
Table::getFragmentNodes(), 195
Table::getFragmentType(), 190
Table::getFrmData(), 192
Table::getFrmLength(), 193
Table::getKValue(), 191
Table::getLinearFlag(), 194
Table::getLogging(), 190
Table::getMaxLoadFactor(), 191
Table::getMaxRows(), 196
Table::getMinLoadFactor(), 191
Table::getNoOfCOlumns(), 191
Table::getNoOfPrimaryKeys(), 192
Table::getObjectId(), 197
Table::getObjectStatus(), 196
Table::getObjectType(), 196
Table::getObjectVersion(), 196
Table::getPrimaryKey(), 192
Table::getRangeListData(), 193
Table::getRangeListDataLen(), 193
Table::getRowChecksumIndicator(), 198
Table::getRowGCIIndicator(), 197
Table::getTableId(), 190
Table::getTablespace(), 195
483
Index
Table::getTablespaceData(), 194
Table::getTablespaceDataLen(), 194
Table::getTablespaceNames(), 197
Table::getTablespaceNamesLen(), 197
Table::hasDefaultValues(), 204
Table::setDefaultNoPartitionsFlag(), 201
Table::setFragmentCount(), 199
Table::setFragmentData(), 201
Table::setFragmentType(), 199
Table::setFrm(), 201
Table::setKValue(), 199
Table::setLinearFlag(), 199
Table::setLogging(), 198
Table::setMaxLoadFactor(), 200
Table::setMaxRows(), 200
Table::setMinLoadFactor(), 199
Table::setName(), 198
Table::setObjectType(), 203
Table::setRangeListData(), 202
Table::setRowChecksumIndicator(), 203
Table::setRowGCIIndicator(), 203
Table::setStatusInvalid(), 203
Table::setTablespace(), 200
Table::setTablespaceData(), 202
Table::setTablespaceNames(), 202
Table::SingleUserMode, 189
Table::validate(), 204
TableEvent (Event datatype), 55
tableFragmentationChanged() (method of NdbEventOperation), 99
tableFrmChanged() (method of NdbEventOperation), 99
tableNameChanged() (method of NdbEventOperation), 99
Tablespace class, 205
Tablespace::getAutoGrowSpecification(), 207
Tablespace::getDefaultLogfileGroup(), 207
Tablespace::getDefaultLogfileGroupId(), 207
Tablespace::getExtentSize(), 207
Tablespace::getName(), 206
Tablespace::getObjectId(), 208
Tablespace::getObjectStatus(), 208
Tablespace::getObjectVersion(), 208
Tablespace::setAutoGrowSpecification(), 209
Tablespace::setDefaultLogfileGroup(), 209
Tablespace::setExtentSize(), 209
Tablespace::setName(), 208
TC
and NDB Kernel, 10
defined, 3
selecting, 10
threading, 11
Transaction (ClusterJ), 352
Transaction Coordinator
defined, 3
transactions
concurrency, 11
example, 238
handling and transmission, 11
performance, 11
synchronous, 4
example of use, 235
using, 4
transporter
defined, 2
truncate() (method of NdbBlob), 88
TUP
and NDB Kernel, 10
defined, 3
Tuple Manager
defined, 3
Type (Index datatype), 63
Type (NdbOperation datatype), 134
Type (Object datatype), 183
U
Undofile class, 209
Undofile::getFileNo(), 213
Undofile::getLogfileGroup(), 212
Undofile::getLogfileGroupId(), 212
Undofile::getNode(), 212
Undofile::getObjectId(), 213
Undofile::getObjectStatus(), 213
Undofile::getObjectVersion(), 213
Undofile::getPath(), 211
Undofile::getSize(), 212
Undofile::setLogfileGroup(), 214
Undofile::setNode(), 214
Undofile::setPath(), 214
Undofile::setSize(), 214
unique (ClusterJ), 357
updateCurrentTuple() (method of NdbScanOperation), 163
updatePersistent (ClusterJ), 350
updatePersistentAll (ClusterJ), 350
updateTuple() (method of NdbIndexOperation), 102
updateTuple() (method of NdbOperation), 142
updateTuple() (method of NdbTransaction), 176
u_32_value() (method of NdbRecAttr), 147
u_64_value() (method of NdbRecAttr), 147
u_8_value() (method of NdbRecAttr), 148
u_char_value() (method of NdbRecAttr), 148
u_medium_value() (method of NdbRecAttr), 147
u_short_value() (method of NdbRecAttr), 148
V
validate() (method of Table), 204
value (ClusterJ), 355, 356, 356, 358
vendorName (ClusterJ), 356
W
wait_until_ready() (method of Ndb_cluster_connection), 218
where (ClusterJ), 369
writeData() (method of NdbBlob), 89
writeTuple() (method of NdbOperation), 142
writeTuple() (method of NdbTransaction), 177
write_attr() (method of NdbInterepretedCode), 114
484