Documentation Home
MySQL NDB Cluster API Developer Guide
Related Documentation Download this Manual
PDF (US Ltr) - 3.6Mb
PDF (A4) - 3.6Mb


2.3.14 The NdbDictionary Class

This section provides information about the NdbDictionary class, which stores meta-information about NDB database objects, such as tables, columns, and indexes.

While the preferred method of database object creation and deletion is through the MySQL Server, NdbDictionary also permits the developer to perform these tasks through the NDB API.

NdbDictionary Class Overview

Parent class

None

Child classes

Dictionary, Column, Object

For the numeric equivalents to enumerations of NdbDictionary subclasses, see the file /storage/ndb/include/ndbapi/NdbDictionary.hpp in the NDB Cluster source tree.

Description

This is a data dictionary class that supports enquiries about tables, columns, and indexes. It also provides ways to define these database objects and to remove them. Both sorts of functionality are supplied using inner classes that model these objects. These include the following inner classes:

  • Table for working with tables

  • Column for creating table columns

  • Index for working with secondary indexes

  • Dictionary for creating database objects and making schema enquiries

  • Event for working with events in the cluster.

Additional Object subclasses model the tablespaces, log file groups, data files, and undo files required for working with NDB Cluster Disk Data table, as well as with foreign key constraints.

Tables and indexes created using NdbDictionary cannot be viewed from the MySQL Server.

Dropping indexes through the NDB API that were created originally from an NDB Cluster causes inconsistencies. It is possible that a table from which one or more indexes have been dropped using the NDB API will no longer be usable by MySQL following such operations. In this event, the table must be dropped, and then re-created using MySQL to make it accessible to MySQL once more.

Methods

NdbDictionary itself has no public instance methods, only static methods that are used for working with NdbRecord objects. Operations not using NdbRecord are accomplished by means of NdbDictionary subclass instance methods. The following table lists the public methods of NdbDictionary and the purpose or use of each method:

Table 2.37 NdbDictionary class methods and descriptions

Name Description
getEmptyBitmask() Returns an empty column presence bitmask which can be used with NdbRecord
getFirstAttrId() Get the first attribute ID specified by a given NdbRecord object
getRecordIndexName() Gets the name of the index object referred to by an NdbRecord
getRecordRowLength() Get the number of bytes needed to store one row of data using a given NdbRecord
getRecordTableName() Gets the name of the table object referred to by an NdbRecord
getRecordType() Gets the RecordType of an NdbRecord
getValuePtr() Returns a pointer to the beginning of stored data specified by attribute ID, using NdbRecord
isNull() Show whether the null bit for a column is true or false
setNull() Set a column's null bit

Types

NdbDictionary defines two data structures, listed here:

NdbDictionary::AutoGrowSpecification

Abstract

This section provides information about the AutoGrowSpecification data structure.

Parent class

NdbDictionary

Description

The AutoGrowSpecification is a data structure defined in the NdbDictionary class, and is used as a parameter to or return value of some of the methods of the Tablespace and LogfileGroup classes.

Members

AutoGrowSpecification has the members shown in the following table:

Table 2.38 NdbDictionary::AutoGrowSpecification data structure member names and descriptions

Name Description
min_free ???
max_size ???
file_size ???
filename_pattern ???

NdbDictionary::getEmptyBitmask()

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.

NdbDictionary::getFirstAttrId()

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.

NdbDictionary::getNextAttrId()

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.

NdbDictionary::getNullBitOffset()

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.

NdbDictionary::getOffset()

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.

NdbDictionary::getRecordIndexName()

Description

Get the name of the Index object that the NdbRecord refers to.

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.

NdbDictionary::getRecordRowLength()

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.

NdbDictionary::getRecordTableName()

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.

NdbDictionary::getRecordType()

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

NdbDictionary::getValuePtr()

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.

Signature

This method provides both row-const and non-row-const versions:

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.

NdbDictionary::isNull()

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.

NdbDictionary::RecordSpecification

This section provides information about the RecordSpecification structure.

Parent class

NdbDictionary

Description

This structure is used to specify columns and range offsets when creating NdbRecord objects.

Members

The elements making up this structure are shown in the following table:

Table 2.39 NdbDictionary::RecordSpecification attributes, with types and descriptions

Name Type Description
column Column The column described by this entry (the column's maximum size defines the field size for the row). Even when creating an NdbRecord for an index, this must point to a column obtained from the underlying table, and not from the index itself.
offset Uint32 The offset of data from the beginning of a row. For reading blobs, the blob handle (NdbBlob), rather than the actual blob data, is written into the row. This means that there must be at least sizeof(NdbBlob*) must be available in the row.
nullbit_byte_offset Uint32 The offset from the beginning of the row of the byte containing the NULL bit.
nullbit_bit_in_byte Uint32 NULL bit (0-7).

nullbit_byte_offset and nullbit_bit_in_byte are not used for non-nullable columns.

For more information, see Section 2.3.22, “The NdbRecord Interface”.

NdbDictionary::setNull()

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.