- 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::createDatafile() - 2.3.4.1.3.
Dictionary::createEvent() - 2.3.4.1.4.
Dictionary::createIndex() - 2.3.4.1.5.
Dictionary::createLogfileGroup() - 2.3.4.1.6.
Dictionary::createRecord() - 2.3.4.1.7.
Dictionary::createTable() - 2.3.4.1.8.
Dictionary::createTablespace() - 2.3.4.1.9.
Dictionary::createUndofile() - 2.3.4.1.10.
Dictionary::dropDatafile() - 2.3.4.1.11.
Dictionary::dropEvent() - 2.3.4.1.12.
Dictionary::dropIndex() - 2.3.4.1.13.
Dictionary::dropLogfileGroup() - 2.3.4.1.14.
Dictionary::dropTable() - 2.3.4.1.15.
Dictionary::dropTablespace() - 2.3.4.1.16.
Dictionary::dropUndofile() - 2.3.4.1.17.
Dictionary::getDatafile() - 2.3.4.1.18.
NdbDictionary::getEmptyBitmask() - 2.3.4.1.19.
Dictionary::getEvent() - 2.3.4.1.20.
NdbDictionary::getFirstAttrId() - 2.3.4.1.21.
Dictionary::getIndex() - 2.3.4.1.22.
Dictionary::getLogfileGroup() - 2.3.4.1.23.
Dictionary::getNdbError() - 2.3.4.1.24.
NdbDictionary::getNextAttrId() - 2.3.4.1.25.
NdbDictionary::getNullBitOffset() - 2.3.4.1.26.
NdbDictionary::getOffset() - 2.3.4.1.27.
NdbDictionary::getRecordIndexName() - 2.3.4.1.28.
NdbDictionary::getRecordRowLength() - 2.3.4.1.29.
NdbDictionary::getRecordTableName() - 2.3.4.1.30.
NdbDictionary::getRecordType() - 2.3.4.1.31.
Dictionary::getTable() - 2.3.4.1.32.
Dictionary::getTablespace() - 2.3.4.1.33.
Dictionary::getUndofile() - 2.3.4.1.34.
NdbDictionary::getValuePtr() - 2.3.4.1.35.
Dictionary::invalidateIndex() - 2.3.4.1.36.
DIctionary::invalidateTable() - 2.3.4.1.37.
NdbDictionary::isNull() - 2.3.4.1.38.
Dictionary::listEvents() - 2.3.4.1.39.
Dictionary::listIndexes() - 2.3.4.1.40.
Dictionary::listObjects() - 2.3.4.1.41.
Dictionary::releaseRecord() - 2.3.4.1.42.
Dictionary::removeCachedTable() - 2.3.4.1.43.
Dictionary::removeCachedIndex() - 2.3.4.1.44.
NdbDictionary::setNull()
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.
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.
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.8, “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.34, “TheTableClass”.)A
RecordSpecificationused to describe a column. (See Section 2.3.31, “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.24, “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.34, “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
)
int dropIndex
(
const Index& index,
const Table& table
)
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.34, “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.
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.
Returns an empty column presence bitmask which can be used
with any NdbRecord to specify
that no NdbRecord columns are
to be included in the operation.
Signature.
static const unsigned char* getEmptyBitmask
(
void
)
Parameters. None.
Return value. An empty bitmask.
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.
Get the first attribute ID specified by an
NdbRecord object. Returns
false if no attribute ID is specified.
Signature.
static bool getFirstAttrId
(
const NdbRecord* record,
Uint32& firstAttrId
)
Parameters.
A pointer to an NdbRecord and
a reference to the attribute
(firstAttrID).
Return value.
Boolean false, when no attribute ID can be
obtained.
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.
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.10, “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.17, “The NdbError Structure”.
Description.
Get the next attribute ID specified by an
NdbRecord object following
the attribute ID passed in. Returns false
when there are no more attribute IDs to be returned.
Signature.
static bool getNextAttrId
(
const NdbRecord* record,
Uint32& attrId
)
Parameters.
A pointer to an NdbRecord and
a reference to an attribute ID.
Return value.
Boolean false, when no attribute ID can be
obtained.
Description.
Get the offset of the given attribute ID's null bit from the
start of the NdbRecord row.
Returns false if the attribute ID is not
present.
Signature.
static bool getNullBitOffset
(
const NdbRecord* record,
Uint32 attrId,
Uint32& bytes,
Uint32& bit
)
Parameters.
An NdbRecord
record in which to get the null bit
offset of the given attribute ID
(attrId). The offset is expressed
as a number of bytes (bytes) plus a
number of bits within the last byte
(bit).
Return value.
Boolean false, if the attribute with the
given ID is not present.
Description.
Get the offset of the given attribute ID's storage from the
start of the NdbRecord row.
Returns false if the attribute id is not
present
Signature.
static bool getOffset
(
const NdbRecord* record,
Uint32 attrId,
Uint32& offset
)
Parameters.
The offset of the given attribute
ID's storage from the start of the
NdbRecord row.
Return value.
Boolean false, if no attribute ID can be
found.
Description.
Get the name of the Index
object that the NdbRecord
refers to.
If the NdbRecord object is not
an IndexAccess
NdbRecord, the method returns
null.
Signature.
static const char* getRecordIndexName
(
const NdbRecord* record
)
Parameters.
A pointer to the NdbRecord
for which to get the name.
Return value.
The name, if any. Otherwise, or if the
NdbRecord object is not of
the IndexAccess type, this method returns
null.
Description.
Get the number of bytes needed to store one row of data laid
out as described by the
NdbRecord structure passed in
to this method.
Signature.
static Uint32 getRecordRowLength
(
const NdbRecord* record
)
Parameters.
An NdbRecord object.
Return value. The number of bytes needed per row.
Description.
Return the name of the table object that the
NdbRecord refers to. This
method returns null if the record is not a
TableAccess.
Signature.
static const char* getRecordTableName
(
const NdbRecord* record
)
Parameters.
The record
(NdbRecord object) for which
to get the table name.
Return value.
The name of the table, or null if the
NdbRecord object' type
is not TableAccess.
Description.
Return the type of the
NdbRecord object passed.
Signature.
static RecordType getRecordType
(
const NdbRecord* record
)
Parameters.
An NdbRecord object.
Return value.
The RecordType of the
NdbRecord
(IndexAccess or
TableAccess).
Description.
This method can be used to access the table with a known name.
See Section 2.3.34, “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.35, “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.36, “The Undofile Class”.
Description. Returns a pointer to the beginning of stored data specified by attribute ID, by looking up the offset of the column stored in the NdbRecord object and returning the sum of the row position and the offset.
This method provides both row-const and non-row-const versions.
Signature.
static const char* getValuePtr
(
const NdbRecord* record,
const char* row,
Uint32 attrId
)
static char* getValuePtr
(
const NdbRecord* record,
char* row,
Uint32 attrId
)
Parameters.
A pointer to an NdbRecord
object describing the row format, a pointer to the start of
the row data (const in the const version of
this method), and the attribute ID of the column,
Return value. A pointer to the start of the attribute in the row. This is null if the attribute is not part of the NdbRecord definition.
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.
Indicate whether the null bit for the given column is set to
true or false. The
location of the null bit in relation to the row pointer is
obtained from the passed
NdbRecord object. If the
column is not nullable, or if the column is not part of the
NdbRecord definition, the
method returns false.
Signature.
static bool isNull
(
const NdbRecord* record,
const char* row,
Uint32 attrId
)
Parameters.
A pointer to an NdbRecord
object describing the row format, a pointer to the start of
the row data, and the attribute ID of the column to check.
Return value.
Boolean true if the attribute ID exists in
this NdbRecord, is nullable,
and this row's null bit is set; otherwise, Boolean
false.
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.11, “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.11, “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.11, “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.28.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.
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.24, “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.
Description.
Set the null bit for the given column to the supplied value.
The offset for the null bit is obtained from the passed
NdbRecord object. If the
attribute ID is not part of the
NdbRecord, or if it is not
nullable, this method returns an error (-1).
Signature.
static int setNull
(
const NdbRecord* record,
char* row,
Uint32 attrId,
bool value
)
Parameters.
A pointer to the record
(NdbRecord object) describing
the row format; a pointer to the start of the
row data; the attribute ID of the
column (attrId); and the
value to set the null bit to
(true or false).
Return value.
Returns 0 on success; returns -1 if the
attrId is not part of the
record, or is not nullable.
