Function DbRecall() | Xbase++

Removes deletion flag for a record (recalls the record).

DbRecall() --> NIL

The return value of DbRecall() is always NIL.

The database function DbRecall() removes the mark indicating record deletion on the current record, if the deletion flag is set. When the function is used without the alias operator, the function removes the "deleted" flag of the current record in the current work area.

The command RECALL can be used instead of DbRecall(). RECALL is effective only in the current work area.

When multi-user file access is allowed, a record must be locked with RLock() before calling the function DbRecall().

DbRecall()

// The example shows various file operations which illustrate 
// the effect of the "deleted" mark of a record. 

PROCEDURE Main 
   USE Customer NEW 

   SET DELETED ON              // filter out records 
                               // with deletion flags 
   Customer->( DbGoTop() ) 

   ? Customer->( RecNo() )     // result: 1 
   ? Customer->LastName        // result: King 

   Customer->( DbDelete() )    // set deletion flag 
   ? Customer->( Deleted() )   // result: .T. 

   Customer->( DbGoTop() ) 
   ? Customer->( RecNo() )     // result: 2 
   ? Customer->LastName        // result: Fisher 
   ? Customer->( Deleted() )   // result: .F. 

   SET DELETED OFF 
   Customer->( DbGoTop() ) 

   ? Customer->( RecNo() )     // result: 1 
   ? Customer->LastName        // result: King 
   ? Customer->( Deleted() )   // result: .T. 

   Customer->( DbRecall() ) 
   ? Customer->( Deleted() )   // result: .F. 

   CLOSE Customer 
RETURN

Record recycling with DbRecall()


// In the example, an index expression is used which places all 
// Deleted() records at the logical end of the file. When a new 
// record is added to the file, the UDF MyAppend() first tests 
// whether the last record is marked as deleted. If it is, the 
// deletion flag is removed and the record is filled with empty 
// values. Using this technique, the time-consuming PACK command 
// can be avoided. 

PROCEDURE Main 
   USE Customer NEW EXCLUSIVE 
   INDEX ON IIf(Deleted(),Chr(255)+SubStr(NAME,2),NAME) ; 
         TO CustA 
   SET INDEX TO CustA 
   SET DELETED ON 

   ? LastRec()             // result: 100 
   DbAppend() 

   ? LastRec()             // result: 101 

   DbDelete() 
   ? LastRec()             // result: 101 

   MyAppend() 
   ? LastRec()             // result: 101 

   CLOSE Customer 
RETURN 

PROCEDURE MyAppend() 
   LOCAL aData, nIndex 

   DbGoto( LastRec() )      // go to the last physical 
                            // record 
   IF Deleted()             // is deletion flag set ? 
      nIndex := IndexOrd()  // save current index 
      DbSetOrder(0)         // deactivate controlling index 

      DbGoto( LastRec() )   // copy empty values from 
      DbSkip()              // the "ghost-record" 
                            // into an array 
      aData := Array( FCount() ) 
      AEval( aData, {|x,i| aData[i]:=FieldGet(i)} ) 

      DbGoto( LastRec() )   // back to the Deleted() record 
      DbRecall()            // remove deletion flag 
                            // copy empty data into record 
      AEval( aData, {|x,i| FieldPut(i,x)} ) 
      DbSetOrder(nIndex)    // reactivate the controlling index 
      DbGoto( LastRec() )   // update index files 
   ELSE                     // no record with deletion flag 
      DbAppend()            // is available, add a new record 
   ENDIF 

RETURN

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.

Function DbRecall() Foundation