MySQL :: MySQL Cluster API Developer Guide

MySQL Cluster API Developer Guide :: 2 The NDB API :: 2.3 NDB API Classes, Interfaces, and Structures :: 2.3.15 The NdbBlob Class

« 2.3.14.1 Ndb_cluster_connection Methods

2.3.15.1 NdbBlob Types »

Section Navigation [Toggle]

2.3.15. The `NdbBlob` Class

[+/-]

2.3.15.1. NdbBlob Types
2.3.15.2. NdbBlob Methods

Abstract

This class represents a handle to a BLOB column and provides read and write access to BLOB column values. This object has a number of different states and provides several modes of access to BLOB data; these are also described in this section.

Parent class. None

Child classes. None

Description. An instance of NdbBlob is created using the NdbOperation::getBlobHandle() method during the operation preparation phase. (See Section 2.3.22, “The NdbOperation Class”.) This object acts as a handle on a BLOB column.

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

The header and inline bytes are stored in the blob attribute.
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.2, “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. 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.18, “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.

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

Method	Purpose / Use
`blobsFirstBlob()`	Gets the first blob in a list.
`blobsNextBlob()`	Gets the next blob in a list
`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

Note

getBlobTableName() and getBlobEventName() are static methods.

Tip

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

For detailed descriptions, signatures, and examples of use for each of these methods, see Section 2.3.15.2, “NdbBlob Methods”.

Types. The public types defined by NdbBlob are shown here:

Type	Purpose / Use
`ActiveHook()`	Callback for `NdbBlob::setActiveHook()`
`State()`	Represents the states that may be assumed by the `NdbBlob`.

For a discussion of each of these types, along with its possible values, see Section 2.3.15.1, “NdbBlob Types”.

Class diagram. This diagram shows all the available methods and types of the NdbBlob class:

Public methods and types of the
NdbBlob class.

Top / Previous / Next / Up / Table of Contents

2.3.15. The NdbBlob Class

2.3.15. The `NdbBlob` Class