Xbase++ - Function DbEval()

Evaluates a code block for each record in a work area.

DbEval( <bBlock>, ;
       [<bForCondition>], ;
       [<bWhileCondition>], ;
       [<nCount>], ;
       [<xRecordID>], ;
       [<lRest>]  ) --> NIL

<bBlock> contains a code block which is executed for each data record.

<bForCondition> is an optional code block containing a condition as a logical expression. <bBlock> is only executed for the data records where <bForCondition> returns the value .T. (true).

<bWhileCondition> is an optional code block containing a condition as a logical expression. DbEval() terminates as soon as <bWhileCondition> returns the value .F. (false).

The optional argument <nCount> specifies the number of records for which <bBlock> is evaluated beginning with the current data record.

The optional argument <xRecordID> specifies a record ID (for DBF files it is the record number). If <xRecordID> is specified, the evaluation of <bBlock> begins with the specified record.

<lRest>

The logical value <lRest> optionally specifies whether <bBlock> is evaluated for all records of a work area ( <lRest>==.F.), or only for the records from the current to the last record ( <lRest>==.T.). The default value is .F. (false), indicating that <bBlock> is evaluated for all data records.

The return value of DbEval() is always NIL.

The database function DbEval() evaluates a code block and increments the record pointer of a work area after each execution of the code block. When the function is used without the alias operator, it moves the record pointer in the current work area. By default, DbEval() begins with the first logical record and evaluates the code block <bBlock> for each record until the last logical record is reached. The number of records for which the code block is evaluated can be influenced by the optional arguments.

By specifying code blocks for <bForCondition> or <bWhileCondition>, a logical condition can be defined which must return the value .T. (true) for the code block <bBlock> to be evaluated. The <bForCondition> code block is evaluated for all data records. When it returns .T. (true), <bBlock> is executed. When <bWhileCondition> is specified, <bBlock> is only executed until <bWhileCondition> returns .F. (false), causing DbEval() to terminate.

Alternatively the number of records can be explicitly determined with <nCount> or <lRest>. Specifying <xRecordID> positions the record pointer on this record and the code block <bBlock> is evaluated for this and following records.

DbEval() passes no arguments to the code blocks.

DbEval()

// The example shows DbEval() with a FOR condition. All customers 
// in a customer file having the name "Smith" are listed. 

PROCEDURE Main 
   USE Customer NEW 

   DbEval( {|| QOut(LastName,FirstName) }    , ; // <bBlock>, 
           {|| "SMITH" $ Upper(LastName) } )     // <bForCondition> 
   USE 
RETURN

Implementation of file commands with DbEval()


// The example shows a command based on DbEval() which calls 
// DbDelete() from a code block. Many other commands using 
// DbEval() can be found in STD.CH. 

#command   DELETE ; 
    [   FOR <for>] ; 
    [ WHILE <whl>] ; 
    [  NEXT <nxt>] ; 
    [RECORD <rcd>] ; 
    [ <rst: REST>] ; 
    [ ALL ] ; 
=>  dbEval( {|| dbDelete()}, ; 
           <{for}>, <{whl}>, <nxt>, <rcd>, <.rst.>)

DbEval() in a user-defined function


// In the example, a UDF is illustrated in which the RecNo() 
// of all records fulfilling a condition are written 
// into an array with DbEval(). The example lists all customers 
// from a customer file which have not yet paid an invoice. 
PROCEDURE Main 
   LOCAL aRecno 

   USE Customer ALIAS Cust NEW EXCLUSIVE 
   INDEX ON CustNo TO CustNo 
   SET INDEX TO CustNo 

   USE Invoice ALIAS Inv NEW 
                                   // get RecNo(), for PAYMENT=0 
   aRecno := Inv->( CollectRecID( {|| Payment == 0} ) ) 

                                   // output customer name 
   AEval( aRecno, {|n| Inv->( DbGoto(n) ), ; 
                       Cust->( DbSeek(Inv->CustNo) ), ; 
                       Cust->( QOut(LastName,FirstName) ); 
                  }; 
        ) 

   CLOSE Cust 
   CLOSE Inv 

RETURN 

FUNCTION CollectRecID( bFor, bWhile, nCount, lRest ) 
   LOCAL aArray := {} 
   IF PCount() > 0 
      DbEval( {|| AAdd( aArray, RecNo() ) } , ; 
               bFor, bWhile, nCount, , lRest  ) 
   ENDIF 
RETURN aArray

Function DbEval() Foundation