DBEVAL()
 Evaluate a code block for each record matching a scope and condition
------------------------------------------------------------------------------
 Syntax

     DBEVAL(<bBlock>,
        [<bForCondition>],
        [<bWhileCondition>],
        [<nNextRecords>],
        [<nRecord>],
        [<lRest>]) --> NIL

 Arguments

     <bBlock> is a code block to execute for each record processed.

     <bForCondition> is an optional condition specified as a code block
     that is evaluated for each record in the scope.  It provides the same
     functionality as the FOR clause of record processing commands.

     <bWhileCondition> is an optional condition specified as a code block
     that is evaluated for each record from the current record until the
     condition returns false (.F.).  It provides the same functionality as
     the WHILE clause of record processing commands.

     <nNextRecords> is an optional number that specifies the number of
     records to process starting with the current record.  It is the same as
     the NEXT clause.

     <nRecord> is an optional record number to process.  If this argument
     is specified, <bBlock> will be evaluated for the specified record.  This
     argument is the same as the RECORD clause.

     <lRest> is an optional logical value that determines whether the
     scope of DBEVAL() is all records, or, starting with the current record,
     all records to the end of file.  This argument corresponds to the REST
     and ALL clauses of record processing commands.  If true (.T.) , the
     scope is REST; otherwise, the scope is ALL records.  If <lRest> is not
     specified the scope defaults to ALL.

 Returns

     DBEVAL() always returns NIL.

 Description

     DBEVAL() is a database function that evaluates a single block for each
     record within the current work area that matches a specified scope
     and/or condition.  On each iteration, DBEVAL() evaluates the specified
     block.  All records within the scope or matching the condition are
     processed until the end of file is reached.

     By default, DBEVAL() operates on the currently selected work area.  It
     will operate on an unselected work area if you specify it as part of an
     aliased expression.

     DBEVAL() is similar to AEVAL() which applies a block to each element in
     an array.  Like AEVAL(), DBEVAL() can be used as a primitive for the
     construction of user-defined commands that process database files.  In
     fact, many of the standard Clipper database processing commands are
     created using DBEVAL().

     Refer to the Code Blocks section in the "Basic Concepts" chapter of the
     Programming and Utilities Guide for more information on the syntax and
     theory of code blocks; and refer also to the Database System section in
     the same chapter for information on record scoping and conditions.  Also
     refer to the Clipper standard header file, Std.ch, found in
     \CLIP53\INCLUDE for examples of Clipper database command definitions
     that use DBEVAL().

 Examples

     .  This example uses DBEVAL() to implement Count(), a user-
        defined function that counts the number of records in a work area
        matching a specified scope.  The scope is passed as an array to
        Count().  To make the example more interesting, there is a user-
        defined command to create the scope array, thereby allowing you to
        specify the scope in a familiar form.  Additionally, there is a set
        of manifest constants that define the attributes of the scope object.

        // Scope command definition
        #command CREATE SCOPE <aScope> [FOR <for>] ;
           [WHILE <while>] [NEXT <next>] [RECORD <rec>] ;
           [<rest:REST>] [ALL];
        =>;
           <aScope> := { <{for}>, <{while}>, <next>, ;
              <rec>, <.rest.> }
        //

        // Scope attribute constants
        #define FOR_COND      1
        #define WHILE_COND    2
        #define NEXT_SCOPE    3
        #define REC_SCOPE     4
        #define REST_SCOPE    5
        //
        // Create a scope and count records using it
        LOCAL mySet, myCount
        USE Customer NEW
        CREATE SCOPE mySet FOR Customer = "Smith" WHILE ;
                  Zip > "90000"
        myCount := Count( mySet )
        RETURN

        FUNCTION Count( aScope )
           LOCAL nCount := 0
           DBEVAL( {|| nCount++},;
              aScope[ FOR_COND ],;
              aScope[ WHILE_COND ],;
              aScope[ NEXT_SCOPE ],;
              aScope[ REC_SCOPE ],;
              aScope[ REST_SCOPE ];
           )
           RETURN nCount

 Files   Library is CLIPPER.LIB

See Also: AEVAL() EVAL()