Skip navigation links
2.3.20 The Object Class »
Section Navigation      [Toggle]

2.3.19.2. NdbTransaction Methods

[+/-]

2.3.19.2.1. NdbTransaction::getNdbOperation()
2.3.19.2.2. NdbTransaction::getNdbScanOperation()
2.3.19.2.3. NdbTransaction::getNdbIndexScanOperation()
2.3.19.2.4. NdbTransaction::getNdbIndexOperation()
2.3.19.2.5. NdbTransaction::execute()
2.3.19.2.6. NdbTransaction::refresh()
2.3.19.2.7. NdbTransaction::close()
2.3.19.2.8. NdbTransaction::getGCI()
2.3.19.2.9. NdbTransaction::getTransactionId()
2.3.19.2.10. NdbTransaction::commitStatus()
2.3.19.2.11. NdbTransaction::getNdbError()
2.3.19.2.12. NdbTransaction::getNdbErrorOperation()
2.3.19.2.13. NdbTransaction::getNdbErrorLine()
2.3.19.2.14. NdbTransaction::getNextCompletedOperation()
2.3.19.2.15. NdbTransaction::readTuple()
2.3.19.2.16. NdbTransaction::insertTuple()
2.3.19.2.17. NdbTransaction::updateTuple()
2.3.19.2.18. NdbTransaction::writeTuple()
2.3.19.2.19. NdbTransaction::deleteTuple()
2.3.19.2.20. NdbTransaction::scanTable()
2.3.19.2.21. NdbTransaction::scanIndex()

Abstract

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

2.3.19.2.1. 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. See Section 2.3.21, “The Table Class”.

Return value.  A pointer to the new NdbOperation. See Section 2.3.15, “The NdbOperation Class”.

2.3.19.2.2. 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. See Section 2.3.21, “The Table Class”.

Return value.  A pointer to the new NdbScanOperation. See Section 2.3.18, “The NdbScanOperation Class”.

2.3.19.2.3. 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. See Section 2.3.5, “The Index Class”.

Return value.  A pointer to the new NdbIndexScanOperation. See Section 2.3.13, “The NdbIndexScanOperation Class”.

2.3.19.2.4. 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. See Section 2.3.5, “The Index Class”.

Return value.  A pointer to the new NdbIndexOperation. See Section 2.3.12, “The NdbIndexOperation Class”.

2.3.19.2.5. 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 3 parameters, as described here:

Return value.  0 on success, -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, for 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.19.2.6. NdbTransaction::refresh()

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

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.  0 on success, -1 on failure.

2.3.19.2.7. NdbTransaction::close()

Description.  This method closes a transaction. It is equivalent to calling Ndb::closeTransaction() (see Section 2.3.8.1.9, “Ndb::closeTransaction()”).

Important

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

Signature.  

void close
    (
      void
    )

Parameters.  None.

Return value.  None.

2.3.19.2.8. 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.19.2.9. 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.19.2.10. 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.19.1.2, “The NdbTransaction::CommitStatusType Type”.

2.3.19.2.11. 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. See Section 2.3.31, “The NdbError Structure”.

Note

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

2.3.19.2.12. 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(). (See Section 2.3.15.2.5, “NdbOperation::getNdbError()”.)

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.19.2.13. 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.19.2.14. 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.19.2.15. 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.

  • 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.15.1.3, “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 allow this interface to be backwards compatible 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).

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.15.1.3, “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.  The NdbOperation representing this operation (this can be used to check for errors).

2.3.19.2.16. 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.19.2.15, “NdbTransaction::readTuple()”.

  • The optional sizeOfOptions parameter is used to allow this interface to be backwards compatible 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.

Old version.  Prior to MySQL Cluster NDB 6.2.15 and 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.19.2.17. 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.

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.19.2.18. 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.19.2.15, “NdbTransaction::readTuple()”.

  • The optional sizeOfOptions parameter is used to allow this interface to be backwards compatible 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.

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.

2.3.19.2.19. 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_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.19.2.15, “NdbTransaction::readTuple()”.

  • The optional sizeOfOptions parameter is used to allow this interface to be backwards compatible 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.

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.19.2.20. 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.15.1.3, “The NdbOperation::LockMode Type”, for allowable 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.18.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.19.2.21. NdbTransaction::scanIndex()

Description.  This method is used to perform an index scan of a table, using NdbRecord. The scan may optionally be ordered.

Signature.  

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
    )

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 — thatis, they need not remain valid until execute() time (unlike the NdbRecord pointers).

Parameters.  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.15.1.3, “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.18.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.  The current NdbIndexScanOperation, which can be used for error checking.