Skip navigation links
2.3.28 The NdbTransaction Class »
Section Navigation      [Toggle]

2.3.27.2. NdbScanOperation Methods

2.3.27.2.1. NdbScanOperation::close()
2.3.27.2.2. NdbScanOperation::deleteCurrentTuple()
2.3.27.2.3. NdbScanOperation::getNdbTransaction()
2.3.27.2.4. NdbScanOperation::getPruned()
2.3.27.2.5. NdbScanOperation::lockCurrentTuple()
2.3.27.2.6. NdbScanOperation::nextResult()
2.3.27.2.7. NdbScanOperation::readTuples()
2.3.27.2.8. NdbScanOperation::restart()
2.3.27.2.9. NdbScanOperation::updateCurrentTuple()

Abstract

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

Note

This class has no public constructor. To create an instance of NdbScanOperation, it is necessary to use the NdbTransaction::getNdbScanOperation() method.

2.3.27.2.1. NdbScanOperation::close()

Description.  Calling this method closes a scan.

Note

See Scans with exclusive locks, for information about multiple threads attempting to perform the same scan with an exclusive lock and how this can affect closing the scans.

Signature.  

void close
    (
      bool forceSend = false,
      bool releaseOp = false
    )

Parameters.  This method takes the two parameters listed here:

  • forceSend defaults to false; call close() with this parameter set to true in order to force transactions to be sent.

  • releaseOp also defaults to false; set to true in order to release the operation.

Return value.  None.

2.3.27.2.2. NdbScanOperation::deleteCurrentTuple()

Description.  This method is used to delete the current tuple.

Signature.  Originally (prior to the introduction of NdbRecord), this method could be invoked with a single optional parameter, in either of the ways shown here: 

int deleteCurrentTuple
    (
      void
    )


int deleteCurrentTuple
    (
      NdbTransaction* takeOverTransaction
    )

Beginning with MySQL Cluster NDB 6.2.3, this method's signature when performing NdbRecord-style scans is shown here: 

const NdbOperation* deleteCurrentTuple
    (
      NdbTransaction* takeOverTrans,
      const NdbRecord* record,
      char* row = 0,
      const unsigned char* mask = 0,
      const NdbOperation::OperationOptions* opts = 0,
      Uint32 sizeOfOpts = 0
    )

For more information, see Section 2.3.25, “The NdbRecord Interface”.

Parameters.  This method takes a single, optional parameter—the transaction that should perform the lock. If this is omitted, the transaction is the current one.

Parameters when using NdbRecord.  When used with the NdbRecord interface (beginning with MySQL Cluster NDB 6.2.3), this method takes the parameters listed here:

  • The transaction (takeOverTrans) that should perform the lock; when using NdbRecord with scans, this parameter is not optional.

  • The NdbRecord referenced by the scan. This record value is required, even if no records are being read.

  • The row from which to read. Set this to NULL if no read is to occur.

  • The mask pointer is optional. If it is present, then only columns for which the corresponding bit in the mask is set are retrieved by the scan.

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

  • If options are specified, their length (sizeOfOpts) must be specified as well.

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

2.3.27.2.3. NdbScanOperation::getNdbTransaction()

Description.  Gets the NdbTransaction object for this scan. This method is available beginning with MySQL Cluster NDB 6.2.17 and MySQL Cluster NDB 6.3.19.

Signature.  

NdbTransaction* getNdbTransaction
    (
      void
    ) const

Parameters.  None.

Return value.  A pointer to an NdbTransaction object.

2.3.27.2.4. NdbScanOperation::getPruned()

Description.  This method is used to determine whether or not a given scan operation has been pruned to a single partition. For scans defined using NdbRecord, this method can be called before or after the scan is executed. For scans not defined using NdbRecord, getPruned() is valid only after the scan has been executed.

Signature.  

bool getPruned
    (
      void
    ) const

Parameters.  None.

Return value.  Returns true, if the scan is pruned to a single table partition.

2.3.27.2.5. NdbScanOperation::lockCurrentTuple()

Description.  This method locks the current tuple.

Signature.  In MySQL 5.1 and later, this method can be called with an optional single parameter, in either of the two ways shown here: 

NdbOperation* lockCurrentTuple
    (
      void
    )

NdbOperation* lockCurrentTuple
    (
      NdbTransaction* lockTrans
    )

Beginning with MySQL Cluster NDB 6.2.3, the following signature is also supported for this method, when using NdbRecord: 

NdbOperation *lockCurrentTuple
    (
      NdbTransaction* takeOverTrans,
      const NdbRecord* record,
      char* row = 0,
      const unsigned char* mask = 0
    )

In MySQL Cluster NDB 7.0 and later, this method also supports specifying one or more OperationOptions (also when using NdbRecord): 

NdbOperation *lockCurrentTuple
    (
      NdbTransaction* takeOverTrans,
      const NdbRecord* record,
      char* row = 0,
      const unsigned char* mask = 0,
      const NdbOperation::OperationOptions* opts = 0,
      Uint32 sizeOfOptions = 0
    )

Parameters (old style).  This method takes a single, optional parameter—the transaction that should perform the lock. If this is omitted, the transaction is the current one.

Parameters (when using NdbRecord).  When using the NdbRecord interface, this method takes these parameters, as described in the following list:

  • The transaction (takeOverTrans) that should perform the lock; when using NdbRecord with scans, this parameter is not optional.

  • The NdbRecord referenced by the scan. This is required, even if no records are being read.

  • The row from which to read. Set this to NULL if no read is to occur.

  • The mask pointer is optional. If it is present, then only columns for which the corresponding bit in the mask is set are retrieved by the scan.

  • (MySQL Cluster NDB 7.0 and later:) The opts argument can take on any of the following OperationOptions values: OO_ABORTOPTION, OO_GETVALUE, and OO_ANYVALUE.

  • (MySQL Cluster NDB 7.0 and later:) If options are specified, their length (sizeOfOptions) must be specified as well.

Important

Calling an NdbRecord scan lock takeover on an NdbRecAttr-style scan is not valid, nor is calling an NdbRecAttr-style scan lock takeover on an NdbRecord-style scan.

Return value.  This method returns a pointer to an NdbOperation object, or NULL.

2.3.27.2.6. NdbScanOperation::nextResult()

Description.  This method is used to fetch the next tuple in a scan transaction. Following each call to nextResult(), the buffers and NdbRecAttr objects defined in NdbOperation::getValue() are updated with values from the scanned tuple.

Prior to MySQL Cluster NDB 6.3.49, 7.0.34, 7.1.23, and 7.2.7: When an NDB API application called this method again after the previous call had returned end-of-file (return code 1), a transaction object was leaked, and NDB returned -1 (undefined). (Bug #11748194) Later versions: When nextResult() is executed following end-of-file, NDB returns error code 4210 (Ndb sent more info than length specified) and the extra transaction object is freed by returning it to the idle list for the right TC node.

Signature.  This method can be invoked in one of two ways. The first of these, shown here, is available beginning in MySQL 5.1: 

int nextResult
    (
      bool fetchAllowed = true,
      bool forceSend = false
    )

Beginning with MySQL Cluster NDB 6.2.3, it is also possible to use this method as shown here: 

int nextResult
    (
      const char*& outRow,
      bool fetchAllowed = true,
      bool forceSend = false
    )

Parameters (2-parameter version).  This method takes the following two parameters:

  • Normally, the NDB API contacts the NDB kernel for more tuples whenever it is necessary; setting fetchAllowed to false keeps this from happening.

    Disabling fetchAllowed by setting it to false forces NDB to process any records it already has in its caches. When there are no more cached records it returns 2. You must then call nextResult() with fetchAllowed equal to true in order to contact NDB for more records.

    While nextResult(false) returns 0, you should transfer the record to another transaction. When nextResult(false) returns 2, you must execute and commit the other transaction. This causes any locks to be transferred to the other transaction, updates or deletes to be made, and then, the locks to be released. Following this, call nextResult(true)—this fetches more records and caches them in the NDB API.

    Note

    If you do not transfer the records to another transaction, the locks on those records will be released the next time that the NDB Kernel is contacted for more records.

    Disabling fetchAllowed can be useful when you want to update or delete all of the records obtained in a given transaction, as doing so saves time and speeds up updates or deletes of scanned records.

  • forceSend defaults to false, and can normally be omitted. However, setting this parameter to true means that transactions are sent immediately. See Section 1.3.4, “The Adaptive Send Algorithm”, for more information.

Parameters (3-parameter version).  Beginning with MySQL Cluster NDB 6.2.3, this method can also be called with the following three parameters:

  • Calling nextResult() sets a pointer to the next row in outRow (if returning 0). This pointer is valid (only) until the next call to nextResult() when fetchAllowed is true. The NdbRecord object defining the row format must be specified beforehand using NdbTransaction::scanTable() (or NdbTransaction::scanIndex().

  • When false, fetchAllowed forces NDB to process any records it already has in its caches. See the description for this parameter in the previous Parameters subsection for more details.

  • Setting forceSend to true means that transactions are sent immediately, as described in the previous Parameters subsection, as well as in Section 1.3.4, “The Adaptive Send Algorithm”.

Return value.  This method returns one of the following 4 integer values, interpreted as shown in the following list:

  • -1: Indicates that an error has occurred.

  • 0: Another tuple has been received.

  • 1: There are no more tuples to scan.

  • 2: There are no more cached records (invoke nextResult(true) to fetch more records).

Example.  See Section 2.4.4, “Basic Scanning Example”.

2.3.27.2.7. NdbScanOperation::readTuples()

Description.  This method is used to perform a scan.

Signature.  

virtual int readTuples
    (
      LockMode mode = LM_Read,
      Uint32   flags = 0,
      Uint32   parallel = 0,
      Uint32   batch = 0
    )

Parameters.  This method takes the four parameters listed here:

  • The lock mode; this is a LockMode value.

    Scans with exclusive locks.  When scanning with an exclusive lock, extra care must be taken due to the fact that, if two threads perform this scan simultaneously over the same range, then there is a significant probability of causing a deadlock. The likelihood of a deadlock is increased if the scan is also ordered (that is, using SF_OrderBy or SF_Descending).

    The NdbScanOperation::close() method is also affected by this deadlock, since all outstanding requests are serviced before the scan is actually closed.

  • One or more ScanFlag values. Multiple values are OR'ed together

  • The number of fragments to scan in parallel; use 0 to require that the maximum possible number be used.

  • The batch parameter specifies how many records will be returned to the client from the server by the next NdbScanOperation::nextResult(true) method call. Use 0 to specify the maximum automatically.

    Note

    This parameter was ignored prior to MySQL 5.1.12, and the maximum was used (see Bug #20252).

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

2.3.27.2.8. NdbScanOperation::restart()

Description.  Use this method to restart a scan without changing any of its getValue() calls or search conditions.

Signature.  

int restart
    (
      bool forceSend = false
    )

Parameters.  Call this method with forceSend set to true in order to force the transaction to be sent.

Return value.  0 on success; -1 on failure.

2.3.27.2.9. NdbScanOperation::updateCurrentTuple()

Description.  This method is used to update the current tuple.

Signature.  Originally, this method could be called with a single. optional parameter, in either of the ways shown here: 

NdbOperation* updateCurrentTuple
    (
      void
    )


NdbOperation* updateCurrentTuple
    (
      NdbTransaction* updateTrans
    )

Beginning with MySQL Cluster NDB 6.2.3, it is also possible to employ this method, when using NdbRecord with scans, as shown here: 

NdbOperation* updateCurrentTuple
    (
      NdbTransaction*      takeOverTrans,
      const NdbRecord*     record,
      const char*          row,
      const unsigned char* mask = 0
    )

See Section 2.3.25, “The NdbRecord Interface”, for more information.

Parameters (original).  This method takes a single, optional parameter—the transaction that should perform the lock. If this is omitted, the transaction is the current one.

Parameters (when using NdbRecord).  When using the NdbRecord interface (beginning with MySQL Cluster NDB 6.2.3), this method takes the following parameters, as described in the following list:

  • The takeover transaction (takeOverTrans).

  • The record (NdbRecord object) referencing the column used for the scan.

  • The row to read from. If no attributes are to be read, set this equal to NULL.

  • The mask pointer is optional. If it is present, then only columns for which the corresponding bit in the mask is set are retrieved by the scan.

Return value.  This method returns an NdbOperation object or NULL.

Copyright © 2003, 2013, Oracle and/or its affiliates. All rights reserved. Legal Notices