2.3.3 The Dictionary Class

This section provides information about the Dictionary class.

• Dictionary Class Overview

• Dictionary Class Constructor

• Dictionary::beginSchemaTrans()

• Dictionary::createDatafile()

• Dictionary::createEvent()

• Dictionary::createForeignKey()

• Dictionary::createHashMap()

• Dictionary::createIndex()

• Dictionary::createLogfileGroup()

• Dictionary::createRecord()

• Dictionary::createTable()

• Dictionary::createTablespace()

• Dictionary::createUndofile()

• Dictionary::dropDatafile()

• Dictionary::dropEvent()

• Dictionary::dropForeignKey()

• Dictionary::dropIndex()

• Dictionary::dropLogfileGroup()

• Dictionary::dropTable()

• Dictionary::dropTablespace()

• Dictionary::dropUndofile()

• Dictionary::endSchemaTrans()

• Dictionary::getDatafile()

• Dictionary::getDefaultHashMap()

• Dictionary::getEvent()

• Dictionary::getForeignKey()

• Dictionary::getHashMap()

• Dictionary::getIndex()

• Dictionary::getLogfileGroup()

• Dictionary::getNdbError()

• Dictionary::getTable()

• Dictionary::getTablespace()

• Dictionary::getUndofile()

• Dictionary::hasSchemaTrans()

• Dictionary::initDefaultHashMap()

• Dictionary::invalidateIndex()

• DIctionary::invalidateTable()

• Dictionary::listEvents()

• Dictionary::listIndexes()

• Dictionary::listObjects()

• Dictionary::prepareHashMap()

• Dictionary::releaseEvent()

• Dictionary::releaseRecord()

• Dictionary::removeCachedTable()

• Dictionary::removeCachedIndex()

Dictionary Class Overview

Parent class

NdbDictionary

Child classes

List

Description

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

Methods

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

Table 2.12 Dictionary class methods and descriptions

Name	Description
Dictionary()	Class constructor method
~Dictionary()	Destructor method
beginSchemaTrans()	Begins a schema transaction
createDatafile()	Creates a data file
createEvent()	Creates an event
createForeignKey()	Creates a foreign key
createHashMap()	Creates a hash map
createIndex()	Creates an index
createLogfileGroup()	Creates a log file group
createRecord()	Creates an Ndbrecord object
createTable()	Creates a table
createTablespace()	Creates a tablespace
createUndofile()	Creates an undo file
dropDatafile()	Drops a data file
dropEvent()	Drops an event
dropForeignKey()	Drops a foreign key
dropIndex()	Drops an index
dropLogfileGroup()	Drops a log file group
dropTable()	Drops a table
dropTablespace()	Drops a tablespace
dropUndofile()	Drops an undo file
endSchemaTrans()	Ends (commits and closes) a schema transaction
getDatafile()	Gets the data file having the given name
getDefaultHashMap()	Gets a table's default hash map
getEvent()	Gets the event having the given name
getForeignKey()	Gets the foreign key having the given name or reference
getHashMap()	Gets the hash map given its name or associated table
getIndex()	Gets the index having the given name
getLogfileGroup()	Gets the log file group having the given name
getNdbError()	Retrieves the latest error
getTable()	Gets the table having the given name
getTablespace()	Gets the tablespace having the given name
getUndofile()	Gets the undo file having the given name
hasSchemaTrans()	Tells whether a schema transaction currently exists
initDefaultHashMap()	Initializes a atble' default hash map
invalidateTable()	Invalidates a table object
listObjects()	Fetches a list of the objects in the dictionary
listIndexes()	Fetches a list of the indexes defined on a given table
listEvents()	Fetches a list of the events defined in the dictionary
prepareHashMap()	Creates or retrieves a hash map that can be updated
releaseEvent()	Deletes an event returned earlier by getEvent()
removeCachedTable()	Removes a table from the local cache
removeCachedIndex()	Removes an index from the local cache

Database objects such as tables and indexes created using the Dictionary::create*() methods cannot be seen by the MySQL Server. This means that they cannot be accessed by MySQL clients, and that they cannot be replicated. For these reasons, it is often preferable to avoid working with them.

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.10, “The List Class”, and Section 2.3.4, “The Element Structure”.

Dictionary Class Constructor

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
    )

Dictionary::beginSchemaTrans()

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:

1. To begin the schema transaction, call beginSchemaTrans().

2. Execute the desired operations (such as createTable()).

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

Dictionary::createDatafile()

Description

This method creates a new data file, 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.

Dictionary::createEvent()

Description

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

You should keep in mind that the NDB API does not track allocated event objects, which means that the user must delete the Event that was obtained using createEvent(), after this object is no longer required.

Signature

int createEvent
    (
      const Event& event
    )

Parameters

A reference event to an Event object.

Return value

0 on success, -1 on failure.

Dictionary::createForeignKey()

Description

Creates a ForeignKey object, given a reference to this object and an Object ID.

Signature

int createForeignKey
    (
      const ForeignKey&,
      ObjectId* = 0,
      int flags = 0
    )

Parameters

A reference to the ForeignKey object, and an Object ID. An optional value flags, if used, allows the creation of the foreign key without performing any foreign key checks. If set, its value must be CreateFK_NoVerify (1).

Return value

0 on success.

Dictionary::createHashMap()

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.

Return value

Returns 0 on success; on failure, returns -1 and sets an error.

Dictionary::createIndex()

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.

Dictionary::createLogfileGroup()

Description

This method creates a new log file 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.

Dictionary::createRecord()

Description

This method is used to create an NdbRecord object for use in table or index scanning operations.

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

• A RecordSpecification used to describe a column.

• The length of the record.

• The size of the elements making up this record.

Return value

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

Example

See Section 2.3.22, “The NdbRecord Interface”.

Dictionary::createTable()

Description

Creates a table given an instance of Table.

Tables created using this method cannot be seen by the MySQL Server, cannot be updated by MySQL clients, and cannot be replicated.

Signature

int createTable
    (
      const Table& table
    )

Parameters

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

Return value

0 on success, -1 on failure.

Dictionary::createTablespace()

Description

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

Signature

int createTablespace
    (
      const Tablespace& tSpace
    )

Parameters

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

Return value

0 on success, -1 on failure.

Dictionary::createUndofile()

Description

This method creates a new undo file, 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.

Dictionary::dropDatafile()

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.

Dictionary::dropEvent()

Description

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

Signature

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

Parameters

This method takes two parameters:

• The name of the event to be dropped, as a string.

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

Return value

0 on success, -1 on failure.

Dictionary::dropForeignKey()

Description

This method drops a foreign key, given a reference to an ForeignKey object to be dropped.

Signature

int dropForeignKey
    (
      const ForeignKey&
    )

Parameters

A reference to the ForeignKey to be dropped.

Return value

0 on success.

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

This method takes two parameters, one of which is optional:

• Required: A reference to an Index object.

• : A reference to a Table object.

Return value

0 on success, -1 on failure.

Dictionary::dropLogfileGroup()

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.

Dictionary::dropTable()

Description

Drops a table given an instance of Table.

This method drops all foreign key constraints on the table that is being dropped, whether the dropped table acts as a parent table, child table, or both.

Prior to NDB 8.0, an NDB table dropped using this method persisted in the MySQL data dictionary but could not be dropped using DROP TABLE in the mysql client. In NDB 8.0, such “orphan” tables can be dropped using DROP TABLE. (Bug #29125206, Bug #93672)

Signature

int dropTable
    (
      const Table& table
    )

Parameters

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

Return value

0 on success, -1 on failure.

Dictionary::dropTablespace()

Description

This method drops a tablespace, given a Tablespace object.

Signature

int dropTablespace
    (
      const Tablespace& tSpace
    )

Parameters

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

Return value

0 on success, -1 on failure.

Dictionary::dropUndofile()

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.

Dictionary::endSchemaTrans()

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 aborted

• SchemaTransBackground (= 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.

Dictionary::getDatafile()

Description

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

Signature

Datafile getDatafile
    (
      Uint32      nodeId,
      const char* path
    )

Parameters

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

• The 32-bit unsigned integer nodeId of the data node where the data file is located

• The path to the data file 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.

Dictionary::getDefaultHashMap()

Description

Get a table's default hash map.

Signature

int getDefaultHashMap
    (
      HashMap& dst,
      Uint32 fragments
    )

or

int getDefaultHashMap
    (
      HashMap& dst,
      Uint32 buckets,
      Uint32 fragments
    )

Return value

Returns 0 on success; on failure, returns -1 and sets an error.

Dictionary::getEvent()

Description

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

getEvent() allocates memory each time it is successfully called. You should keep in mind that successive invocations of this method using the same event name return multiple, distinct objects.

The NDB API does not track allocated event objects, which means that the user must clean up each Event created using getEvent() with delete, after the object is no longer required. Beginning with NDB 8.0.30, you can do this with releaseEvent() instead.

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

Dictionary::getForeignKey()

Description

This method is used to obtain a new ForeignKey object representing an event, given a reference to the foreign key and its name.

Signature

int getForeignKey
    (
      ForeignKey& dst,
      const char* name
    )

Parameters

A reference to the foreign key and its name, a string (character pointer).

Return value

A pointer to a ForeignKey object.

Dictionary::getHashMap()

Description

Gets a hash map by name or by table.

Signatures

int getHashMap
    (
      HashMap& dst,
      const char* name
    )

or

int getHashMap
    (
      HashMap& dst,
      const Table* table
    )

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.

Dictionary::getIndex()

Description

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

Signature

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

Parameters

Two parameters are required:

• The name of the index (iName)

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

Both of these are string values, represented by character pointers.

Return value

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

Dictionary::getLogfileGroup()

Description

This method gets a LogfileGroup object, given the name of the log file group.

Signature

LogfileGroup getLogfileGroup
    (
      const char* name
    )

Parameters

The name of the log file group.

Return value

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

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.

Dictionary::getTable()

Description

This method can be used to access a Table whose name is already known.

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.

Dictionary::getTablespace()

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 the following two ways:

• Using the tablespace name:

  Tablespace getTablespace
      (
        const char* name
      )

• Using the tablespace ID:

  Tablespace getTablespace
      (
        Uint32 id
      )

Parameters

Either one of the following:

• The name of the tablespace, a string (as a character pointer)

• The unsigned 32-bit integer id of the tablespace

Return value

A Tablespace object, as discussed in Section 2.3.28, “The Tablespace Class”.

Dictionary::getUndofile()

Description

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

Signature

Undofile getUndofile
    (
      Uint32      nodeId,
      const char* path
    )

Parameters

This method requires the following two arguments:

• The nodeId of the data node where the undo file is located; this value is passed as a 32-bit unsigned integer

• The path to the undo file on the node's file system (string as character pointer)

Return value

An instance of Undofile. For more information, see Section 2.3.29, “The Undofile Class”.

Dictionary::hasSchemaTrans()

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.

Dictionary::initDefaultHashMap()

Description

Initialize a default hash map for a table.

Signature

int initDefaultHashMap
    (
      HashMap& dst,
      Uint32 fragments
    )

or

int initDefaultHashMap
    (
      HashMap& dst,
      Uint32 buckets,
      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.

Dictionary::invalidateIndex()

Description

This method is used to invalidate a cached index object.

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.

DIctionary::invalidateTable()

Description

This method is used to invalidate a cached table object.

Signature

void invalidateTable
    (
      const char* name
    )

It is also possibloe to use 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.

Dictionary::listEvents()

Description

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

Signature

int listEvents
    (
      List& list
    )

Parameters

A reference to an empty List. In NDB 8.0.29 and later, use clear() to empty a previously used List for reuse.

Return value

0 on success; -1 on failure.

Dictionary::listIndexes()

Description

This method is used to obtain a List of all the indexes on a table, given the table's name.

Signature

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

Parameters

listIndexes() takes two arguments, both of which are required:

• A reference to an empty List that, following the call to this method, contains the indexes. In NDB 8.0.29 and later, use clear() to empty a previously used List for reuse.

• The name of the table whose indexes are to be listed

Return value

0 on success, -1 on failure.

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

This method has two signatures:

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

and

int listObjects
    (
      List&        list,
      Object::Type type,
      bool         fullyQualified
    ) const

Parameters

A reference to an empty List object is required—this is the list that contains the dictionary's objects after listObjects() is called. (See Section 2.3.10, “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. If type is not given, then the list contains all of the dictionary's objects.

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.

In NDB 8.0.29 and later, you can call clear() to empty a previously used List for reuse.

Note

Setting fullyQualified to false causes listObjects() to return objects that use fully qualified names.

Return value

0 on success, -1 on failure.

Dictionary::prepareHashMap()

Description

Creates or retrieves a hash map suitable for alteration. Requires a schema transaction to be in progress; see Dictionary::beginSchemaTrans(), for more information.

Signatures

Either of the following:

• int prepareHashMap
      (
        const Table& oldTable,
        Table& newTable
      )

• int prepareHashMap
      (
        const Table& oldTable,
        Table& newTable,
        Uint32 buckets
      )

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.

Dictionary::releaseEvent()

Description

This method is used to free an Event after it is no longer needed. Typically this is an event returned by getEvent().

Signature

void releaseEvent
    (
      const Event* event
    )

Parameters

The Event to be cleaned up.

Return value

None.

This method was added in NDB 8.0.30.

Dictionary::releaseRecord()

Description

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

Signature

void releaseRecord
    (
      NdbRecord* record
    )

Parameters

The NdbRecord to be cleaned up.

Return value

None.

Example

See Section 2.3.22, “The NdbRecord Interface”.

Dictionary::removeCachedTable()

Description

This method removes the table, specified by name, 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.

Dictionary::removeCachedIndex()

Description

This method removes the specified index from the local cache, given the name of the index and that of the table in which it is contained.

Signature

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

Parameters

The removeCachedIndex() method requires two arguments:

• The name of the index to be removed from the cache

• The name of the table in which the index is found

Return value

None.