ndb - Update documentation wrt scans

ndb/include/ndbapi/NdbIndexScanOperation.hpp

@@ -34,16 +34,15 @@ class NdbIndexScanOperation : public NdbScanOperation {
 
 public:
   /**
-   * readTuples returns a NdbResultSet where tuples are stored.
-   * Tuples are not stored in NdbResultSet until execute(NoCommit) 
-   * has been executed and nextResult has been called.
+   * readTuples using ordered index
    * 
-   * @param parallel  Scan parallelism
+   * @param lock_mode Lock mode
    * @param batch     No of rows to fetch from each fragment at a time
-   * @param LockMode  Scan lock handling   
+   * @param parallel  No of fragments to scan in parallel
    * @param order_by  Order result set in index order
-   * @param order_desc  Order descending, ignored unless order_by
-   * @returns NdbResultSet.
+   * @param order_desc Order descending, ignored unless order_by
+   * @param read_range_no Enable reading of range no using @ref get_range_no
+   * @returns 0 for success and -1 for failure
    * @see NdbScanOperation::readTuples
    */ 
   int readTuples(LockMode = LM_Read,
@@ -53,16 +52,6 @@ public:
                  bool order_desc = false,
 		 bool read_range_no = false);
   
-#ifndef DOXYGEN_SHOULD_SKIP_DEPRECATED
-  inline int readTuples(int parallell){
-    return readTuples(LM_Read, 0, parallell, false);
-  }
-  
-  inline int readTuplesExclusive(int parallell = 0){
-    return readTuples(LM_Exclusive, 0, parallell, false);
-  }
-#endif
-  
   /**
    * Type of ordered index key bound.  The values (0-4) will not change
    * and can be used explicitly (e.g. they could be computed).
@@ -134,7 +123,14 @@ public:
    */
   int get_range_no();
   
+  /**
+   * Is current scan sorted
+   */
   bool getSorted() const { return m_ordered; }
+
+  /**
+   * Is current scan sorted descending
+   */
   bool getDescending() const { return m_descending; }
 private:
   NdbIndexScanOperation(Ndb* aNdb);

ndb/include/ndbapi/NdbOperation.hpp

@@ -265,21 +265,6 @@ public:
   int  equal(Uint32 anAttrId, Int64 aValue);	
   int  equal(Uint32 anAttrId, Uint64 aValue);
 	
-  /**
-   * Generate a tuple id and set it as search argument.
-   *
-   * The Tuple id has NDB$TID as attribute name and 0 as attribute id.
-   *
-   * The generated tuple id is returned by the method.
-   * If zero is returned there is an error.
-   *
-   * This is mostly used for tables without any primary key 
-   * attributes.
-   * 
-   * @return    Generated tuple id if successful, otherwise 0.
-   */
-  Uint64       setTupleId();			
-
   /** @} *********************************************************************/
   /** 
    * @name Specify Attribute Actions for Operations
@@ -708,6 +693,7 @@ public:
 
   /** @} *********************************************************************/
 
+#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
   /**
    * Type of operation
    */
@@ -723,11 +709,16 @@ public:
     NotDefined2,                  ///< Internal for debugging
     NotDefined                    ///< Internal for debugging
   };
+#endif
 
+  /**
+   * Return lock mode for operation
+   */
   LockMode getLockMode() const { return theLockMode; }
-  void setAbortOption(Int8 ao) { m_abortOption = ao; }
 
 #ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
+  void setAbortOption(Int8 ao) { m_abortOption = ao; }
+  
   /**
    * Set/get distribution/partition key
    */
@@ -758,8 +749,10 @@ protected:
   void	next(NdbOperation*);		// Set next pointer		      
   NdbOperation*	    next();	        // Get next pointer		       
 public:
+#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
   const NdbOperation* next() const;
   const NdbRecAttr* getFirstRecAttr() const;
+#endif
 protected:
 
   enum OperationStatus

ndb/include/ndbapi/NdbRecAttr.hpp

@@ -245,7 +245,9 @@ public:
   ~NdbRecAttr();    
 
 public:
+#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
   const NdbRecAttr* next() const;
+#endif
 private:
   NdbRecAttr();
 

ndb/include/ndbapi/NdbScanOperation.hpp

@@ -37,16 +37,14 @@ class NdbScanOperation : public NdbOperation {
 
 public:
   /**
-   * readTuples returns a NdbResultSet where tuples are stored.
-   * Tuples are not stored in NdbResultSet until execute(NoCommit) 
-   * has been executed and nextResult has been called.
+   * readTuples
    * 
-   * @param parallel  Scan parallelism
+   * @param lock_mode Lock mode
    * @param batch No of rows to fetch from each fragment at a time
-   * @param LockMode  Scan lock handling   
+   * @param parallel No of fragments to scan in parallell
    * @note specifying 0 for batch and parallall means max performance
    */ 
-  int readTuples(LockMode = LM_Read, 
+  int readTuples(LockMode lock_mode = LM_Read, 
 		 Uint32 batch = 0, Uint32 parallel = 0);
   
 #ifndef DOXYGEN_SHOULD_SKIP_DEPRECATED
@@ -67,7 +65,7 @@ public:
   /**
    * Get the next tuple in a scan transaction. 
    * 
-   * After each call to NdbResult::nextResult
+   * After each call to nextResult
    * the buffers and NdbRecAttr objects defined in 
    * NdbOperation::getValue are updated with values 
    * from the scanned tuple. 
@@ -114,53 +112,31 @@ public:
   int nextResult(bool fetchAllowed = true, bool forceSend = false);
 
   /**
-   * Close result set (scan)
+   * Close scan
    */
   void close(bool forceSend = false);
 
   /**
-   * Restart
-   */
-  int restart(bool forceSend = false);
-  
-  /**
-   * Transfer scan operation to an updating transaction. Use this function 
-   * when a scan has found a record that you want to update. 
-   * 1. Start a new transaction.
-   * 2. Call the function takeOverForUpdate using your new transaction 
-   *    as parameter, all the properties of the found record will be copied 
-   *    to the new transaction.
-   * 3. When you execute the new transaction, the lock held by the scan will 
-   *    be transferred to the new transaction(it's taken over).
-   *
-   * @note You must have started the scan with openScanExclusive
-   *       to be able to update the found tuple.
+   * Update current tuple
    *
-   * @param updateTrans the update transaction connection.
    * @return an NdbOperation or NULL.
    */
   NdbOperation* updateCurrentTuple();
   NdbOperation*	updateCurrentTuple(NdbTransaction* updateTrans);
 
   /**
-   * Transfer scan operation to a deleting transaction. Use this function 
-   * when a scan has found a record that you want to delete. 
-   * 1. Start a new transaction.
-   * 2. Call the function takeOverForDelete using your new transaction 
-   *    as parameter, all the properties of the found record will be copied 
-   *    to the new transaction.
-   * 3. When you execute the new transaction, the lock held by the scan will 
-   *    be transferred to the new transaction(its taken over).
-   *
-   * @note You must have started the scan with openScanExclusive
-   *       to be able to delete the found tuple.
-   *
-   * @param deleteTrans the delete transaction connection.
-   * @return an NdbOperation or NULL.
+   * Delete current tuple
+   * @return 0 on success or -1 on failure
    */
   int deleteCurrentTuple();
   int deleteCurrentTuple(NdbTransaction* takeOverTransaction);
   
+  /**
+   * Restart scan with exactly the same
+   *   getValues and search conditions
+   */
+  int restart(bool forceSend = false);
+  
 protected:
   NdbScanOperation(Ndb* aNdb);
   virtual ~NdbScanOperation();

ndb/include/ndbapi/NdbTransaction.hpp

@@ -110,23 +110,6 @@ enum ExecType {
  * -# AbortOption::IgnoreError
  *    Continue execution of transaction even if operation fails
  *
- * NdbTransaction::execute can sometimes indicate an error 
- * (return with -1) while the error code on the NdbTransaction is 0. 
- * This is an indication that one of the operations found a record 
- * problem. The transaction is still ok and can continue as usual.
- * The NdbTransaction::execute returns -1 together with error code 
- * on NdbTransaction object equal to 0 always means that an 
- * operation was not successful but that the total transaction was OK. 
- * By checking error codes on the individual operations it is possible 
- * to find out which operation was not successful. 
- *
- * NdbTransaction::executeScan is used to setup a scan in the NDB kernel
- * after it has been defined.
- * NdbTransaction::nextScanResult is used to iterate through the 
- * scanned tuples. 
- * After each call to NdbTransaction::nextScanResult, the pointers
- * of NdbRecAttr objects defined in the NdbOperation::getValue 
- * operations are updated with the values of the new the scanned tuple. 
  */
 
 /* FUTURE IMPLEMENTATION:
@@ -376,6 +359,7 @@ public:
 #endif
   void close();
 
+#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
   /**
    * Restart transaction
    *
@@ -385,6 +369,7 @@ public:
    *   Note this method also releases completed operations
    */
   int restart();
+#endif
 
   /** @} *********************************************************************/
 
@@ -494,7 +479,7 @@ public:
    */
   const NdbOperation * getNextCompletedOperation(const NdbOperation * op)const;
 
-  
+#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
   const NdbOperation* getFirstDefinedOperation()const{return theFirstOpInList;}
   const NdbOperation* getLastDefinedOperation()const{return theLastOpInList;}
 
@@ -508,6 +493,7 @@ public:
    * ops are used (read, insert, update, delete).
    */
   int executePendingBlobOps(Uint8 flags = 0xFF);
+#endif
 
 private:						
   /**

ndb/src/ndbapi/NdbOperationSearch.cpp

@@ -300,32 +300,6 @@ NdbOperation::equal_impl(const NdbColumnImpl* tAttrInfo,
   return -1;
 }
 
-/******************************************************************************
- * Uint64 setTupleId( void )
- *
- * Return Value:  Return > 0: OK 
- *                Return 0 : setTupleId failed
- * Parameters:     
- * Remark:
- *****************************************************************************/
-Uint64
-NdbOperation::setTupleId()
-{
-  if (theStatus != OperationDefined)
-  {
-    return 0;
-  }
-  Uint64 tTupleId = theNdb->getTupleIdFromNdb(m_currentTable->m_tableId);
-  if (tTupleId == ~(Uint64)0){
-    setErrorCodeAbort(theNdb->theError.code);
-    return 0;
-  }
-  if (equal((Uint32)0, tTupleId) == -1)
-    return 0;
-
-  return tTupleId;
-}
-
 /******************************************************************************
  * int insertKEYINFO(const char* aValue, aStartPosition, 
  *                   anAttrSizeInWords, Uint32 anAttrBitsInLastWord);