2.3.29.2 NdbTransaction Methods

2.3.29.2.1 NdbTransaction::close()
2.3.29.2.2 NdbTransaction::commitStatus()
2.3.29.2.3 NdbTransaction::deleteTuple()
2.3.29.2.4 NdbTransaction::execute()
2.3.29.2.5 NdbTransaction::getGCI()
2.3.29.2.6 NdbTransaction::getMaxPendingBlobReadBytes()
2.3.29.2.7 NdbTransaction::getMaxPendingBlobWriteBytes()
2.3.29.2.8 NdbTransaction::getNdbError()
2.3.29.2.9 NdbTransaction::getNdbErrorLine()
2.3.29.2.10 NdbTransaction::getNdbErrorOperation()
2.3.29.2.11 NdbTransaction::getNdbIndexOperation()
2.3.29.2.12 NdbTransaction::getNdbIndexScanOperation()
2.3.29.2.13 NdbTransaction::getNdbOperation()
2.3.29.2.14 NdbTransaction::getNdbScanOperation()
2.3.29.2.15 NdbTransaction::getNextCompletedOperation()
2.3.29.2.16 NdbTransaction::getTransactionId()
2.3.29.2.17 NdbTransaction::insertTuple()
2.3.29.2.18 NdbTransaction::readTuple()
2.3.29.2.19 NdbTransaction::refresh()
2.3.29.2.20 NdbTransaction::releaseLockHandle()
2.3.29.2.21 NdbTransaction::scanIndex()
2.3.29.2.22 NdbTransaction::scanTable()
2.3.29.2.23 NdbTransaction::setMaxPendingBlobReadBytes()
2.3.29.2.24 NdbTransaction::setMaxPendingBlobWriteBytes()
2.3.29.2.25 NdbTransaction::unlock()
2.3.29.2.26 NdbTransaction::updateTuple()
2.3.29.2.27 NdbTransaction::writeTuple()

Abstract

This section lists and describes the public methods of the NdbTransaction class.

2.3.29.2.1 NdbTransaction::close()

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

Important

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

Signature. 

void close
    (
      void
    )

Parameters.  None.

Return value.  None.

2.3.29.2.2 NdbTransaction::commitStatus()

Description.  This method gets the transaction's commit status.

Signature. 

CommitStatusType commitStatus
    (
      void
    )

Parameters.  None.

Return value.  The commit status of the transaction, a CommitStatusType value. See Section 2.3.29.1.2, “The NdbTransaction::CommitStatusType Type”.

2.3.29.2.3 NdbTransaction::deleteTuple()

Description.  Deletes a tuple using NdbRecord.

Signature. 

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
    )

Parameters.  This method takes the following parameters:

  • key_rec is a pointer to an NdbRecord for either a table or an index. If on a table, then the delete operation uses a primary key; if on an index, then the operation uses a unique key. In either case, the key_rec must include all columns of the key.

  • The key_row passed to this method defines the primary or unique key of the tuple to be deleted, and must remain valid until execute() is called.

  • The result_rec is the NdbRecord to be used.

  • The result_row can be NULL if no attributes are to be returned.

  • The result_mask, if not NULL, defines a subset of attributes to be read and returned to the client. The mask is copied, and so does not need to remain valid after the call to this method returns.

  • OperationOptions (opts) can be used to provide more finely-grained control of operation definitions. An OperationOptions structure is passed with flags indicating which operation definition options are present. Not all operation types support all operation options; for the options supported by each type of operation, see Section 2.3.29.2.18, “NdbTransaction::readTuple().

  • The optional sizeOfOptions parameter provides backward compatibility of this interface with previous definitions of the OperationOptions structure. If an unusual size is detected by the interface implementation, it can use this to determine how to interpret the passed OperationOptions structure. To enable this functionality, the caller should pass sizeof(NdbOperation::OperationOptions) for the value of this argument.

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

Signature (old version).  Prior to MySQL Cluster NDB 6.2.15 and 6.3.15, this method was defined as shown here:

NdbOperation* deleteTuple
    (
      const NdbRecord* key_rec,
      const char* key_row
    )

Parameters (old version).  Prior to MySQL Cluster NDB 6.2.15 and 6.3.15, this method took the following parameters:

  • key_rec is a pointer to an NdbRecord for either a table or an index. If on a table, then the delete operation uses a primary key; if on an index, then the operation uses a unique key. In either case, the key_rec must include all columns of the key.

  • The key_row passed to this method defines the primary or unique key of the tuple to be deleted, and must remain valid until execute() is called.

Return Value (old version).  A pointer to the NdbOperation representing this write operation. The operation can be checked for errors if necessary.

2.3.29.2.4 NdbTransaction::execute()

Description.  This method is used to execute a transaction.

Signature. 

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

Parameters.  The execute method takes the three parameters listed here:

Return value.  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.

In MySQL 5.1.15 and earlier versions, this method returned -1 for some errors even when the trasnsaction itself was not aborted; beginning with MySQL 5.1.16, this method reports a failure if and only if the transaction was aborted. (This change was made due to the fact it had been possible to construct cases where there was no way to determine whether or not a transaction was actually aborted.) However, the transaction's error information is still set in such cases to reflect the actual error code and category.

This means, in the case where a NoDataFound error is a possibility, you must now check for it explicitly, as shown in this example:

Ndb_cluster_connection myConnection;

if( myConnection.connect(4, 5, 1) )
{
  cout << "Unable to connect to cluster within 30 secs." << endl;
  exit(-1);
}

Ndb myNdb(&myConnection, "test");

//  define operations...

myTransaction = myNdb->startTransaction();

if(myTransaction->getNdbError().classification == NdbError:NoDataFound)
{
  cout << "No records found." << endl;
  //  ...
}

myNdb->closeTransaction(myTransaction);
2.3.29.2.5 NdbTransaction::getGCI()

Description.  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.

Note

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

Important

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

Signature. 

int getGCI
    (
      void
    )

Parameters.  None.

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

Note

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

2.3.29.2.6 NdbTransaction::getMaxPendingBlobReadBytes()

Description.  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.

This method was introduced in MySQL Cluster NDB 7.0.21 and MySQL Cluster NDB 7.1.10.

Signature. 

Uint32 getMaxPendingBlobReadBytes
    (
      void
    ) const

Parameters.  None.

Return value.  The current BLOB read batch size, in bytes. See Section 2.3.29.2.23, “NdbTransaction::setMaxPendingBlobReadBytes(), for more information.

2.3.29.2.7 NdbTransaction::getMaxPendingBlobWriteBytes()

Description.  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.

This method was introduced in MySQL Cluster NDB 7.0.21 and MySQL Cluster NDB 7.1.10.

Signature. 

Uint32 getMaxPendingBlobWriteBytes
    (
      void
    ) const

Parameters.  None.

Return value.  The current BLOB write batch size, in bytes. See Section 2.3.29.2.24, “NdbTransaction::setMaxPendingBlobWriteBytes(), for more information.

2.3.29.2.8 NdbTransaction::getNdbError()

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

Signature. 

const NdbError& getNdbError
    (
      void
    ) const

Parameters.  None.

Return value.  A reference to an NdbError object.

Note

For additional information about handling errors in transactions, see Section 1.3.2.3.5, “Error Handling”.

2.3.29.2.9 NdbTransaction::getNdbErrorLine()

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

Signature. 

int getNdbErrorLine
    (
      void
    )

Parameters.  None.

Return value.  The line number of the most recent error.

Note

For additional information about handling errors in transactions, see Section 1.3.2.3.5, “Error Handling”.

2.3.29.2.10 NdbTransaction::getNdbErrorOperation()

Description.  This method retrieves the operation that caused an error.

Tip

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

Signature. 

NdbOperation* getNdbErrorOperation
    (
      void
    )

Parameters.  None.

Return value.  A pointer to an NdbOperation.

Note

For additional information about handling errors in transactions, see Section 1.3.2.3.5, “Error Handling”.

2.3.29.2.11 NdbTransaction::getNdbIndexOperation()

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

Note

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

Signature. 

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

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

Return value.  A pointer to the new NdbIndexOperation.

2.3.29.2.12 NdbTransaction::getNdbIndexScanOperation()

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

Note

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

Signature. 

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

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

Return value.  A pointer to the new NdbIndexScanOperation.

2.3.29.2.13 NdbTransaction::getNdbOperation()

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

Note

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

Signature. 

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

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

Return value.  A pointer to the new NdbOperation.

2.3.29.2.14 NdbTransaction::getNdbScanOperation()

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

Note

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

Signature. 

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

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

Return value.  A pointer to the new NdbScanOperation.

2.3.29.2.15 NdbTransaction::getNextCompletedOperation()

Description.  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.

Important

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

Signature. 

const NdbOperation* getNextCompletedOperation
    (
      const NdbOperation* op
    ) const

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

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

2.3.29.2.16 NdbTransaction::getTransactionId()

Description.  This method is used to obtain the transaction ID.

Signature. 

Uint64 getTransactionId
    (
      void
    )

Parameters.  None.

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

2.3.29.2.17 NdbTransaction::insertTuple()

Description.  Inserts a tuple using NdbRecord.

Signature. 

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
    )

Parameters.  insertTuple() takes the following parameters:

  • A pointer to an NdbRecord indicating the record (key_rec) to be inserted.

  • A row (key_row) of data to be inserted.

  • A pointer to an NdbRecord indicating an attribute (attr_rec) to be inserted.

  • A row (attr_row) of data to be inserted as the attribute.

  • A mask which can be used to filter the columns to be inserted.

  • OperationOptions (opts) can be used to provide more finely-grained control of operation definitions. An OperationOptions structure is passed with flags indicating which operation definition options are present. Not all operation types support all operation options; for the options supported by each type of operation, see Section 2.3.29.2.18, “NdbTransaction::readTuple().

  • The optional sizeOfOptions parameter is used to preserve backward compatibility of this interface with previous definitions of the OperationOptions structure. If an unusual size is detected by the interface implementation, it can use this to determine how to interpret the passed OperationOptions structure. To enable this functionality, the caller should pass sizeof(NdbOperation::OperationOptions) for the value of this argument.

This method can also be called using a single NdbRecord pointer and single char pointer (combined_rec, combined_row) where the single NdbRecord represents record and attribute and data.

Return value.  A const pointer to the NdbOperation representing this insert operation.

Signature (old version).  Prior to MySQL Cluster NDB 6.2.15 and MySQL Cluster NDB 6.3.15, this method was defined as follows:

NdbOperation* insertTuple
    (
      const NdbRecord* record,
      const char* row,
      const unsigned char* mask = 0
    )

Parameters (old version).  Prior to MySQL Cluster NDB 6.2.15 and 6.3.15, insertTuple() took the following parameters:

  • A pointer to an NdbRecord indicating the record to be inserted.

  • A row of data to be inserted.

  • A mask which can be used to filter the columns to be inserted.

Return Value (old version).  Prior to MySQL Cluster NDB 6.2.15 and 6.3.15, this method returned a pointer to the NdbOperation representing the insert operation.

2.3.29.2.18 NdbTransaction::readTuple()

Description.  This method reads a tuple using NdbRecord objects.

Signature. 

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
    )

Parameters.  This method takes the following parameters:

  • key_rec is a pointer to an NdbRecord for either a table or an index. If on a table, then the operation uses a primary key; if on an index, then the operation uses a unique key. In either case, the key_rec must include all columns of the key.

  • The key_row passed to this method defines the primary or unique key of the affected tuple, and must remain valid until execute() is called.

    The mask, if not NULL, defines a subset of attributes to read, update, or insert. Only if (mask[attrId >> 3] & (1<<(attrId & 7))) is set is the column affected. The mask is copied by the methods, so need not remain valid after the call returns.

  • result_rec is a pointer to an NdbRecord used to hold the result

  • result_row defines a buffer for the result data.

  • lock_mode specifies the lock mode in effect for the operation. See Section 2.3.24.1.2, “The NdbOperation::LockMode Type”, for permitted values and other information.

  • result_mask defines a subset of attributes to read. Only if mask[attrId >> 3] & (1<<(attrId & 7)) is set is the column affected. The mask is copied, and so need not remain valid after the method call returns.

  • OperationOptions (opts) can be used to provide more finely-grained control of operation definitions. An OperationOptions structure is passed with flags indicating which operation definition options are present. Not all operation types support all operation options; the options supported for each type of operation are shown in the following table:

    Operation type (Method)OperationOptions Flags Supported
    readTuple()OO_ABORTOPTION, OO_GETVALUE, OO_PARTITION_ID, OO_INTERPRETED
    insertTuple()OO_ABORTOPTION, OO_SETVALUE, OO_PARTITION_ID, OO_ANYVALUE
    updateTuple()OO_ABORTOPTION, OO_SETVALUE, OO_PARTITION_ID, OO_INTERPRETED, OO_ANYVALUE
    writeTuple()OO_ABORTOPTION, OO_SETVALUE, OO_PARTITION_ID, OO_ANYVALUE
    deleteTuple()OO_ABORTOPTION, OO_GETVALUE, OO_PARTITION_ID, OO_INTERPRETED, OO_ANYVALUE
  • The optional sizeOfOptions parameter is used to preserve backward compatibility of this interface with previous definitions of the OperationOptions structure. If an unusual size is detected by the interface implementation, it can use this to determine how to interpret the passed OperationOptions structure. To enable this functionality, the caller should pass sizeof(NdbOperation::OperationOptions) for the value of this argument.

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

Signature (old version).  Prior to MySQL Cluster NDB 6.2.15 and 6.3.15, this method was defined as shown here:

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
    )

Parameters (old version).  Prior to MySQL Cluster NDB 6.2.15 and 6.3.15, this method took the following parameters:

  • key_rec is a pointer to an NdbRecord for either a table or an index. If on a table, then the operation uses a primary key; if on an index, then the operation uses a unique key. In either case, the key_rec must include all columns of the key.

  • The key_row passed to this method defines the primary or unique key of the affected tuple, and must remain valid until execute() is called.

  • result_rec is a pointer to an NdbRecord used to hold the result

  • result_row defines a buffer for the result data.

  • lock_mode specifies the lock mode in effect for the operation. See Section 2.3.24.1.2, “The NdbOperation::LockMode Type”, for permitted values and other information.

  • result_mask defines a subset of attributes to read. Only if mask[attrId >> 3] & (1<<(attrId & 7)) is set is the column affected. The mask is copied, and so need not remain valid after the method call returns.

Return value (old version).  A pointer to the NdbOperation representing this operation (this can be used to check for errors).

2.3.29.2.19 NdbTransaction::refresh()

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

Important

Prior to MySQL Cluster NDB 6.3.36, MySQL Cluster NDB 7.0.17, and MySQL Cluster NDB 7.1.6, this method did not update the counter used to track TransactionInactiveTimeout (see Bug #54724).

Note

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

Signature. 

int refresh
    (
      void
    )

Parameters.  None.

Return value.  Returns 0 on success, -1 on failure.

2.3.29.2.20 NdbTransaction::releaseLockHandle()

Description.  This method is used to release a lock handle (see Section 2.3.24.2.4, “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.

Note

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

Signature. 

int releaseLockHandle
    (
      const NdbLockHandle* lockHandle
    )

Parameters.  The NdbLockHandle object to be released.

Return value.  0 on success.

2.3.29.2.21 NdbTransaction::scanIndex()

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

The signature for this method changed in MySQL Cluster NDB 6.3.8. Information about the old-style signature follows later in this section.

Signature (MySQL Cluster NDB 6.3.8 and later). 

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
    )

Parameters (MySQL Cluster NDB 6.3.8 and later).  The key_record describes the index to be scanned. It must be a key record for the index; that is, it must specify, at a minimum, all of the key columns of the index. The key_record must be created from the index to be scanned (and 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 a minimum) all of the columns in the index (the full index key is needed by the NDB API for merge-sorting the ordered rows returned from each fragment).

Like the key_record, the result_record must be created from the underlying table, and 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 be specified either 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 be added using successive 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.

To specify additional options, pass a ScanOptions structure.

The sizeOfOptions exists To enable backwards compatability for this interface. 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-style ScanOptions structure. If this functionality is not required, this argument can be left set to 0.

The parameters used by this method changed in MySQL Cluster NDB 6.3.8. Information about the old-style parameters follows later in this section.

Note

For multi-range scans, the low_key and high_key pointers must be unique. In other words, it is not permissible to reuse the same row buffer for several different range bounds within a single scan. However, it is permissible to use the same row pointer as low_key and high_key in order to specify an equals bound; it is also permissible to reuse the rows after the scanIndex() method returns—that is, they need not remain valid until execute() time (unlike the NdbRecord pointers).

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

Signature (old style). 

NdbIndexScanOperation* scanIndex
    (
      const NdbRecord* key_record,
      const char* low_key,
      Uint32 low_key_count,
      bool low_inclusive,
      const char* high_key,
      Uint32 high_key_count,
      bool high_inclusive,
      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
    )

Parameters (old style).  This method takes the following parameters:

  • The key_record describes the index to be scanned. It must be a key record on the index; that is, the columns which it specifies must include all of the key columns of the index. It must be created from the index to be scanned, and not from the underlying table.

  • low_key determines the lower bound for a range scan.

  • low_key_count determines the number of columns used for the lower bound when specifying a partial prefix for the scan.

  • low_inclusive determines whether the lower bound is considered as a >= or > relation.

  • high_key determines the upper bound for a range scan.

  • high_key_count determines the number of columns used for the higher bound when specifying a partial prefix for the scan.

  • high_inclusive determines whether the lower bound is considered as a <= or < relation.

  • The result_record describes the rows to be returned from the scan. For an ordered index scan, result_record be a key record on the index; that is, the columns which it specifies must include all of the key columns of the index. This is because the index key is needed for merge sorting of the scans returned from each fragment.

  • The lock_mode for the scan must be one of the values specified in Section 2.3.24.1.2, “The NdbOperation::LockMode Type”.

  • The result_mask pointer is optional. If it is 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 when execute() is invoked.

  • scan_flags can be used to impose ordering and sorting conditions for scans. See Section 2.3.28.1, “The NdbScanOperation::ScanFlag Type”, for a list of permitted values.

  • The parallel argument is the desired parallelism, or 0 for maximum parallelism (receiving rows from all fragments in parallel), which is the default.

  • batch determines whether batching is employed. The default is 0 (off).

2.3.29.2.22 NdbTransaction::scanTable()

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

Signature. 

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
    )

Parameters.  The scanTable() method takes the following parameters:

  • A pointer to an NdbRecord for storing the result. This result_record must remain valid until after the execute() call has been made.

  • The lock_mode in effect for the operation. See Section 2.3.24.1.2, “The NdbOperation::LockMode Type”, for permitted values and other information.

  • The result_mask pointer is optional. If it is 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 when execute() is invoked.

  • scan_flags can be used to impose ordering and sorting conditions for scans. See Section 2.3.28.1, “The NdbScanOperation::ScanFlag Type”, for a list of permitted values.

  • The parallel argument is the desired parallelism, or 0 for maximum parallelism (receiving rows from all fragments in parallel), which is the default.

  • batch determines whether batching is employed. The default is 0 (off).

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

2.3.29.2.23 NdbTransaction::setMaxPendingBlobReadBytes()

Description.  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.

This method was introduced in MySQL Cluster NDB 7.0.21 and MySQL Cluster NDB 7.1.10.

Signature. 

void setMaxPendingBlobReadBytes
    (
      Uint32 bytes
    )

Parameters.  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).

Return value.  None.

Note

BLOB read batching can also be controlled in the mysql client and other MySQL client application using the MySQL Server's --ndb-blob-read-batch-bytes option and its associated MySQL Server system variables.

2.3.29.2.24 NdbTransaction::setMaxPendingBlobWriteBytes()

Description.  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.

This method was introduced in MySQL Cluster NDB 7.0.21 and MySQL Cluster NDB 7.1.10.

Signature. 

void setMaxPendingBlobWriteBytes
    (
      Uint32 bytes
    )

Parameters.  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).

Return value.  None.

Note

BLOB write batching can also be controlled in the mysql client and other MySQL client application using the MySQL Server's --ndb-blob-write-batch-bytes option and its associated MySQL Server system variables.

2.3.29.2.25 NdbTransaction::unlock()

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

Signature. 

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

Parameters.  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.

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

2.3.29.2.26 NdbTransaction::updateTuple()

Description.  Updates a tuple using an NdbRecord object.

Signature. 

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
    )

Parameters.  updateTuple() takes the following parameters:

  • key_rec is a pointer to an NdbRecord for either a table or an index. If on a table, then the operation uses a primary key; if on an index, then the operation uses a unique key. In either case, the key_rec must include all columns of the key.

  • The key_row passed to this method defines the primary or unique key of the affected tuple, and must remain valid until execute() is called.

  • attr_rec is an NdbRecord referencing the attribute to be updated.

    Note

    For unique index operations, the attr_rec must refer to the underlying table of the index, not to the index itself.

  • attr_row is a buffer containing the new data for the update.

  • The mask, if not NULL, defines a subset of attributes to be updated. The mask is copied, and so does not need to remain valid after the call to this method returns.

  • OperationOptions (opts) can be used to provide more finely-grained control of operation definitions. An OperationOptions structure is passed with flags indicating which operation definition options are present. Not all operation types support all operation options; for the options supported by each type of operation, see Section 2.3.29.2.18, “NdbTransaction::readTuple().

  • The optional sizeOfOptions parameter is used to preserve backward compatibility of this interface with previous definitions of the OperationOptions structure. If an unusual size is detected by the interface implementation, it can use this to determine how to interpret the passed OperationOptions structure. To enable this functionality, the caller should pass sizeof(NdbOperation::OperationOptions) for the value of this argument.

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

Old version.  Prior to MySQL Cluster NDB 6.2.15 and 6.3.15, this method was defined as follows:

NdbOperation* updateTuple
    (
      const NdbRecord* key_rec,
      const char* key_row,
      const NdbRecord* attr_rec,
      const char* attr_row,
      const unsigned char* mask = 0
    )

Parameters (old version).  Prior to MySQL Cluster NDB 6.2.15 and 6.3.15, updateTuple() took the following parameters:

  • key_rec is a pointer to an NdbRecord for either a table or an index. If on a table, then the operation uses a primary key; if on an index, then the operation uses a unique key. In either case, the key_rec must include all columns of the key.

  • The key_row passed to this method defines the primary or unique key of the affected tuple, and must remain valid until execute() is called.

  • attr_rec is an NdbRecord referencing the attribute to be updated.

    Note

    For unique index operations, the attr_rec must refer to the underlying table of the index, not to the index itself.

  • attr_row is a buffer containing the new data for the update.

  • The mask, if not NULL, defines a subset of attributes to be updated. The mask is copied, and so does not need to remain valid after the call to this method returns.

Return Value (old version).  Prior to MySQL Cluster NDB 6.2.15 and 6.3.15, this method returned a pointer to the NdbOperation representing this operation (which could be used to check for errors).

2.3.29.2.27 NdbTransaction::writeTuple()

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

Signature. 

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
    )

Parameters.  This method takes the following parameters:

  • key_rec is a pointer to an NdbRecord for either a table or an index. If on a table, then the operation uses a primary key; if on an index, then the operation uses a unique key. In either case, the key_rec must include all columns of the key.

  • The key_row passed to this method defines the primary or unique key of the tuple to be written, and must remain valid until execute() is called.

  • attr_rec is an NdbRecord referencing the attribute to be written.

    Note

    For unique index operations, the attr_rec must refer to the underlying table of the index, not to the index itself.

  • attr_row is a buffer containing the new data.

  • The mask, if not NULL, defines a subset of attributes to be written. The mask is copied, and so does not need to remain valid after the call to this method returns.

  • OperationOptions (opts) can be used to provide more finely-grained control of operation definitions. An OperationOptions structure is passed with flags indicating which operation definition options are present. Not all operation types support all operation options; for the options supported by each type of operation, see Section 2.3.29.2.18, “NdbTransaction::readTuple().

  • The optional sizeOfOptions parameter is used to provide backward compatibility of this interface with previous definitions of the OperationOptions structure. If an unusual size is detected by the interface implementation, it can use this to determine how to interpret the passed OperationOptions structure. To enable this functionality, the caller should pass sizeof(NdbOperation::OperationOptions) for the value of this argument.

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

Signature (old version).  Prior to MySQL Cluster NDB 6.2.15 and 6.3.15, this method was defined as shown here:

NdbOperation* writeTuple
    (
      const NdbRecord* key_rec,
      const char* key_row,
      const NdbRecord* attr_rec,
      const char* attr_row,
      const unsigned char* mask = 0
    )

Parameters (old version).  Prior to MySQL Cluster NDB 6.2.15 and 6.3.15, this method took the following parameters:

  • key_rec is a pointer to an NdbRecord for either a table or an index. If on a table, then the operation uses a primary key; if on an index, then the operation uses a unique key. In either case, the key_rec must include all columns of the key.

  • The key_row passed to this method defines the primary or unique key of the tuple to be written, and must remain valid until execute() is called.

  • attr_rec is an NdbRecord referencing the attribute to be written.

    Note

    For unique index operations, the attr_rec must refer to the underlying table of the index, not to the index itself.

  • attr_row is a buffer containing the new data.

  • The mask, if not NULL, defines a subset of attributes to be written. The mask is copied, and so does not need to remain valid after the call to this method returns.

Return Value (old version).  Prior to MySQL Cluster NDB 6.2.15 and 6.3.15, this method returned a pointer to the NdbOperation representing this write operation. The operation could be checked for errors if and as necessary.