Blob handle. More...

#include <NdbBlob.hpp>

Classes
struct	Buf
struct	Head

Public Types
enum	State { Idle = 0, Prepared = 1, Active = 2, Closed = 3, Invalid = 9 }
typedef int	ActiveHook (NdbBlob me, void arg)

Public Member Functions
State	getState ()
void	getVersion (int &version)
int	getValue (void *data, Uint32 bytes)
int	setValue (const void *data, Uint32 bytes)
int	setActiveHook (ActiveHook activeHook, void arg)
int	getDefined (int &isNull)
int	getNull (bool &isNull)
int	getNull (int &isNull)
int	setNull ()
int	getLength (Uint64 &length)
int	truncate (Uint64 length=0)
int	getPos (Uint64 &pos)
int	setPos (Uint64 pos)
int	readData (void *data, Uint32 &bytes)
int	writeData (const void *data, Uint32 bytes)
const NdbDictionary::Column *	getColumn ()
const NdbError &	getNdbError () const
const NdbOperation *	getNdbOperation () const
NdbBlob *	blobsFirstBlob ()
NdbBlob *	blobsNextBlob ()
int	close (bool execPendingBlobOps=true)

Static Public Member Functions
static void	packBlobHead (const Head &head, char *buf, int blobVersion)
static void	unpackBlobHead (Head &head, const char *buf, int blobVersion)
static int	getBlobTableName (char btname, Ndb anNdb, const char tableName, const char columnName)
static int	getBlobEventName (char bename, Ndb anNdb, const char eventName, const char columnName)

Friends
class	Ndb
class	NdbTransaction
class	NdbOperation
class	NdbScanOperation
class	NdbDictionaryImpl
class	NdbResultSet
class	NdbEventBuffer
class	NdbEventOperationImpl
class	NdbReceiver
struct	Ndb_free_list_t< NdbBlob >

Detailed Description

Blob handle.

there is no support for an asynchronous interface

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 blob handle is closed or 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 also supports reading post or pre blob data from events. The handle can be read after next event on main table has been retrieved. The data is available immediately. See NdbEventOperation.

Non-void NdbBlob methods return -1 on error and 0 on success. Output parameters are used when necessary.

Usage notes for different operation types:

insertTuple must be followed by a setValue() call for every non nullable blob in the row.

readTuple or scan readTuples with lock mode LM_CommittedRead is temporarily upgraded to lock mode LM_Read if any blob attributes are accessed (to guarantee consistent view). After the Blob handle is closed, the LM_Read lock is removed on the next execute() call.

readTuple (with any lock mode) can only read blob value

updateTuple can either overwrite existing value with setValue or update it in active phase

writeTuple always overwrites blob value and must use setValue if blob attribute is non-nullable

deleteTuple creates implicit non-accessible blob handles

scan readTuples (any lock mode) can use its blob handles only to read blob value

scan readTuples with lock mode LM_Exclusive can update row and blob value using updateCurrentTuple, where the operation returned must create its own blob handles explicitly

scan readTuples with lock mode LM_Exclusive can delete row (and therefore blob values) using deleteCurrentTuple, which creates implicit non-accessible blob handles

the operation returned by lockCurrentTuple cannot update blob value

Bugs / limitations:

too many pending blob ops can blow up i/o buffers

table and its blob part tables are not created atomically

Definition at line 129 of file NdbBlob.hpp.

Member Typedef Documentation

typedef int NdbBlob::ActiveHook(NdbBlob *me, void *arg)

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.

Definition at line 198 of file NdbBlob.hpp.

Member Enumeration Documentation

enum NdbBlob::State

State.

Definition at line 134 of file NdbBlob.hpp.

Member Function Documentation

NdbBlob * NdbBlob::blobsFirstBlob ( )

Return info about all blobs in this operation.

Get first blob in list.

Definition at line 3322 of file NdbBlob.cpp.

NdbBlob * NdbBlob::blobsNextBlob ( )

Return info about all blobs in this operation.

Get next blob in list. Initialize with blobsFirstBlob().

Definition at line 3328 of file NdbBlob.cpp.

int NdbBlob::close ( bool execPendingBlobOps = true )

Close the BlobHandle

The BlobHandle can be closed to release internal resources before transaction commit / abort time.

The close method can only be called when the Blob is in Active state.

If execPendingBlobOps = true then pending Blob operations will be flushed before the Blob handle is closed. If execPendingBlobOps = false then the Blob handle must have no pending read or write operations.

Read operations and locks

Where a Blob handle is created on a read operation using lockmode LM_Read or LM_Exclusive, the read operation can only be unlocked after all Blob handles created on the operation are closed.

Where a row containing Blobs has been read with lockmode LM_CommittedRead, the lockmode is automatically upgraded to LM_Read to ensure consistency. In this case, when all the BlobHandles for the row have been close()d, an unlock operation for the row is automatically issued by the close() call, adding a pending 'write' operation to the Blob. After the next execute() call, the upgraded lock is released.

Definition at line 3340 of file NdbBlob.cpp.

int NdbBlob::getBlobEventName	(	char *	bename,
		Ndb *	anNdb,
		const char *	eventName,
		const char *	columnName
	)

static

Get blob event name. The blob event is created if the main event monitors the blob column. The name includes main event name.

Definition at line 230 of file NdbBlob.cpp.

int NdbBlob::getBlobTableName	(	char *	btname,
		Ndb *	anNdb,
		const char *	tableName,
		const char *	columnName
	)

static

Get blob parts table name. Useful only to test programs.

Definition at line 57 of file NdbBlob.cpp.

const NdbDictionary::Column * NdbBlob::getColumn ( )

Return the blob column.

Definition at line 3267 of file NdbBlob.cpp.

int NdbBlob::getLength ( Uint64 & length )

Get current length in bytes. Use getNull to distinguish between length 0 blob and NULL blob.

Definition at line 1306 of file NdbBlob.cpp.

const NdbError & NdbBlob::getNdbError ( ) const

Return 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 non-zero error code.

Definition at line 66 of file Ndberr.cpp.

const NdbOperation * NdbBlob::getNdbOperation ( ) const

Get a pointer to the operation which this Blob Handle was initially created as part of. Note that this could be a scan operation. Note that the pointer returned is a const pointer.

Definition at line 3334 of file NdbBlob.cpp.

int NdbBlob::getNull ( int & isNull )

Return -1, 0, 1 if blob is undefined, non-null, or null. For non-event blob, undefined causes a state error.

Definition at line 1264 of file NdbBlob.cpp.

int NdbBlob::getPos ( Uint64 & pos )

Get current read/write position.

Definition at line 1375 of file NdbBlob.cpp.

NdbBlob::State NdbBlob::getState ( )

Get the state of a NdbBlob object.

Definition at line 32 of file NdbBlob.cpp.

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.

Definition at line 1147 of file NdbBlob.cpp.

void NdbBlob::getVersion ( int & version )

Returns -1 for normal statement based blob and 0/1 for event operation post/pre data blob. Always succeeds.

Definition at line 38 of file NdbBlob.cpp.

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.

Definition at line 1406 of file NdbBlob.cpp.

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.

Definition at line 1220 of file NdbBlob.cpp.

int NdbBlob::setNull ( )

Set blob to NULL.

Definition at line 1281 of file NdbBlob.cpp.

Here is the call graph for this function:

int NdbBlob::setPos ( Uint64 pos )

Set read/write position. Must be between 0 and current length. "Sparse blobs" are not supported.

Definition at line 1387 of file NdbBlob.cpp.

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.

Definition at line 1170 of file NdbBlob.cpp.

Here is the caller graph for this function:

int NdbBlob::truncate ( Uint64 length = 0 )

Truncate blob to given length. Has no effect if the length is larger than current length.

Definition at line 1322 of file NdbBlob.cpp.

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.

Definition at line 1531 of file NdbBlob.cpp.

Friends And Related Function Documentation

friend class Ndb

friend

Reciver(s)

Definition at line 322 of file NdbBlob.hpp.

friend class NdbOperation

friend

Sender(s)

Definition at line 324 of file NdbBlob.hpp.

The documentation for this class was generated from the following files:

storage/ndb/include/ndbapi/NdbBlob.hpp
storage/ndb/src/ndbapi/NdbBlob.cpp
storage/ndb/src/ndbapi/Ndberr.cpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Member Function Documentation

Friends And Related Function Documentation