MySQL NDB Cluster API Developer Guide
This section provides information about the
NdbBlob
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.
None
None
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.
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.
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_
,
where tid
_cid
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.
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
)
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.
This method initialises a list of blobs belonging to the current operation and returns the first blob in the list.
NdbBlob* blobsFirstBlob ( void )
None.
A pointer to the desired blob.
Use the method to obtain the next in a list of blobs that
was initialised using blobsFirstBlob()
.
See NdbBlob::blobsFirstBlob().
NdbBlob* blobsNextBlob ( void )
None.
A pointer to the desired blob.
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
.
int close
(
bool execPendingBlobOps
= true
)
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.
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()
.
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.
static int getBlobEventName ( char*name
, Ndb*ndb
, const char*event
, const char*column
)
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.
0
on success, -1
on
failure.
This method gets the blob data segment table name.
This method is generally of use only for testing and debugging purposes.
static int getBlobTableName ( char*name
, Ndb*ndb
, const char*table
, const char*column
)
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.
Returns 0
on success,
-1
on failure.
This method gets the blob's current length in bytes.
int getLength
(
Uint64& length
)
A reference to the length.
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.
This method checks whether the blob's value is
NULL
.
int getNull
(
int& isNull
)
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
.
None.
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.
const NdbError& getNdbError ( void ) const
None.
An NdbError
object.
This method can be used to find the operation with which the
handle for this NdbBlob
is
associated.
const NdbOperation* getNdbOperation ( void ) const
None.
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.
This method gets the current read/write position in a blob.
int getPos
(
Uint64& pos
)
One parameter, a reference to the position.
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.)
This method gets the current state of the
NdbBlob
object for which it
is invoked. Possible states are described in
NdbBlob::State.
State getState ( void )
None.
A value of type
State
.
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.
int getValue ( void*data
, Uint32bytes
)
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.
0
on success, -1
on
failure.
This method is used to distinguish whether a blob operation is statement-based or event-based.
void getVersion
(
int& version
)
This method takes a single parameter, an integer reference to the blob version (operation type).
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
.
This method is used to read data from a blob.
int readData ( void*data
, Uint32&bytes
)
readData()
accepts a pointer to the
data
to be read, and a reference
to the number of bytes
read.
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.
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.
int setActiveHook ( ActiveHook*activeHook
, void*arg
)
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.
0
on success, -1
on
failure.
This method sets the value of a blob to
NULL
.
int setNull ( void )
None.
0
on success; -1
on
failure.
This method sets the position within the blob at which to read or write data.
int setPos
(
Uint64 pos
)
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.
“Sparse” blobs are not supported in the NDB API; in other words, there can be no unused data positions within a blob.
0
on success, -1
on
failure.
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.
int setValue ( const void*data
, Uint32bytes
)
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
.
0
on success, -1
on
failure.
This is an enumerated data type which represents the possible
states of an NdbBlob
instance.
An NdbBlob
may assume any
one of these states
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. |
This method is used to truncate a blob to a given length.
int truncate
(
Uint64 length
= 0
)
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()
).
0
on success, -1
on
failure.
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.
int writeData ( const void*data
, Uint32bytes
)
This method takes two parameters, a pointer to the
data
to be written, and the
number of bytes
to write.
0
on success, -1
on
failure.