NdbBlob Class Reference
#include <NdbBlob.hpp>
List of all members.
Detailed Description
Blob handle.
Blob data is stored in 2 places:
- "header" and "inline bytes" stored in the blob attribute
- "blob parts" stored in a separate table NDB$BLOB_<tid>_<cid>
Inline and part sizes can be set via NdbDictionary::Column methods when the table is created.
NdbBlob is a blob handle. To access blob data, the handle must be created using NdbOperation::getBlobHandle in operation prepare phase. The handle has following states:
- prepared: before the operation is executed
- active: after execute or next result but before transaction commit
- closed: after transaction commit
- invalid: after rollback or transaction close
NdbBlob supports 3 styles of data access:
- in prepare phase, NdbBlob methods getValue and setValue are used to prepare a read or write of a blob value of known size
- in prepare phase, setActiveHook is used to define a routine which is invoked as soon as the handle becomes active
- in active phase, readData and writeData are used to read or write blob data of arbitrary size
The styles can be applied in combination (in above order).
Blob operations take effect at next transaction execute. In some cases NdbBlob is forced to do implicit executes. To avoid this, operate on complete blob parts.
Use NdbTransaction::executePendingBlobOps to flush your reads and writes. It avoids execute penalty if nothing is pending. It is not needed after execute (obviously) or after next scan result.
NdbBlob methods return -1 on error and 0 on success, and use output parameters when necessary.
Operation types:
- insertTuple must use setValue if blob column is non-nullable
- readTuple with exclusive lock can also update existing value
- updateTuple can overwrite with setValue or update existing value
- writeTuple always overwrites and must use setValue if non-nullable
- deleteTuple creates implicit non-accessible blob handles
- scan with exclusive lock can also update existing value
- scan "lock takeover" update op must do its own getBlobHandle
Bugs / limitations:
- lock mode upgrade should be handled automatically
- lock mode vs allowed operation is not checked
- too many pending blob ops can blow up i/o buffers
- table and its blob part tables are not created atomically
Public Types
- typedef int ActiveHook (NdbBlob *me, void *arg)
- enum State {
Idle = 0,
Prepared = 1,
Active = 2,
Closed = 3,
Invalid = 9
}
Public Member Functions
Static Public Member Functions
Member Typedef Documentation
|
Callback for setActiveHook(). Invoked immediately when the prepared operation has been executed (but not committed). Any getValue() or setValue() is done first. The blob handle is active so readData or writeData() etc can be used to manipulate blob value. A user-defined argument is passed along. Returns non-zero on error. |
Member Enumeration Documentation
Member Function Documentation
NdbBlob* NdbBlob::blobsFirstBlob |
( |
|
) |
|
|
|
Return info about all blobs in this operation.
Get first blob in list. |
NdbBlob* NdbBlob::blobsNextBlob |
( |
|
) |
|
|
|
Return info about all blobs in this operation.
Get next blob in list. Initialize with blobsFirstBlob(). |
int NdbBlob::getBlobTableName |
( |
char * |
btname, |
|
|
Ndb * |
anNdb, |
|
|
const char * |
tableName, |
|
|
const char * |
columnName |
|
) |
[static] |
|
|
Get blob parts table name. Useful only to test programs. |
int NdbBlob::getLength |
( |
Uint64 & |
length |
) |
|
|
|
Get current length in bytes. Use getNull to distinguish between length 0 blob and NULL blob. |
const NdbError& NdbBlob::getNdbError |
( |
|
) |
const |
|
|
Return error object. The error may be blob specific (below) or may be copied from a failed implicit operation. |
int NdbBlob::getNull |
( |
bool & |
isNull |
) |
|
|
int NdbBlob::getPos |
( |
Uint64 & |
pos |
) |
|
|
|
Get current read/write position. |
State NdbBlob::getState |
( |
|
) |
|
|
|
Get the state of a NdbBlob object. |
int NdbBlob::getValue |
( |
void * |
data, |
|
|
Uint32 |
bytes |
|
) |
|
|
|
Prepare to read blob value. The value is available after execute. Use getNull() to check for NULL and getLength() to get the real length and to check for truncation. Sets current read/write position to after the data read. |
int NdbBlob::readData |
( |
void * |
data, |
|
|
Uint32 & |
bytes |
|
) |
|
|
|
Read at current position and set new position to first byte after the data read. A read past blob end returns actual number of bytes read in the in/out bytes parameter. |
int NdbBlob::setActiveHook |
( |
ActiveHook * |
activeHook, |
|
|
void * |
arg |
|
) |
|
|
|
Define callback for blob handle activation. The queue of prepared operations will be executed in no commit mode up to this point and then the callback is invoked. |
int NdbBlob::setPos |
( |
Uint64 |
pos |
) |
|
|
|
Set read/write position. Must be between 0 and current length. "Sparse blobs" are not supported. |
int NdbBlob::setValue |
( |
const void * |
data, |
|
|
Uint32 |
bytes |
|
) |
|
|
|
Prepare to insert or update blob value. An existing longer blob value will be truncated. The data buffer must remain valid until execute. Sets current read/write position to after the data. Set data to null pointer (0) to create a NULL value. |
int NdbBlob::truncate |
( |
Uint64 |
length = 0 |
) |
|
|
|
Truncate blob to given length. Has no effect if the length is larger than current length. |
int NdbBlob::writeData |
( |
const void * |
data, |
|
|
Uint32 |
bytes |
|
) |
|
|
|
Write at current position and set new position to first byte after the data written. A write past blob end extends the blob value. |
Documentation generated Mon May 2 18:33:48 2005 from mysql source files.
© 2003-2004
MySQL AB