- 2.3.4 The Dictionary Class
- 2.3.4.1 Dictionary Methods
[+/-]
- 2.3.4.1.1.
DictionaryClass Constructor - 2.3.4.1.2.
Dictionary::beginSchemaTrans() - 2.3.4.1.3.
Dictionary::createDatafile() - 2.3.4.1.4.
Dictionary::createEvent() - 2.3.4.1.5.
Dictionary::createHashMap() - 2.3.4.1.6.
Dictionary::createIndex() - 2.3.4.1.7.
Dictionary::createLogfileGroup() - 2.3.4.1.8.
Dictionary::createRecord() - 2.3.4.1.9.
Dictionary::createTable() - 2.3.4.1.10.
Dictionary::createTablespace() - 2.3.4.1.11.
Dictionary::createUndofile() - 2.3.4.1.12.
Dictionary::dropDatafile() - 2.3.4.1.13.
Dictionary::dropEvent() - 2.3.4.1.14.
Dictionary::dropIndex() - 2.3.4.1.15.
Dictionary::dropLogfileGroup() - 2.3.4.1.16.
Dictionary::dropTable() - 2.3.4.1.17.
Dictionary::dropTablespace() - 2.3.4.1.18.
Dictionary::dropUndofile() - 2.3.4.1.19.
Dictionary::endSchemaTrans() - 2.3.4.1.20.
Dictionary::getDatafile() - 2.3.4.1.21.
Dictionary::getDefaultHashMap() - 2.3.4.1.22.
Dictionary::getEvent() - 2.3.4.1.23.
Dictionary::getHashMap() - 2.3.4.1.24.
Dictionary::getIndex() - 2.3.4.1.25.
Dictionary::getLogfileGroup() - 2.3.4.1.26.
Dictionary::getNdbError() - 2.3.4.1.27.
Dictionary::getTable() - 2.3.4.1.28.
Dictionary::getTablespace() - 2.3.4.1.29.
Dictionary::getUndofile() - 2.3.4.1.30.
Dictionary::hasSchemaTrans() - 2.3.4.1.31.
Dictionary::initDefaultHashMap() - 2.3.4.1.32.
Dictionary::invalidateIndex() - 2.3.4.1.33.
DIctionary::invalidateTable() - 2.3.4.1.34.
Dictionary::listEvents() - 2.3.4.1.35.
Dictionary::listIndexes() - 2.3.4.1.36.
Dictionary::listObjects() - 2.3.4.1.37.
Dictionary::prepareHashMap() - 2.3.4.1.38.
Dictionary::releaseRecord() - 2.3.4.1.39.
Dictionary::removeCachedTable() - 2.3.4.1.40.
Dictionary::removeCachedIndex()
Abstract
This section details all of the public methods of the
Dictionary class.
Description.
This method creates a new instance of the
Dictionary class.
Both the constructor and destructor for this class are protected methods, rather than public.
Signature.
protected Dictionary
(
Ndb& ndb
)
Parameters.
An Ndb object.
Return value.
A Dictionary object.
Destructor. The destructor takes no parameters and returns nothing.
protected ~Dictionary
(
void
)
Description.
Starts a schema transaction. An error occurs if a transaction
is already active, or if the kernel metadata is locked. You
can determine whether a schema transaction already exists
using the
hasSchemaTrans()
method.
A metadata operation occurs whenever data objects are created, altered, or dropped; such an operation can create additional suboperations in the NDB kernel.
The Ndb object and its
associated Dictionary support
one schema transaction at a time. By default, each metadata
operation is executed separately; that is, for each operation, a
schema transaction is started implicitly, the operation
(including any suboperations) is executed, and the transaction
is closed.
It is also possible to begin and end a schema transaction explicitly, and execute a set of user-defined operations atomically within its boundaries. In this case, all operations within the schema transaction either succeed, or are aborted and rolled back, as a unit. This is done by following the steps listed here:
To begin the schema transaction, call
beginSchemaTrans().Execute the desired operations (such as
createTable()).End the schema transaction by calling
endSchemaTrans.
Each operation is sent to the NDB kernel, which parses and saves it. A parse failure results in a rollback to the previous user operation before returning, at which point the user can either continue with or abort the entire transaction.
After all operations have been submitted,
endSchemaTrans() processes and commits them.
In the event of an error, the transaction is immediately
aborted.
If the user exits before calling
endSchemaTrans(), the NDB kernel aborts the
transaction. If the user exits before the call to
endSchemaTrans() returns, the kernel
continues with the request, and its completion status is
reported in the cluster log.
Signature.
int beginSchemaTrans
(
void
)
Parameters. None.
Return value. Returns 0 on success, -1 on error.
Description.
This method creates a new datafile, given a
Datafile object.
Signature.
int createDatafile
(
const Datafile& dFile
)
Parameters.
A single argument—a reference to an instance of
Datafile—is required.
Return value.
0 on success, -1 on
failure.
Description.
Creates an event, given a reference to an
Event object.
Signature.
int createEvent
(
const Event& event
)
Parameters.
A reference event to an
Event object.
Return value.
0 on success, -1 on
failure.
Description.
Creates a HashMap.
Signature.
int createHashMap
(
const HashMap& hashmap,
ObjectId* id = 0
)
Parameters. A reference to the hash map, and, optionally, an ID to be assigned to it. Added in MySQL Cluster NDB 7.1.23 and MySQL Cluster NDB 7.2.7.
Return value. Returns 0 on success; on failure, returns -1 and sets an error.
Description.
This method creates an index given an instance of
Index and possibly an
optional instance of Table.
Signature. This method can be invoked with or without a reference to a table object:
int createIndex
(
const Index& index
)
int createIndex
(
const Index& index,
const Table& table
)
Parameters.
Required: A reference to an
Index object.
Optional: A reference to a
Table object.
Return value.
0 on success, -1 on
failure.
Description.
This method creates a new logfile group, given an instance of
LogfileGroup.
Signature.
int createLogfileGroup
(
const LogfileGroup& lGroup
)
Parameters.
A single argument, a reference to a
LogfileGroup object, is
required.
Return value.
0 on success, -1 on
failure.
Description.
This method is used to create an
NdbRecord object for use in
table or index scanning operations.
Dictionary::createRecord() is available
beginning with MySQL Cluster NDB 6.2.3.
Signature. The signature of this method depends on whether the resulting NdbRecord is to be used in table or index operations:
To create an NdbRecord for use
in table operations, use the following:
NdbRecord* createRecord
(
const Table* table,
const RecordSpecification* recSpec,
Uint32 length,
Uint32 elSize
)
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* recSpec,
Uint32 length,
Uint32 elSize
)
or
NdbRecord* createRecord
(
const Index* index,
const RecordSpecification* recSpec,
Uint32 length,
Uint32 elSize
)
Parameters.
Dictionary::createRecord() takes the
following parameters:
If this
NdbRecordis to be used with an index, a pointer to the correspondingIndexobject. If theNdbRecordis to be used with a table, this parameter is omitted. (See Section 2.3.9, “TheIndexClass”.)A pointer to a
Tableobject representing the table to be scanned. If theNdbrecordproduced is to be used with an index, then this optionally specifies the table containing that index. (See Section 2.3.35, “TheTableClass”.)A
RecordSpecificationused to describe a column. (See Section 2.3.32, “TheRecordSpecificationStructure”.The
lengthof the record.The size of the elements making up this record.
Return value.
An NdbRecord for use in
operations involving the given table or index.
Example.
See Section 2.3.25, “The NdbRecord Interface”.
Description.
Creates a table given an instance of
Table.
Signature.
int createTable
(
const Table& table
)
Parameters.
An instance of Table. See
Section 2.3.35, “The Table Class”, for more information.
Return value.
0 on success, -1 on
failure.
Description.
This method creates a new tablespace, given a
Tablespace object.
Signature.
int createTablespace
(
const Tablespace& tSpace
)
Parameters.
This method requires a single argument—a reference to an
instance of Tablespace.
Return value.
0 on success, -1 on
failure.
Description.
This method creates a new undofile, given an
Undofile object.
Signature.
int createUndofile
(
const Undofile& uFile
)
Parameters.
This method requires one argument: a reference to an instance
of Undofile.
Return value.
0 on success, -1 on
failure.
Description.
This method drops a data file, given a
Datafile object.
Signature.
int dropDatafile
(
const Datafile& dFile
)
Parameters.
A single argument—a reference to an instance of
Datafile—is required.
Return value.
0 on success, -1 on
failure.
Description.
This method drops an event, given a reference to an
Event object.
Signature.
int dropEvent
(
const char* name,
int force = 0
)
Parameters. This method takes two parameters:
The
nameof the event to be dropped, as a string.By default,
dropEvent()fails if the event specified does not exist. You can override this behavior by passing any nonzero value for the (optional)forceargument; in this case no check is made as to whether there actually is such an event, and an error is returned only if the event exists but it was for whatever reason not possible to drop it.
Return value.
0 on success, -1 on
failure.
Description.
This method drops an index given an instance of
Index, and possibly an
optional instance of Table.
Signature.
int dropIndex
(
const Index& index
)
Parameters. This method takes two parameters, one of which is optional:
Return value.
0 on success, -1 on
failure.
Description.
Given an instance of
LogfileGroup, this method
drops the corresponding log file group.
Signature.
int dropLogfileGroup
(
const LogfileGroup& lGroup
)
Parameters.
A single argument, a reference to a
LogfileGroup object, is
required.
Return value.
0 on success, -1 on
failure.
Description.
Drops a table given an instance of
Table.
Signature.
int dropTable
(
const Table& table
)
Parameters.
An instance of Table. See
Section 2.3.35, “The Table Class”, for more information.
Return value.
0 on success, -1 on
failure.
Description.
This method drops a tablespace, given a
Tablespace object.
Signature.
int dropTablespace
(
const Tablespace& tSpace
)
Parameters.
This method requires a single argument—a reference to an
instance of Tablespace.
Return value.
0 on success, -1 on
failure.
Description.
This method drops an undo file, given an
Undofile object.
Signature.
int dropUndofile
(
const Undofile& uFile
)
Parameters.
This method requires one argument: a reference to an instance
of Undofile.
Return value.
0 on success, -1 on
failure.
Description.
Ends a schema transaction begun with
beginSchemaTrans();
causes operations to be processed and either committed, or
aborted and rolled back. This method combines transaction
execution and closing; separate methods for these tasks are
not required (or implemented). This method may be called
successfully even if no schema transaction is currently
active.
As with many other NDB API methods, it is entirely possible
for endSchemaTrans() to overwrite any
current error code. For this reason, you should first check
for and save any error code that may have resulted from a
previous, failed operation.
Signature.
int endSchemaTrans
(
Uint32 flags = 0
)
Parameters. The flags determines how the completed transaction is handled. The default is 0, which causes the transaction to be committed.
Dictionary::SchemaTransFlag.
You can also use with endSchemaTrans()
either of the SchemaTransFlag values shown
here:
SchemaTransAbort(= 1): Causes the transaction to be abortedSchemaTransBackground(= 2): Causes the transaction to execute in the background; the result is written to the cluster log, while the application continues without waiting for a response.
Return value.
Returns 0 on success; in the event of an error, returns -1 and
sets an NdbError error code.
Description.
This method is used to retrieve a
Datafile object, given the
node ID of the data node where a datafile is located and the
path to the datafile on that node's file system.
Signature.
Datafile getDatafile
(
Uint32 nodeId,
const char* path
)
Parameters. This method must be invoked using two arguments, as shown here:
The 32-bit unsigned integer
nodeIdof the data node where the datafile is locatedThe
pathto the datafile on the node's file system (string as character pointer)
Return value.
A Datafile object—see
Section 2.3.3, “The Datafile Class”, for details.
Description. Get a table's default hash map.
Added in MySQL Cluster NDB 7.23 and MySQL Cluster NDB 7.2.7.
Signature.
int getDefaultHashMap
(
HashMap& dst,
Uint32 fragments
)
Return value. Returns 0 on success; on failure, returns -1 and sets an error.
Description.
This method is used to obtain an
Event object, given the
event's name.
Signature.
const Event* getEvent
(
const char* eventName
)
Parameters.
The eventName, a string (character
pointer).
Return value.
A pointer to an Event object.
See Section 2.3.6, “The Event Class”, for more information.
Description. Gets a hash map by name or by table.
Added in MySQL Cluster NDB 7.23 and MySQL Cluster NDB 7.2.7.
Signature.
int getHashMap
(
HashMap& dst,
const char* name
)
Parameters.
A reference to the hash map and either a name or a
Table.
Return value. Returns 0 on success; on failure, returns -1 and sets an error.
Description. This method retrieves a pointer to an index, given the name of the index and the name of the table to which the table belongs.
Signature.
const Index* getIndex
(
const char* iName,
const char* tName
) const
Parameters. Two parameters are required:
The name of the index (
iName)The name of the table to which the index belongs (
tName)
Both of these are string values, represented by character pointers.
Return value.
A pointer to an Index. See
Section 2.3.9, “The Index Class”, for information about this
object.
Description.
This method gets a
LogfileGroup object, given
the name of the logfile group.
Signature.
LogfileGroup getLogfileGroup
(
const char* name
)
Parameters.
The name of the logfile group.
Return value.
An instance of LogfileGroup;
see Section 2.3.11, “The LogfileGroup Class”, for more information.
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.18, “The NdbError Structure”.
Description.
This method can be used to access the table with a known name.
See Section 2.3.35, “The Table Class”.
Signature.
const Table* getTable
(
const char* name
) const
Parameters.
The name of the table.
Return value.
A pointer to the table, or NULL if there is
no table with the name supplied.
Description.
Given either the name or ID of a tablespace, this method
returns the corresponding
Tablespace object.
Signatures. This method can be invoked in either of ways, as show here:
-
Using the tablespace name:
Tablespace getTablespace ( const char*name) -
Using the tablespace ID:
Tablespace getTablespace ( Uint32id)
Parameters. Either one of the following:
The
nameof the tablespace, a string (as a character pointer)The unsigned 32-bit integer
idof the tablespace
Return value.
A Tablespace object, as
discussed in Section 2.3.36, “The Tablespace Class”.
Description.
This method gets an Undofile
object, given the ID of the node where an undofile is located
and the file system path to the file.
Signature.
Undofile getUndofile
(
Uint32 nodeId,
const char* path
)
Parameters. This method requires the following two arguments:
The
nodeIdof the data node where the undofile is located; this value is passed as a 32-bit unsigned integerThe
pathto 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.37, “The Undofile Class”.
Description. Tells whether an NDB API schema transaction is ongoing.
Signature.
bool hasSchemaTrans
(
void
) const
Parameters. None.
Return value.
Returns boolean TRUE if a schema
transaction is in progress, otherwise
FALSE.
Description. Initialize a default hash map for a table.
Added in MySQL Cluster NDB 7.1.23 and MySQL Cluster NDB 7.2.7.
Signature.
int initDefaultHashMap
(
HashMap& dst,
Uint32 fragments
)
Parameters. A reference to the hash map and the number of fragments. Optionally the number of buckets.
Return value. Returns 0 on success; on failure, returns -1 and sets an error.
Description. This method is used to invalidate a cached index object.
This method is supported beginning with MySQL Cluster NDB 6.3.39, MySQL Cluster NDB 7.0.20, and MySQL Cluster NDB 7.1.9.
Signature.
The index invalidated by this method can be referenced either
as an Index object (using a
pointer), or by index name and table name, as shown here:
void invalidateIndex
(
const char* indexName,
const char* tableName
)
void invalidateIndex
(
const Index* index
)
Parameters.
The names of the index to be removed from the cache and the
table to which it belongs
(indexName and
tableName, respectively), or a
pointer to the corresponding
Index object.
Return value. None.
Description. This method is used to invalidate a cached table object.
Signature.
void invalidateTable
(
const char* name
)
Beginning with MySQL Cluster NDB 6.3.39, MySQL Cluster NDB
7.0.20, and MySQL Cluster NDB 7.1.9, an alternative way of
calling this method is supported, using a
Table object rather than the
name of the table, as shown here:
void invalidateTable
(
const Table* table
)
Parameters.
The name of the table to be removed
from the table cache, or a pointer to the corresponding
Table object.
Return value. None.
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
)
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 (see Bug #47798):
int listEvents
(
List& list
) const
Parameters.
A reference to a List object.
(See Section 2.3.12, “The List Class”.)
Return value.
0 on success; -1 on
failure.
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.12, “The List Class”.)
Signature.
int listIndexes
(
List& list,
const char* table
) 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 (see Bug #47798):
int listIndexes
(
List& list,
const char* table
)
Parameters.
listIndexes() takes two arguments, both of
which are required:
A reference to the
Listthat contains the indexes following the call to the methodThe name of the
tablewhose indexes are to be listed
Return value.
0 on success, -1 on
failure.
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. Prior to MySQL Cluster NDB 6.2.19, MySQL Cluster NDB 6.3.29, and MySQL Cluster NDB 7.0.10, this method had only the following 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 (see Bug #48851), this method has the following additional signature:
int listObjects
(
List& list,
Object::Type type,
bool fullyQualified
) const
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 (see 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.12, “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.29.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.
Description.
Creates or retrieves a hash map suitable for alteration.
Requires a schema transaction to be in progress; see
Section 2.3.4.1.2, “Dictionary::beginSchemaTrans()”, for more
information.
Added in MySQL Cluster NDB 7.23 and MySQL Cluster NDB 7.2.7.
Signature.
int prepareHashMap
(
const Table& oldTable,
Table& newTable
)
Parameters. References to the old and new tables. Optionally, a number of buckets.
Return value. Returns 0 on success; on failure, returns -1 and sets an error.
Description.
This method is used to free an
NdbRecord after it is no
longer needed.
Signature.
void releaseRecord
(
NdbRecord* record
)
Parameters.
The NdbRecord to be cleaned
up.
Return value. None.
Example.
See Section 2.3.25, “The NdbRecord Interface”.
Description. This method removes the specified table from the local cache.
Signature.
void removeCachedTable
(
const char* table
)
Parameters.
The name of the table to be removed
from the cache.
Return value. None.
Description. This method removes the specified index from the local cache.
Signature.
void removeCachedIndex
(
const char* index,
const char* table
)
Parameters.
The removeCachedIndex() requires two
arguments:
The name of the
indexto be removed from the cacheThe name of the
tablein which the index is found
Return value. None.
