Skip navigation links
2.3.9.1 NdbBlob Types »
Section Navigation      [Toggle]

2.3.9. The NdbBlob Class

[+/-]

2.3.9.1. NdbBlob Types
2.3.9.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.15, “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 NdbDictionary::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:

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

These data access types can be applied in combination, provided that they are used in the order given above.

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, and use NdbTransaction::executePendingBlobOps() to flush reads and writes. There is no penalty for doing this if nothing is pending. It is not necessary to do so following execution (obviously) or after next scan result is obtained. 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.11, “The NdbEventOperation Class”.)

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.

See Section 2.3.15, “The NdbOperation Class”.

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
getState() Gets the state of an NdbBlob object
getValue() Prepares to read a blob value
setValue() Prepares to insert or update a blob value
setActiveHook() Defines a callback for blob handle activation
getVersion() Checks whether a blob is statement-based or event-based
getNull() Checks whether a blob value is NULL
setNull() Sets a blob to NULL
getLength() Gets the length of a blob, in bytes
truncate() Truncates a blob to a given length
getPos() Gets the current position for reading/writing
setPos() Sets the position at which to begin reading/writing
readData() Reads data from a blob
writeData() Writes blob data
getColumn() Gets a blob column.
getNdbError() Gets an error (an NdbError object)
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.
getNdbOperation() Get a pointer to the operation (NdbOperation object) to which this NdbBlob object belonged when created.

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