MySQL :: MySQL NDB Cluster API Developer Guide

NdbBlob Class Overview

Parent class

None

Child classes

None

Description

This class has no public constructor. An instance of NdbBlob is created using the NdbOperation::getBlobHandle() method during the operation preparation phase. (See Section 2.3.20, “The NdbOperation Class”.) This object acts as a handle on a blob column.

Methods

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

Table 2.34 NdbBlob class methods and descrptions

Name	Description
`blobsFirstBlob()`	Gets the first blob in a list.
`blobsNextBlob()`	Gets the next blob in a list
`close()`	Release internal resources prior to commit or abort
`getBlobEventName()`	Gets a blob event name
`getBlobTableName()`	Gets a blob data segment's table name.
`getColumn()`	Gets a blob column.
`getLength()`	Gets the length of a blob, in bytes
`getNdbError()`	Gets an error (an `NdbError` object)
`getNdbOperation()`	Get a pointer to the operation (`NdbOperation` object) to which this `NdbBlob` object belonged when created.
`getNull()`	Checks whether a blob value is `NULL`
`getPos()`	Gets the current position for reading/writing
`getState()`	Gets the state of an `NdbBlob` object
`getValue()`	Prepares to read a blob value
`getVersion()`	Checks whether a blob is statement-based or event-based
`readData()`	Reads data from a blob
`setActiveHook()`	Defines a callback for blob handle activation
`setNull()`	Sets a blob to `NULL`
`setPos()`	Sets the position at which to begin reading/writing
`setValue()`	Prepares to insert or update a blob value
`truncate()`	Truncates a blob to a given length
`writeData()`	Writes blob data

getBlobTableName() and getBlobEventName() are static methods.

Most NdbBlob methods (nearly all of those whose return type is int) return 0 on success and -1 in the event of failure.

Types

The public types defined by NdbBlob are shown here:

Table 2.35 NdbBlob types and descriptions

Name	Description
`ActiveHook()`	Callback for `NdbBlob::setActiveHook()`
`State()`	Represents the states that may be assumed by the `NdbBlob`.

Blob Data Storage. Blob data is stored in 2 locations:

The header and inline bytes are stored in the blob column.
The blob's data segments are stored in a separate table named NDB$BLOB_tid_cid, where tid is the table ID, and cid is the blob column ID.

The inline and data segment sizes can be set using the appropriate Column methods when the table is created. See Section 2.3.1, “The Column Class”, for more information about these methods.

Data Access Types. NdbBlob supports 3 types of data access: These data access types can be applied in combination, provided that they are used in the order given above.

In the preparation phase, the NdbBlob methods getValue() and setValue() are used to prepare a read or write of a blob value of known size.
Also in the preparation phase, setActiveHook() is used to define a routine which is invoked as soon as the handle becomes active.
In the active phase, readData() and writeData() are used to read and write blob values having arbitrary sizes.

Blob operations. Blob operations take effect when the next transaction is executed. In some cases, NdbBlob is forced to perform implicit execution. To avoid this, you should always operate on complete blob data segments.

Use NdbTransaction::executePendingBlobOps() to flush reads and writes, which avoids any execution penalty if no operations are pending. This is not necessary following execution of operations, or after the next scan result.

NdbBlob also supports reading post- or pre-blob data from events. The handle can be read after the next event on the main table has been retrieved. The data becomes available immediately. (See Section 2.3.16, “The NdbEventOperation Class”, for more information.)

Blobs and NdbOperations. NdbOperation methods acting on NdbBlob objects have the following characteristics:.

NdbOperation::insertTuple() must use NdbBlob::setValue() if the blob attribute is nonnullable.
NdbOperation::readTuple() used with any lock mode can read but not write blob values.

When the LM_CommittedRead lock mode is used with readTuple(), the lock mode is automatically upgraded to LM_Read whenever blob attributes are accessed.
NdbOperation::updateTuple() can either overwrite an existing value using NdbBlob::setValue(), or update it during the active phase.
NdbOperation::writeTuple() always overwrites blob values, and must use NdbBlob::setValue() if the blob attribute is nonnullable.
NdbOperation::deleteTuple() creates implicit, nonaccessible blob handles.
A scan with any lock mode can use its blob handles to read blob values but not write them.

A scan using the LM_Exclusive lock mode can update row and blob values using updateCurrentTuple(); the operation returned must explicitly create its own blob handle.

A scan using the LM_Exclusive lock mode can delete row values (and therefore blob values) using deleteCurrentTuple(); this create implicit nonaccessible blob handles.
An operation which is returned by lockCurrentTuple() cannot update blob values.

Known Issues. The following are known issues or limitations encountered when working with NdbBlob objects:

Too many pending blob operations can overflow the I/O buffers.
The table and its blob data segment tables are not created atomically.

NdbBlob::ActiveHook

ActiveHook is a data type defined for use as a callback for the setActiveHook() method. (See NdbBlob::setActiveHook().)

Definition. ActiveHook is a custom data type defined as shown here:

typedef int ActiveHook
    (
      NdbBlob* me,
      void*    arg
    )

Description: This is a callback for NdbBlob::setActiveHook(), and is invoked immediately once the prepared operation has been executed (but not committed). Any calls to getValue() or setValue() are performed first. The blob handle is active so readData() or writeData() can be used to manipulate the blob value. A user-defined argument is passed along with the NdbBlob. setActiveHook() returns a nonzero value in the event of an error.

NdbBlob::blobsFirstBlob()

Description

This method initialises a list of blobs belonging to the current operation and returns the first blob in the list.

Signature

NdbBlob* blobsFirstBlob
    (
      void
    )

Parameters

None.

Return value

A pointer to the desired blob.

NdbBlob::blobsNextBlob()

Description

Use the method to obtain the next in a list of blobs that was initialised using blobsFirstBlob(). See NdbBlob::blobsFirstBlob().

Signature

NdbBlob* blobsNextBlob
    (
      void
    )

Parameters

None.

Return value

A pointer to the desired blob.

NdbBlob::close()

Description

Closes the blob handle, releasing internal resources as it does so, prior to committing or aborting the transaction. In other words, this signals that an application has finished with reading from a given blob. This method can be called only when the blob's State is Active.

Signature

int close
    (
      bool execPendingBlobOps = true
    )

Parameters

This method has a single boolean parameter execPendingBlobOps. If the value of this parameter true (the default), any pending blob operations are flushed before the blob handle is closed. If execPendingBlobOps is false, then it is assumed that the blob handle has no pending read or write operations to flush.

Return value

0 on success.

Read operations and locking. When a blob handle is created on a read operation using LM_Read or LM_Exclusive as the LockMode, the read operation can be unlocked only once all Blob handles created on this operation have been closed.

When a row containing blobs has been read with lock mode LM_CommittedRead, the mode is automatically upgraded to LM_Read to ensure consistency. In this case, when all the blob handles for the row have been closed, an unlock operation for the row is automatically performed by the call to the close() method, which adds a pending write operation to the blob. The upgraded lock is released following the call to execute().

NdbBlob::getBlobEventName()

Description

This method gets a blob event name. The blob event is created if the main event monitors the blob column. The name includes the main event name.

Signature

static int getBlobEventName
    (
      char*       name,
      Ndb*        ndb,
      const char* event,
      const char* column
    )

Parameters

This method takes the four parameters listed here:

name: The name of the blob event.
ndb: The relevant Ndb object.
event: The name of the main event.
column: The blob column.

Return value

0 on success, -1 on failure.

NdbBlob::getBlobTableName()

Description

This method gets the blob data segment table name.

This method is generally of use only for testing and debugging purposes.

Signature

static int getBlobTableName
    (
      char*       name,
      Ndb*        ndb,
      const char* table,
      const char* column
    )

Parameters

This method takes the four parameters listed here:

name: The name of the blob data segment table.
ndb: The relevant Ndb object.
table: The name of the main table.
column: The blob column.

Return value

Returns 0 on success, -1 on failure.

NdbBlob::getColumn()

Description

Use this method to get the blob column to which the NdbBlob belongs.

Signature

const Column* getColumn
    (
      void
    )

Parameters

None.

Return value

A Column object.

NdbBlob::getLength()

Description

This method gets the blob's current length in bytes.

Signature

int getLength
    (
      Uint64& length
    )

Parameters

A reference to the length.

Return value

The blob's length in bytes. For a NULL blob, this method returns 0. to distinguish between a blob whose length is 0 blob and one which is NULL, use the getNull() method.

NdbBlob::getNull()

Description

This method checks whether the blob's value is NULL.

Signature

int getNull
    (
      int& isNull
    )

Parameters

A reference to an integer isNull. Following invocation, this parameter has one of the following values, interpreted as shown here:

-1: The blob is undefined. If this is a nonevent blob, this result causes a state error.
0: The blob has a nonnull value.
1: The blob's value is NULL.

Return value

None.

NdbBlob::getNdbError()

Description

Use this method to obtain an error object. The error may be blob-specific or may be copied from a failed implicit operation. The error code is copied back to the operation unless the operation already has a nonzero error code.

Signature

const NdbError& getNdbError
    (
      void
    ) const

Parameters

None.

Return value

An NdbError object.

NdbBlob::getNdbOperation()

Description

This method can be used to find the operation with which the handle for this NdbBlob is associated.

Signature

const NdbOperation* getNdbOperation
    (
      void
    ) const

Parameters

None.

Return value

A pointer to an operation.

The operation referenced by the pointer returned by this method may be represented by either an NdbOperation or NdbScanOperation object.

See Section 2.3.20, “The NdbOperation Class”, and Section 2.3.24, “The NdbScanOperation Class”, for more information.

NdbBlob::getPos()

Description

This method gets the current read/write position in a blob.

Signature

int getPos
    (
      Uint64& pos
    )

Parameters

One parameter, a reference to the position.

Return value

Returns 0 on success, or -1 on failure. (Following a successful invocation, pos will hold the current read/write position within the blob, as a number of bytes from the beginning.)

NdbBlob::getState()

Description

This method gets the current state of the NdbBlob object for which it is invoked. Possible states are described in NdbBlob::State.

Signature

State getState
    (
      void
    )

Parameters

None.

Return value

A value of type State.

NdbBlob::getValue()

Description

Use this method to prepare to read a blob value; the value is available following invocation. Use getNull() to check for a NULL value; use getLength() to get the actual length of the blob, and to check for truncation. getValue() sets the current read/write position to the point following the end of the data which was read.

Signature

int getValue
    (
      void*  data,
      Uint32 bytes
    )

Parameters

This method takes two parameters. The first of these is a pointer to the data to be read; the second is the number of bytes to be read.

Return value

0 on success, -1 on failure.

NdbBlob::getVersion()

Description

This method is used to distinguish whether a blob operation is statement-based or event-based.

Signature

void getVersion
    (
      int& version
    )

Parameters

This method takes a single parameter, an integer reference to the blob version (operation type).

Return value

One of the following three values:

-1: This is a “normal” (statement-based) blob.
0: This is an event-operation based blob, following a change in its data.
1: This is an event-operation based blob, prior to any change in its data.

getVersion() is always successful, assuming that it is invoked as a method of a valid instance of NdbBlob.

NdbBlob::readData()

Description

This method is used to read data from a blob.

Signature

int readData
    (
      void*     data,
      Uint32&  bytes
    )

Parameters

readData() accepts a pointer to the data to be read, and a reference to the number of bytes read.

Return value

Returns 0 on success, -1 on failure. Following a successful invocation, data points to the data that was read, and bytes holds the number of bytes read.

NdbBlob::setActiveHook()

Description

This method defines a callback for blob handle activation. The queue of prepared operations will be executed in no-commit mode up to this point; then, the callback is invoked. For additional information, see NdbBlob::ActiveHook.

Signature

int setActiveHook
    (
      ActiveHook*  activeHook,
      void*        arg
    )

Parameters

This method requires the two parameters listed here:

A pointer to an ActiveHook.
A pointer to void, for any data to be passed to the callback.

Return value

0 on success, -1 on failure.

NdbBlob::setNull()

Description

This method sets the value of a blob to NULL.

Signature

int setNull
    (
      void
    )

Parameters

None.

Return value

0 on success; -1 on failure.

NdbBlob::setPos()

Description

This method sets the position within the blob at which to read or write data.

Signature

int setPos
    (
      Uint64 pos
    )

Parameters

The setPos() method takes a single parameter pos (an unsigned 64-bit integer), which is the position for reading or writing data. The value of pos must be between 0 and the blob's current length.

Important

“Sparse” blobs are not supported in the NDB API; in other words, there can be no unused data positions within a blob.

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

NdbBlob::setValue()

Description

This method is used to prepare for inserting or updating a blob value. Any existing blob data that is longer than the new data is truncated. The data buffer must remain valid until the operation has been executed. setValue() sets the current read/write position to the point following the end of the data. You can set data to a null pointer (0) in order to create a NULL value.

Signature

int setValue
    (
      const void*  data,
      Uint32       bytes
    )

Parameters

This method takes the two parameters listed here:

The data that is to be inserted or used to overwrite the blob value.
The number of bytes—that is, the length—of the data.

Return value

0 on success, -1 on failure.

NdbBlob::State

This is an enumerated data type which represents the possible states of an NdbBlob instance.

Description

An NdbBlob may assume any one of these states

Enumeration values

Possible values are shown, along with descriptions, in the following table:

Table 2.36 NdbBlob::State type values and descriptions

Name	Description
`Idle`	The `NdbBlob` has not yet been prepared for use with any operations.
`Prepared`	This is the state of the `NdbBlob` prior to operation execution.
`Active`	This is the blob handle's state following execution or the fetching of the next result, but before the transaction is committed.
`Closed`	This state occurs after the transaction has been committed.
`Invalid`	This follows a rollback or the close of a transaction.

NdbBlob::truncate()

Description

This method is used to truncate a blob to a given length.

Signature

int truncate
    (
      Uint64 length = 0
    )

Parameters

truncate() takes a single parameter which specifies the new length to which the blob is to be truncated. This method has no effect if length is greater than the blob's current length (which you can check using getLength()).

Return value

0 on success, -1 on failure.

NdbBlob::writeData()

Description

This method is used to write data to an NdbBlob. After a successful invocation, the read/write position will be at the first byte following the data that was written to the blob.

A write past the current end of the blob data extends the blob automatically.

Signature

int writeData
    (
      const void*  data,
      Uint32       bytes
    )

Parameters

This method takes two parameters, a pointer to the data to be written, and the number of bytes to write.

Return value

0 on success, -1 on failure.

2.3.13 The NdbBlob Class

NdbBlob Class Overview

NdbBlob::ActiveHook

NdbBlob::blobsFirstBlob()

NdbBlob::blobsNextBlob()

NdbBlob::close()

NdbBlob::getBlobEventName()

NdbBlob::getBlobTableName()

NdbBlob::getColumn()

NdbBlob::getLength()

NdbBlob::getNull()

NdbBlob::getNdbError()

NdbBlob::getNdbOperation()

NdbBlob::getPos()

NdbBlob::getState()

NdbBlob::getValue()

NdbBlob::getVersion()

NdbBlob::readData()

NdbBlob::setActiveHook()

NdbBlob::setNull()

NdbBlob::setPos()

NdbBlob::setValue()

NdbBlob::State

NdbBlob::truncate()

NdbBlob::writeData()