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

2.3.18.2. NdbScanOperation Methods

[+/-]

2.3.18.2.1. NdbScanOperation::readTuples()
2.3.18.2.2. NdbScanOperation::nextResult()
2.3.18.2.3. NdbScanOperation::close()
2.3.18.2.4. NdbScanOperation::lockCurrentTuple()
2.3.18.2.5. NdbScanOperation::updateCurrentTuple()
2.3.18.2.6. NdbScanOperation::deleteCurrentTuple()
2.3.18.2.7. NdbScanOperation::restart()
2.3.18.2.8. NdbScanOperation::getNdbTransaction()
2.3.18.2.9. NdbScanOperation::getPruned()

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. See Section 2.3.19.2.2, “NdbTransaction::getNdbScanOperation()”.

2.3.18.2.1. 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 four parameters, as shown here:

  • The lock mode; this is a LockMode value as described in Section 2.3.15.1.3, “The NdbOperation::LockMode Type”.

    Caution

    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 NdbIndexScanOperation::close() method is also affected by this deadlock, since all outstanding requests are serviced before the scan is actually closed.

    We are working to resolve this issue in a future release.

  • 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. (Bug#20252)

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

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

Signature.  

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.  This method takes 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.  Beginning with MySQL Cluster NDB 6.2.3, this method can also be called with the following 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:

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

2.3.18.2.3. NdbScanOperation::close()

Description.  Calling this method closes a scan.

Note

See Scans and 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 two parameters:

  • 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.18.2.4. NdbScanOperation::lockCurrentTuple()

Description.  This method locks the current tuple.

Signature.  

NdbOperation* lockCurrentTuple
    (
      void
    )

or 

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
    )

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 using the NdbRecord interface (see Section 2.3.25, “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.

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. (See Section 2.3.15, “The NdbOperation Class”.)

2.3.18.2.5. NdbScanOperation::updateCurrentTuple()

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

Signature.  

NdbOperation* updateCurrentTuple
    (
      void
    )

or 

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.  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 here:

  • 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. (See Section 2.3.15, “The NdbOperation Class”.)

2.3.18.2.6. NdbScanOperation::deleteCurrentTuple()

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

Signature.  

int deleteCurrentTuple
    (
      void
    )

or 

int deleteCurrentTuple
    (
      NdbTransaction* takeOverTransaction
    )

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





          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
          two parameters, as shown here:

          


    

  • 
                The takeover transaction
                (takeOverTrans, a pointer to
                an NdbTransaction object) to employ.
              
    • 

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




        


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







2.3.18.2.7. 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.18.2.8. NdbScanOperation::getNdbTransaction()


Description. 
          Gets the NdbTransaction object for this
          scan. 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. See
          Section 2.3.19, “The NdbTransaction Class”.
        







2.3.18.2.9. 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. 
          TRUE, if the scan is pruned to a single
          table partition.