Documentation Home
MySQL NDB Cluster API Developer Guide
Download this Manual

2.3.29.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 NDB 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
    )

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 using execute(NdbTransaction::NoCommit). When nextResult(false) returns 2, you should normally 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, you can call nextResult(true) to have more records fetched and cached 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).  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.5.4, “NDB API Basic Scanning Example”.