2.3.4.1 Dictionary Methods

2.3.4.1.1 Dictionary Class 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.

2.3.4.1.1 Dictionary Class Constructor

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

Note

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

Signature. 

protected Dictionary
    (
      Ndb& ndb
    )

Parameters.  An Ndb object.

Return value.  A Dictionary object.

Destructor.  The destructor takes no parameters and returns nothing.

protected ~Dictionary
    (
      void
    )
2.3.4.1.2 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.

2.3.4.1.3 Dictionary::createDatafile()

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

Signature. 

int createDatafile
    (
      const Datafile& dFile
    )

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

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

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

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

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

2.3.4.1.7 Dictionary::createLogfileGroup()

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

Signature. 

int createLogfileGroup
    (
      const LogfileGroup& lGroup
    )

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

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

2.3.4.1.8 Dictionary::createRecord()

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:

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

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

2.3.4.1.10 Dictionary::createTablespace()

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

Signature. 

int createTablespace
    (
      const Tablespace& tSpace
    )

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

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

2.3.4.1.11 Dictionary::createUndofile()

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

Signature. 

int createUndofile
    (
      const Undofile& uFile
    )

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

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

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

2.3.4.1.13 Dictionary::dropEvent()

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

Signature. 

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

Parameters.  This method takes two parameters:

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

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

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

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

  • Optional.  A reference to a Table object.

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

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

2.3.4.1.16 Dictionary::dropTable()

Description.  Drops a table given an instance of Table.

Signature. 

int dropTable
    (
      const Table& table
    )

Note

In MySQL Cluster NDB 7.3.5 and later, 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. (Bug #18069680)

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

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

2.3.4.1.17 Dictionary::dropTablespace()

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

Signature. 

int dropTablespace
    (
      const Tablespace& tSpace
    )

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

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

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

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

Note

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.

2.3.4.1.20 Dictionary::getDatafile()

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

Signature. 

Datafile getDatafile
    (
      Uint32      nodeId,
      const char* path
    )

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

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

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

Return value.  A Datafile object—see Section 2.3.3, “The Datafile Class”, for details.

2.3.4.1.21 Dictionary::getDefaultHashMap()

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
    )

or

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

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

2.3.4.1.22 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 delete each Event created using getEvent(), after the object is no longer required.

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.

2.3.4.1.23 Dictionary::getHashMap()

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
    )

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.

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

2.3.4.1.25 Dictionary::getLogfileGroup()

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

Signature. 

LogfileGroup getLogfileGroup
    (
      const char* name
    )

Parameters.  The name of the logfile group.

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

2.3.4.1.26 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.18, “The NdbError Structure”.

2.3.4.1.27 Dictionary::getTable()

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.

2.3.4.1.28 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 ways, as show here:

  • 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.36, “The Tablespace Class”.

2.3.4.1.29 Dictionary::getUndofile()

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

Signature. 

Undofile getUndofile
    (
      Uint32      nodeId,
      const char* path
    )

Parameters.  This method requires the following two arguments:

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

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

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

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

2.3.4.1.31 Dictionary::initDefaultHashMap()

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
    )

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.

2.3.4.1.32 Dictionary::invalidateIndex()

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.

2.3.4.1.33 DIctionary::invalidateTable()

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.

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

2.3.4.1.35 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.12, “The List Class”.)

Signature. 

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 (see Bug #47798):

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

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

  • A reference to the List that contains the indexes following the call to the method

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

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

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

2.3.4.1.37 Dictionary::prepareHashMap()

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
    )

or

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.

2.3.4.1.38 Dictionary::releaseRecord()

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

Signature. 

void releaseRecord
    (
      NdbRecord* record
    )

Parameters.  The NdbRecord to be cleaned up.

Return value.  None.

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

2.3.4.1.39 Dictionary::removeCachedTable()

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

Signature. 

void removeCachedTable
    (
      const char* table
    )

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

Return value.  None.

2.3.4.1.40 Dictionary::removeCachedIndex()

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

Signature. 

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

Parameters.  The removeCachedIndex() requires two arguments:

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

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

Return value.  None.