This section provides information about theNdbBlob class, which models 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
This class has no public constructor. An instance of
NdbBlobis created using theNdbOperation::getBlobHandle()method during the operation preparation phase. (SeeSection 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 NdbErrorobject)getNdbOperation()Get a pointer to the operation ( NdbOperationobject) to which thisNdbBlobobject belonged when created.getNull()Checks whether a blob value is NULLgetPos()Gets the current position for reading/writing getState()Gets the state of an NdbBlobobjectgetValue()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 NULLsetPos()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()andgetBlobEventName()are static methods.Most
NdbBlobmethods (nearly all of those whose return type isint) return0on success and-1in the event of failure.- Types
The public types defined by
NdbBlobare 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_, wheretid_cidtidis the table ID, andcidis the blob column ID.
The inline and data segment sizes can be set using the appropriateColumn methods when the table is created. SeeSection 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
NdbBlobmethodsgetValue()andsetValue()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()andwriteData()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.
UseNdbTransaction::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. (SeeSection 2.3.16, “The NdbEventOperation Class”, for more information.)
Blobs and NdbOperations. NdbOperation methods acting onNdbBlob objects have the following characteristics:.
NdbOperation::insertTuple()must useNdbBlob::setValue()if the blob attribute is nonnullable.NdbOperation::readTuple()used with any lock mode can read but not write blob values.When the
LM_CommittedReadlock mode is used withreadTuple(), the lock mode is automatically upgraded toLM_Readwhenever blob attributes are accessed.NdbOperation::updateTuple()can either overwrite an existing value usingNdbBlob::setValue(), or update it during the active phase.NdbOperation::writeTuple()always overwrites blob values, and must useNdbBlob::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_Exclusivelock mode can update row and blob values usingupdateCurrentTuple(); the operation returned must explicitly create its own blob handle.A scan using the
LM_Exclusivelock mode can delete row values (and therefore blob values) usingdeleteCurrentTuple(); 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 withNdbBlob objects:
Too many pending blob operations can overflow the I/O buffers.
The table and its blob data segment tables are not created atomically.
ActiveHook is a data type defined for use as a callback for thesetActiveHook() method. (SeeNdbBlob::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 togetValue()orsetValue()are performed first. The blob handle is active soreadData()orwriteData()can be used to manipulate the blob value. A user-defined argument is passed along with theNdbBlob.setActiveHook()returns a nonzero value in the event of an error.
- 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.
- Description
Use the method to obtain the next in a list of blobs that was initialised using
blobsFirstBlob(). SeeNdbBlob::blobsFirstBlob().- Signature
NdbBlob* blobsNextBlob ( void )- Parameters
None.
- Return value
A pointer to the desired blob.
- 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
StateisActive.- Signature
int close ( boolexecPendingBlobOps = true )- Parameters
This method has a single boolean parameter
execPendingBlobOps. If the value of this parametertrue(the default), any pending blob operations are flushed before the blob handle is closed. IfexecPendingBlobOpsisfalse, 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 usingLM_Read orLM_Exclusive as theLockMode, 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 modeLM_CommittedRead, the mode is automatically upgraded toLM_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 theclose() method, which adds a pending write operation to the blob. The upgraded lock is released following the call toexecute().
- 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 relevantNdbobject.event: The name of the main event.column: The blob column.
- Return value
0on success,-1on failure.
- 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 relevantNdbobject.table: The name of the main table.column: The blob column.
- Return value
Returns
0on success,-1on failure.
- 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
NULLblob, this method returns0. to distinguish between a blob whose length is0blob and one which isNULL, use thegetNull()method.
- 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 isNULL.
- Return value
None.
- 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
NdbErrorobject.
- Description
This method can be used to find the operation with which the handle for this
NdbBlobis 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
NdbOperationorNdbScanOperationobject.SeeSection 2.3.20, “The NdbOperation Class”, andSection 2.3.24, “The NdbScanOperation Class”, for more information.
- 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
0on success, or-1on failure. (Following a successful invocation,poswill hold the current read/write position within the blob, as a number of bytes from the beginning.)
- Description
This method gets the current state of the
NdbBlobobject for which it is invoked. Possible states are described inNdbBlob::State.- Signature
State getState ( void )- Parameters
None.
- Return value
A value of type
State.
- Description
Use this method to prepare to read a blob value; the value is available following invocation. Use
getNull()to check for aNULLvalue; usegetLength()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, Uint32bytes )- Parameters
This method takes two parameters. The first of these is a pointer to the
datato be read; the second is the number ofbytesto be read.- Return value
0on success,-1on failure.
- 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 ofNdbBlob.
- Description
This method is used to read data from a blob.
- Signature
int readData ( void*data, Uint32&bytes )- Parameters
readData()accepts a pointer to thedatato be read, and a reference to the number ofbytesread.- Return value
Returns
0on success,-1on failure. Following a successful invocation,datapoints to the data that was read, andbytesholds the number of bytes read.
- 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, seeNdbBlob::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
0on success,-1on failure.
- Description
This method sets the value of a blob to
NULL.- Signature
int setNull ( void )- Parameters
None.
- Return value
0on success;-1on failure.
- Description
This method sets the position within the blob at which to read or write data.
- Signature
int setPos ( Uint64pos )- 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 ofposmust be between0and the blob's current length.
“Sparse” blobs are not supported in the NDB API; in other words, there can be no unused data positions within a blob.
- Return value
0on success,-1on failure.
- 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 setdatato a null pointer (0) in order to create aNULLvalue.- Signature
int setValue ( const void*data, Uint32bytes )- Parameters
This method takes the two parameters listed here:
The
datathat is to be inserted or used to overwrite the blob value.The number of
bytes—that is, the length—of thedata.
- Return value
0on success,-1on failure.
This is an enumerated data type which represents the possible states of anNdbBlob instance.
- Description
An
NdbBlobmay 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 IdleThe NdbBlobhas not yet been prepared for use with any operations.PreparedThis is the state of the NdbBlobprior to operation execution.ActiveThis is the blob handle's state following execution or the fetching of the next result, but before the transaction is committed. ClosedThis state occurs after the transaction has been committed. InvalidThis follows a rollback or the close of a transaction.
- Description
This method is used to truncate a blob to a given length.
- Signature
int truncate ( Uint64length = 0 )- Parameters
truncate()takes a single parameter which specifies the newlengthto which the blob is to be truncated. This method has no effect iflengthis greater than the blob's current length (which you can check usinggetLength()).- Return value
0on success,-1on failure.
- 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, Uint32bytes )- Parameters
This method takes two parameters, a pointer to the
datato be written, and the number ofbytesto write.- Return value
0on success,-1on failure.