None

None

A transaction is represented in the NDB API by an NdbTransaction object, which belongs to an Ndb object and is created using Ndb::startTransaction(). A transaction consists of a list of operations represented by the NdbOperation class, or by one of its subclasses—NdbScanOperation, NdbIndexOperation, or NdbIndexScanOperation. Each operation access exactly one table.

The following table lists the public methods of this class and the purpose or use of each method:

The methods readTuple(), insertTuple(), updateTuple(), writeTuple(), deleteTuple(), scanTable(), and scanIndex() require the use of NdbRecord.

NdbTransaction defines 2 public types as shown in the following table:

This method closes a transaction. It is equivalent to calling Ndb::closeTransaction().

If the transaction has not yet been committed, it is aborted when this method is called. See Ndb::startTransaction().

void close
    (
      void
    )

None.

None.

This method gets the transaction's commit status.

CommitStatusType commitStatus
    (
      void
    )

None.

The commit status of the transaction, a value of type CommitStatusType.

This type is used to describe a transaction's commit status.

Possible values are shown, along with descriptions, in the following table:

Deletes a tuple using NdbRecord.

const NdbOperation* deleteTuple
    (
      const NdbRecord* key_rec,
      const char* key_row,
      const NdbRecord* result_rec,
      char* result_row,
      const unsigned char* result_mask = 0,
      const NdbOperation::OperationOptions* opts = 0,
      Uint32 sizeOfOptions = 0
    )

This method takes the following parameters:

A const pointer to the NdbOperation representing this write operation. The operation can be checked for errors if necessary.

This type sets the transaction's execution type; that is, whether it should execute, execute and commit, or abort. It is used as a parameter to the execute() method. (See NdbTransaction::execute().)

Possible values are shown, along with descriptions, in the following table:

This method is used to execute a transaction.

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

The execute() method takes the three parameters listed here:

Returns 0 on success, or -1 on failure. The fact that the transaction did not abort does not necessarily mean that each operation was successful; you must check each operation individually for errors.

This method executes the transaction with ExecType equal to NoCommit if there remain any blob part operations of the given types which have not yet been executed.

int executePendingBlobOps
  (
    Uint8 flags = 0xFF
  )

The flags argument is the result of a bitwise OR, equal to 1 << optype, where optype is an NdbOperation::Type. The default corresponds to NdbOperation::Type::PrimaryKeyAccess.

Returns 0 on success, or -1 on failure. The fact that the transaction did not abort does not necessarily mean that each operation was successful; you must check each operation individually for errors.

This method retrieves the transaction's global checkpoint ID (GCI).

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

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

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

The GCI for a scan transaction is undefined, since no updates are performed in scan transactions.

No GCI is available until execute() has been called with ExecType::Commit.

int getGCI
    (
      void
    )

None.

The transaction's GCI, or -1 if none is available.

Gets the current batch size in bytes for blob read operations. When the volume of blob data to be read within a given transaction exceeds this amount, all of the transaction's pending blob read operations are executed.

Uint32 getMaxPendingBlobReadBytes
    (
      void
    ) const

None.

The current blob read batch size, in bytes. See NdbTransaction::setMaxPendingBlobReadBytes(), for more information.

Gets the current batch size in bytes for blob write operations. When the volume of blob data to be written within a given transaction exceeds this amount, all of the transaction's pending blob write operations are executed.

Uint32 getMaxPendingBlobWriteBytes
    (
      void
    ) const

None.

The current blob write batch size, in bytes. See NdbTransaction::setMaxPendingBlobWriteBytes(), for more information.

This method is used to obtain the most recent error (NdbError).

const NdbError& getNdbError
    (
      void
    ) const

None.

A reference to an NdbError object.

This method return the line number where the most recent error occurred.

int getNdbErrorLine
    (
      void
    )

None.

The line number of the most recent error.

This method retrieves the operation that caused an error.

To obtain more information about the actual error, use the NdbOperation::getNdbError() method of the NdbOperation object returned by getNdbErrorOperation().

NdbOperation* getNdbErrorOperation
    (
      void
    )

None.

A pointer to an NdbOperation.

This method is used to create an NdbIndexOperation associated with a given table.

All index operations within the same transaction must be initialised with this method. Operations must be defined before they are executed.

NdbIndexOperation* getNdbIndexOperation
    (
      const NdbDictionary::Index* index
    )

The Index object on which the operation is to be performed.

A pointer to the new NdbIndexOperation.

This method is used to create an NdbIndexScanOperation associated with a given table.

All index scan operations within the same transaction must be initialised with this method. Operations must be defined before they are executed.

NdbIndexScanOperation* getNdbIndexScanOperation
    (
      const NdbDictionary::Index* index
    )

The Index object on which the operation is to be performed.

A pointer to the new NdbIndexScanOperation.

This method is used to create an NdbOperation associated with a given table.

All operations within the same transaction must be initialized with this method. Operations must be defined before they are executed.

NdbOperation* getNdbOperation
    (
      const NdbDictionary::Table* table
    )

The Table object on which the operation is to be performed.

A pointer to the new NdbOperation.

This method is used to create an NdbScanOperation associated with a given table.

All scan operations within the same transaction must be initialized with this method. Operations must be defined before they are executed.

NdbScanOperation* getNdbScanOperation
    (
      const NdbDictionary::Table* table
    )

The Table object on which the operation is to be performed.

A pointer to the new NdbScanOperation.

This method is used to retrieve a transaction's completed operations. It is typically used to fetch all operations belonging to a given transaction to check for errors.

NdbTransaction::getNextCompletedOperation(NULL) returns the transaction's first NdbOperation object; NdbTransaction::getNextCompletedOperation(myOp) returns the NdbOperation object defined after NdbOperation myOp.

This method should only be used after the transaction has been executed, but before the transaction has been closed.

const NdbOperation* getNextCompletedOperation
    (
      const NdbOperation* op
    ) const

This method requires a single parameter op, which is an operation (NdbOperation object), or NULL.

The operation following op, or the first operation defined for the transaction if getNextCompletedOperation() was called using NULL.

This method is used to obtain the transaction ID.

Uint64 getTransactionId
    (
      void
    )

None.

The transaction ID, as an unsigned 64-bit integer.

Inserts a tuple using NdbRecord.

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
    )

insertTuple() takes the following parameters:

A const pointer to the NdbOperation representing this insert operation.

This method reads a tuple using NdbRecord objects.

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
    )

This method takes the following parameters:

A pointer to the NdbOperation representing this read operation (this can be used to check for errors).

This method updates the transaction's timeout counter, and thus avoids aborting due to transaction timeout.

It is not advisable to take a lock on a record and maintain it for a extended time since this can impact other transactions.

int refresh
    (
      void
    )

None.

Returns 0 on success, -1 on failure.

This method is used to release a lock handle (see NdbOperation::getLockHandle) when it is no longer required. For NdbRecord primary key read operations, this cannot be called until the associated read operation has been executed.

All lock handles associated with a given transaction are released when that transaction is closed.

int releaseLockHandle
    (
      const NdbLockHandle* lockHandle
    )

The NdbLockHandle object to be released.

0 on success.

Perform an index range scan of a table, with optional ordering.

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
    )

The current NdbIndexScanOperation, which can be used for error checking.

This method performs a table scan, using an NdbRecord object to read out column data.

NdbScanOperation* scanTable
    (
      const NdbRecord* result_record,
      NdbOperation::LockMode lock_mode = NdbOperation::LM_Read,
      const unsigned char* result_mask = 0,
      Uint32 scan_flags = 0,
      Uint32 parallel = 0,
      Uint32 batch = 0
    )

The scanTable() method takes the following parameters:

A pointer to the NdbScanOperation representing this scan. The operation can be checked for errors if necessary.

Sets the batch size in bytes for blob read operations. When the volume of blob data to be read within a given transaction exceeds this amount, all of the transaction's pending blob read operations are executed.

void setMaxPendingBlobReadBytes
    (
      Uint32 bytes
    )

The batch size, as the number of bytes. Using 0 causes blob read batching to be disabled, which is the default behavior (for backward compatibility).

None.

Sets the batch size in bytes for blob write operations. When the volume of blob data to be written within a given transaction exceeds this amount, all of the transaction's pending blob write operations are executed.

void setMaxPendingBlobWriteBytes
    (
      Uint32 bytes
    )

The batch size, as the number of bytes. Using 0 causes blob write batching to be disabled, which is the default behavior (for backward compatibility).

None.

Enables or disables a schema object ownership check when multiple Ndb_cluster_connection objects are in use. When this check is enabled, objects used by this transaction are checked to make sure that they belong to the NdbDictionary owned by this connection. This is done by acquiring the schema objects of the same names from the connection and comparing these with the schema objects passed to the transaction. If they do not match, an error is returned.

This method is available for debugging purposes. (Bug #19875977) You should be aware that enabling this check carries a performance penalty and for this reason you should avoid doing so in a production setting.

void setSchemaObjOwnerChecks
    (
      bool runChecks
    )

A single parameter runChecks. Use true to enable ownership checks, false to disable them.

None.

This method creates an unlock operation on the current transaction; when executed, the unlock operation removes the lock referenced by the NdbLockHandle (see NdbOperation::getLockHandle) passed to the method.

const NdbOperation* unlock
    (
      const NdbLockHandle* lockHandle,
      NdbOperation::AbortOption ao = NdbOperation::DefaultAbortOption
    )

A pointer to a lock handle; in addition, optionally, an AbortOption value ao.

In the event that the unlock operation fails—for example, due to the row already being unlocked—the AbortOption specifies how this is handled, the default being that errors cause transactions to abort.

A pointer to an NdbOperation (the unlock operation created).

Updates a tuple using an NdbRecord object.

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
    )

updateTuple() takes the following parameters:

The NdbOperation representing this operation (can be used to check for errors).

This method is used with NdbRecord to write a tuple of data.

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
    )

This method takes the following parameters:

A const pointer to the NdbOperation representing this write operation. The operation can be checked for errors if and as necessary.