Represents a transaction. More...

#include <NdbTransaction.hpp>

Public Types
enum	ExecType { NoExecTypeDef, Prepare = ::Prepare, NoCommit, Commit, Rollback = ::Rollback }

Public Member Functions
Ndb *	getNdb ()
NdbOperation *	getNdbOperation (const char *aTableName)
NdbOperation *	getNdbOperation (const NdbDictionary::Table *aTable)
NdbScanOperation *	getNdbScanOperation (const char *aTableName)
NdbScanOperation *	getNdbScanOperation (const NdbDictionary::Table *aTable)
NdbIndexScanOperation *	getNdbIndexScanOperation (const char anIndexName, const char aTableName)
NdbIndexScanOperation *	getNdbIndexScanOperation (const NdbDictionary::Index anIndex, const NdbDictionary::Table aTable)
NdbIndexScanOperation *	getNdbIndexScanOperation (const NdbDictionary::Index *anIndex)
NdbIndexOperation *	getNdbIndexOperation (const char anIndexName, const char aTableName)
NdbIndexOperation *	getNdbIndexOperation (const NdbDictionary::Index anIndex, const NdbDictionary::Table aTable)
NdbIndexOperation *	getNdbIndexOperation (const NdbDictionary::Index *anIndex)
int	executePendingBlobOps (Uint8 flags=0xFF)
Uint32	getConnectedNodeId ()
const NdbOperation *	readTuple (const NdbRecord key_rec, const char key_row, const NdbRecord result_rec, char result_row, NdbOperation::LockMode lock_mode=NdbOperation::LM_Read, const unsigned char result_mask=0, const NdbOperation::OperationOptions opts=0, Uint32 sizeOfOptions=0)
const NdbOperation *	insertTuple (const NdbRecord key_rec, const char key_row, const NdbRecord attr_rec, const char attr_row, const unsigned char mask=0, const NdbOperation::OperationOptions opts=0, Uint32 sizeOfOptions=0)
const NdbOperation *	insertTuple (const NdbRecord combined_rec, const char combined_row, const unsigned char mask=0, const NdbOperation::OperationOptions opts=0, Uint32 sizeOfOptions=0)
const NdbOperation *	updateTuple (const NdbRecord key_rec, const char key_row, const NdbRecord attr_rec, const char attr_row, const unsigned char mask=0, const NdbOperation::OperationOptions opts=0, Uint32 sizeOfOptions=0)
const NdbOperation *	writeTuple (const NdbRecord key_rec, const char key_row, const NdbRecord attr_rec, const char attr_row, const unsigned char mask=0, const NdbOperation::OperationOptions opts=0, Uint32 sizeOfOptions=0)
const NdbOperation *	deleteTuple (const NdbRecord key_rec, const char key_row, const NdbRecord result_rec, char result_row=0, const unsigned char result_mask=0, const NdbOperation::OperationOptions opts=0, Uint32 sizeOfOptions=0)
const NdbOperation *	refreshTuple (const NdbRecord key_rec, const char key_row, const NdbOperation::OperationOptions *opts=0, Uint32 sizeOfOptions=0)
NdbScanOperation *	scanTable (const NdbRecord result_record, NdbOperation::LockMode lock_mode=NdbOperation::LM_Read, const unsigned char result_mask=0, const NdbScanOperation::ScanOptions *options=0, Uint32 sizeOfOptions=0)
NdbIndexScanOperation *	scanIndex (const NdbRecord key_record, const NdbRecord result_record, NdbOperation::LockMode lock_mode=NdbOperation::LM_Read, const unsigned char result_mask=0, const NdbIndexScanOperation::IndexBound bound=0, const NdbScanOperation::ScanOptions *options=0, Uint32 sizeOfOptions=0)
NdbQuery *	createQuery (const NdbQueryDef *query, const NdbQueryParamValue paramValue[]=0, NdbOperation::LockMode lock_mode=NdbOperation::LM_Read)
const NdbOperation *	unlock (const NdbLockHandle *lockHandle, NdbOperation::AbortOption ao=NdbOperation::DefaultAbortOption)
int	releaseLockHandle (const NdbLockHandle *lockHandle)
Uint32	getMaxPendingBlobReadBytes () const
Uint32	getMaxPendingBlobWriteBytes () const
void	setMaxPendingBlobReadBytes (Uint32 bytes)
void	setMaxPendingBlobWriteBytes (Uint32 bytes)
Execute Transaction
int	execute (ExecType execType, NdbOperation::AbortOption=NdbOperation::DefaultAbortOption, int force=0)
int	execute (::ExecType execType,::AbortOption abortOption=::DefaultAbortOption, int force=0)
void	executeAsynchPrepare (ExecType execType, NdbAsynchCallback callback, void *anyObject, NdbOperation::AbortOption=NdbOperation::DefaultAbortOption)
void	executeAsynchPrepare (::ExecType execType, NdbAsynchCallback callback, void *anyObject,::AbortOption ao=::DefaultAbortOption)
void	executeAsynch (ExecType aTypeOfExec, NdbAsynchCallback aCallback, void *anyObject, NdbOperation::AbortOption=NdbOperation::DefaultAbortOption, int forceSend=0)
void	executeAsynch (::ExecType aTypeOfExec, NdbAsynchCallback aCallback, void *anyObject,::AbortOption abortOption=::DefaultAbortOption, int forceSend=0)
int	refresh ()
void	close ()
int	restart ()
Error Handling
const NdbError &	getNdbError () const
NdbOperation *	getNdbErrorOperation ()
const NdbOperation *	getNdbErrorOperation () const
int	getNdbErrorLine ()
const NdbOperation *	getNextCompletedOperation (const NdbOperation *op) const
const NdbOperation *	getFirstDefinedOperation () const
const NdbOperation *	getLastDefinedOperation () const

Friends
class	Ndb
class	NdbOperation
class	NdbScanOperation
class	NdbIndexOperation
class	NdbIndexScanOperation
class	NdbBlob
class	ha_ndbcluster
class	NdbQueryImpl
class	NdbQueryOperationImpl
class	HugoOperations
struct	Ndb_free_list_t< NdbTransaction >

Meta Information
enum	CommitStatusType { NotStarted, Started, Committed, Aborted, NeedAbort }
int	getGCI (Uint64 *gciptr)
int	getGCI ()
Uint64	getTransactionId ()
CommitStatusType	commitStatus ()

Detailed Description

Represents a transaction.

A transaction (represented by an NdbTransaction object) belongs to an Ndb object and is created using Ndb::startTransaction(). A transaction consists of a list of operations (represented by NdbOperation, NdbScanOperation, NdbIndexOperation, and NdbIndexScanOperation objects). Each operation access exactly one table.

After getting the NdbTransaction object, the first step is to get (allocate) an operation given the table name using one of the methods getNdbOperation(), getNdbScanOperation(), getNdbIndexOperation(), or getNdbIndexScanOperation(). Then the operation is defined. Several operations can be defined on the same NdbTransaction object, they will in that case be executed in parallell. When all operations are defined, the execute() method sends them to the NDB kernel for execution.

The execute() method returns when the NDB kernel has completed execution of all operations defined before the call to execute(). All allocated operations should be properly defined before calling execute().

A call to execute() uses one out of three types of execution:

NdbTransaction::NoCommit Executes operations without committing them.
NdbTransaction::Commit Executes remaining operation and commits the complete transaction
NdbTransaction::Rollback Rollbacks the entire transaction.

execute() is equipped with an extra error handling parameter. There are two alternatives:

NdbTransaction::AbortOnError (default). The transaction is aborted if there are any error during the execution
NdbTransaction::AO_IgnoreError Continue execution of transaction even if operation fails

Definition at line 145 of file NdbTransaction.hpp.

Member Enumeration Documentation

enum NdbTransaction::CommitStatusType

The commit status of the transaction.

Enumerator:

NotStarted	Transaction not yet started.
Started	Missing explanation
Committed	Transaction has been committed.
Aborted	Transaction has been aborted.
NeedAbort	Missing explanation

Definition at line 573 of file NdbTransaction.hpp.

enum NdbTransaction::ExecType

Execution type of transaction

Enumerator:

NoExecTypeDef	Erroneous type (Used for debugging only)
Prepare	Missing explanation
NoCommit	Execute the transaction as far as it has been defined, but do not yet commit it
Commit	Execute and try to commit the transaction.
Rollback	Rollback transaction.

Definition at line 175 of file NdbTransaction.hpp.

Member Function Documentation

void NdbTransaction::close ( void )

Close transaction

Note: Equivalent to to calling Ndb::closeTransaction(); It is not allowed to call NdbTransaction::close after sending the transaction asynchronously before the callback method has been called. (The application should keep track of the number of outstanding transactions and wait until all of them has completed before calling NdbTransaction::close). If the transaction is not committed it will be aborted.

Definition at line 961 of file NdbTransaction.cpp.

Here is the call graph for this function:

NdbTransaction::CommitStatusType NdbTransaction::commitStatus ( )

Get the commit status of the transaction.

Returns: The commit status of the transaction

Definition at line 2411 of file NdbTransaction.cpp.

NdbQuery * NdbTransaction::createQuery	(	const NdbQueryDef *	query,
		const NdbQueryParamValue	paramValue[] = `0`,
		NdbOperation::LockMode	lock_mode = `NdbOperation::LM_Read`
	)

Add a prepared NdbQueryDef to transaction for execution.

If the NdbQueryDef contains parameters, (built with NdbQueryBilder::paramValue()) the value of these parameters are specified in the 'paramValue' array. Parameter values Should be supplied in the same order as the related paramValue's was defined.

Definition at line 3030 of file NdbTransaction.cpp.

Here is the call graph for this function:

int NdbTransaction::execute	(	ExecType	execType,
		NdbOperation::AbortOption	abortOption = `NdbOperation::DefaultAbortOption`,
		int	force = `0`
	)

Executes transaction.

Parameters

execType	Execution type: ExecType::NoCommit executes operations without committing them. ExecType::Commit executes remaining operations and commits the complete transaction. ExecType::Rollback rollbacks the entire transaction.
abortOption	Handling of error while excuting AbortOnError - Abort transaction if an operation fail AO_IgnoreError - Accept failing operations DefaultAbortOption - Use per-operation abort option
force	When operations should be sent to NDB Kernel. (See Adaptive Send Algorithm.) 0: non-force, adaptive algorithm notices it (default); 1: force send, adaptive algorithm notices it; 2: non-force, adaptive algorithm do not notice the send.

Returns: 0 if successful otherwise -1.

We abort the execute here. But we still need to put the split-off operation list back into the transaction object, or we will get a memory leak.

Definition at line 289 of file NdbTransaction.cpp.

Here is the caller graph for this function:

void NdbTransaction::executeAsynch	(	ExecType	aTypeOfExec,
		NdbAsynchCallback	aCallback,
		void *	anyObject,
		NdbOperation::AbortOption	abortOption = `NdbOperation::DefaultAbortOption`,
		int	forceSend = `0`
	)

Prepare and send an asynchronous transaction.

This method perform the same action as NdbTransaction::executeAsynchPrepare but also sends the operations to the NDB kernel.

See NdbTransaction::executeAsynchPrepare for information about the parameters of this method.

See Asynchronous Transactions for more information on how to use this method.

Definition at line 951 of file NdbTransaction.cpp.

Here is the call graph for this function:

void NdbTransaction::executeAsynchPrepare	(	NdbTransaction::ExecType	aTypeOfExec,
		NdbAsynchCallback	callback,
		void *	anyObject,
		NdbOperation::AbortOption	abortOption = `NdbOperation::DefaultAbortOption`
	)

Prepare an asynchronous transaction.

See Asynchronous Transactions for more information on how to use this method.

Parameters

execType	Execution type: ExecType::NoCommit executes operations without committing them. ExecType::Commit executes remaining operations and commits the complete transaction. ExecType::Rollback rollbacks the entire transaction.
callback	A callback method. This method gets called when the transaction has been executed. See ndbapi_async1.cpp for an example on how to specify and use a callback method.
anyObject	A void pointer. This pointer is forwarded to the callback method and can be used to give the callback method some data to work on. It is up to the application programmer to decide on the use of this pointer.
abortOption	see execute

Reset error.code on execute

for timeout (4012) we want sendROLLBACK to behave differently. Else, normal behaviour of reset errcode

Definition at line 689 of file NdbTransaction.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

int NdbTransaction::executePendingBlobOps ( Uint8 flags = 0xFF )

inline

Execute the transaction in NoCommit mode if there are any not-yet executed blob part operations of given types. Otherwise do nothing. The flags argument is bitwise OR of (1 << optype) where optype comes from NdbOperation::OperationType. Only the basic PK ops are used (read, insert, update, delete).

Definition at line 1432 of file NdbTransaction.hpp.

Here is the call graph for this function:

Uint32 NdbTransaction::getConnectedNodeId ( )

inline

Get nodeId of TC for this transaction

Definition at line 1293 of file NdbTransaction.hpp.

int NdbTransaction::getGCI ( Uint64 * gciptr )

Get global checkpoint identity (GCI) of transaction.

Each committed transaction belong to a GCI. The log for the committed transaction is saved on disk when a global checkpoint occurs.

Whether or not the global checkpoint with this GCI has been saved on disk or not cannot be determined by this method.

By comparing the GCI of a transaction with the value last GCI restored in a restarted NDB Cluster one can determine whether the transaction was restored or not.

Note: Global Checkpoint Identity is undefined for scan transactions (This is because no updates are performed in scan transactions.)

Returns: 0 if GCI is available, and stored in gciptr -1 if GCI is not available. (Note that there has to be an NdbTransaction::execute call with Ndb::Commit for the GCI to be available.)

Definition at line 2386 of file NdbTransaction.cpp.

int NdbTransaction::getGCI ( )

Deprecated...in favor of getGCI(Uint64*)

Definition at line 2375 of file NdbTransaction.cpp.

Ndb* NdbTransaction::getNdb ( )

inline

Convenience method to fetch this transaction's Ndb* object

Definition at line 200 of file NdbTransaction.hpp.

Here is the caller graph for this function:

const NdbError & NdbTransaction::getNdbError ( ) const

Get error object with information about the latest error.

Returns: An error object with information about the latest error.

Definition at line 52 of file Ndberr.cpp.

Here is the caller graph for this function:

int NdbTransaction::getNdbErrorLine ( )

Get the method number where the latest error occured.

Returns: Line number where latest error occured.

Definition at line 2417 of file NdbTransaction.cpp.

NdbOperation * NdbTransaction::getNdbErrorOperation ( )

Get the latest NdbOperation which had an error. This method is used on the NdbTransaction object to find the NdbOperation causing an error. To find more information about the actual error, use method NdbOperation::getNdbError() on the returned NdbOperation object.

Returns: The NdbOperation causing the latest error.

Deprecated:: Use the const NdbOperation returning variant.

Definition at line 2423 of file NdbTransaction.cpp.

const NdbOperation * NdbTransaction::getNdbErrorOperation ( ) const

Get the latest NdbOperation which had an error. This method is used on the NdbTransaction object to find the NdbOperation causing an error. To find more information about the actual error, use method NdbOperation::getNdbError() on the returned NdbOperation object.

Returns: The NdbOperation causing the latest error.

Definition at line 2430 of file NdbTransaction.cpp.

NdbIndexOperation * NdbTransaction::getNdbIndexOperation	(	const char *	anIndexName,
		const char *	aTableName
	)

Get an operation from NdbIndexOperation idlelist and get the NdbTransaction object that was fetched by startTransaction pointing to this operation.

Parameters

anIndexName	The index name (as created by createIndex).
aTableName	The table name.

Returns: Pointer to an NdbIndexOperation object if successful, otherwise NULL

Definition at line 1729 of file NdbTransaction.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

NdbIndexOperation * NdbTransaction::getNdbIndexOperation ( const NdbDictionary::Index * anIndex )

Get an operation from NdbIndexOperation idlelist and get the NdbTransaction object that was fetched by startTransaction pointing to this operation.

Parameters

anIndex An index object (fetched by NdbDictionary::Dictionary::getIndex).

Returns: Pointer to an NdbIndexOperation object if successful, otherwise NULL

Definition at line 1827 of file NdbTransaction.cpp.

Here is the call graph for this function:

NdbIndexScanOperation * NdbTransaction::getNdbIndexScanOperation	(	const char *	anIndexName,
		const char *	aTableName
	)

Get an operation from NdbIndexScanOperation idlelist and get the NdbTransaction object which was fetched by startTransaction pointing to this operation.

Parameters

anIndexName	The name of the index to use for scanning
aTableName	The name of the table to scan

Returns: pointer to an NdbOperation object if successful, otherwise NULL

Definition at line 1571 of file NdbTransaction.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

NdbIndexScanOperation * NdbTransaction::getNdbIndexScanOperation ( const NdbDictionary::Index * anIndex )

Get an operation from NdbIndexScanOperation idlelist and get the NdbTransaction object which was fetched by startTransaction pointing to this operation.

Parameters

anIndex An index object (fetched by NdbDictionary::Dictionary::getIndex).

Returns: pointer to an NdbOperation object if successful, otherwise NULL

Definition at line 1617 of file NdbTransaction.cpp.

Here is the call graph for this function:

NdbOperation * NdbTransaction::getNdbOperation ( const char * aTableName )

Get an NdbOperation for a table. Note that the operation has to be defined before it is executed.

Note: All operations within the same transaction need to be initialized with this method.

Parameters

aTableName The table name.

Returns: Pointer to an NdbOperation object if successful, otherwise NULL.

Definition at line 1442 of file NdbTransaction.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

NdbOperation * NdbTransaction::getNdbOperation ( const NdbDictionary::Table * aTable )

Get an NdbOperation for a table. Note that the operation has to be defined before it is executed.

Note: All operations within the same transaction need to be initialized with this method.

Parameters

aTable A table object (fetched by NdbDictionary::Dictionary::getTable)

Returns: Pointer to an NdbOperation object if successful, otherwise NULL.

Definition at line 1522 of file NdbTransaction.cpp.

Here is the call graph for this function:

NdbScanOperation * NdbTransaction::getNdbScanOperation ( const char * aTableName )

Get an operation from NdbScanOperation idlelist and get the NdbTransaction object which was fetched by startTransaction pointing to this operation.

Parameters

aTableName The table name.

Returns: pointer to an NdbOperation object if successful, otherwise NULL

Definition at line 1543 of file NdbTransaction.cpp.

Here is the caller graph for this function:

NdbScanOperation * NdbTransaction::getNdbScanOperation ( const NdbDictionary::Table * aTable )

Get an operation from NdbScanOperation idlelist and get the NdbTransaction object which was fetched by startTransaction pointing to this operation.

Parameters

aTable A table object (fetched by NdbDictionary::Dictionary::getTable)

Returns: pointer to an NdbOperation object if successful, otherwise NULL

Definition at line 1706 of file NdbTransaction.cpp.

Here is the call graph for this function:

const NdbOperation * NdbTransaction::getNextCompletedOperation ( const NdbOperation * op ) const

Get completed (i.e. executed) operations of a transaction

This method should only be used after a transaction has been executed.

NdbTransaction::getNextCompletedOperation(NULL) returns the first NdbOperation object.
NdbTransaction::getNextCompletedOperation(op) returns the NdbOperation object defined after the NdbOperation "op".

This method is typically used to fetch all NdbOperation:s of a transaction to check for errors (use NdbOperation::getNdbError to fetch the NdbError object of an NdbOperation).

Note: This method should only be used after the transaction has been executed and before the transaction has been closed.

Parameters

op	Operation, NULL means get first operation

Returns: Operation "after" op

Definition at line 2437 of file NdbTransaction.cpp.

Uint64 NdbTransaction::getTransactionId ( )

Get transaction identity.

Returns: Transaction id.

Definition at line 2405 of file NdbTransaction.cpp.

Here is the caller graph for this function:

int NdbTransaction::refresh ( )

Refresh Update timeout counter of this transaction in the database. If you want to keep the transaction active in the database longer than the transaction abort timeout.

Note: It's not advised to take a lock on a record and keep it for a extended time since this can impact other transactions.

Definition at line 966 of file NdbTransaction.cpp.

int NdbTransaction::restart ( )

Restart transaction

Once a transaction has been completed successfully it can be started again wo/ calling closeTransaction/startTransaction

Note: This method also releases completed operations; This method does not close open scans, c.f. NdbScanOperation::close(); This method can only be called directly after commit and only if commit is successful

Definition at line 236 of file NdbTransaction.cpp.

Here is the caller graph for this function:

NdbIndexScanOperation * NdbTransaction::scanIndex	(	const NdbRecord *	key_record,
		const NdbRecord *	result_record,
		NdbOperation::LockMode	lock_mode = `NdbOperation::LM_Read`,
		const unsigned char *	result_mask = `0`,
		const NdbIndexScanOperation::IndexBound *	bound = `0`,
		const NdbScanOperation::ScanOptions *	options = `0`,
		Uint32	sizeOfOptions = `0`
	)

Do an index range scan (optionally ordered) of a table.

The key_record describes the index to be scanned. It must be a key record for the index, ie. it must specify (at least) all the key columns of the index. And it must be created from the index to be scanned (not from the underlying table).

The result_record describes the rows to be returned from the scan. For an ordered index scan, result_record must be a key record for the index to be scanned, that is it must include at least all of the columns in the index (the reason is that the full index key is needed by NDBAPI for merge sorting the ordered rows returned from each fragment). The result_record must be created from the underlying table, not from the index to be scanned.

Both the key_record and result_record NdbRecord structures must stay in-place until the scan operation is closed.

A single IndexBound can either be specified in this call or in a separate call to NdbIndexScanOperation::setBound(). To perform a multi range read, the scan_flags in the ScanOptions structure must include SF_MULTIRANGE. Additional bounds can then be added using multiple calls to NdbIndexScanOperation::setBound().

To specify an equals bound, use the same row pointer for the low_key and high_key with the low and high inclusive bits set.

A ScanOptions structure can be passed, specifying extra options. See the definition of the ScanOptions structure for more information.

To enable backwards compatability of this interface, a sizeOfOptions parameter can be passed. This parameter indicates the size of the ScanOptions structure at the time the client was compiled, and enables detection of the use of an old ScanOptions structure. If this functionality is not required, it can be left set to zero.

Definition at line 2844 of file NdbTransaction.cpp.

Here is the call graph for this function:

NdbScanOperation * NdbTransaction::scanTable	(	const NdbRecord *	result_record,
		NdbOperation::LockMode	lock_mode = `NdbOperation::LM_Read`,
		const unsigned char *	result_mask = `0`,
		const NdbScanOperation::ScanOptions *	options = `0`,
		Uint32	sizeOfOptions = `0`
	)

Scan a table, using NdbRecord to read out column data.

The NdbRecord pointed to by result_record must remain valid until the scan operation is closed.

The result_mask pointer is optional, if present only columns for which the corresponding bit (by attribute id order) in result_mask is set will be retrieved in the scan. The result_mask is copied internally, so in contrast to result_record need not be valid at execute().

A ScanOptions structure can be passed, specifying extra options. See the definition of the NdbScanOperation::ScanOptions structure for more information.

To enable backwards compatability of this interface, a sizeOfOptions parameter can be passed. This parameter indicates the size of the ScanOptions structure at the time the client was compiled, and enables detection of the use of an old ScanOptions structure. If this functionality is not required, it can be left set to zero.

Definition at line 2800 of file NdbTransaction.cpp.

Here is the call graph for this function:

Friends And Related Function Documentation

friend class Ndb

friend

Reciver(s)

Definition at line 148 of file NdbTransaction.hpp.

friend class NdbIndexOperation

friend

Sender(s)

Definition at line 151 of file NdbTransaction.hpp.

friend class NdbOperation

friend

Sender(s)

Definition at line 149 of file NdbTransaction.hpp.

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

storage/ndb/include/ndbapi/NdbTransaction.hpp
storage/ndb/src/ndbapi/Ndberr.cpp
storage/ndb/src/ndbapi/Ndbif.cpp
storage/ndb/src/ndbapi/NdbTransaction.cpp
storage/ndb/src/ndbapi/NdbTransactionScan.cpp

Public Types

Public Member Functions

Friends

Meta Information

Detailed Description

Member Enumeration Documentation

Member Function Documentation

Friends And Related Function Documentation