$FUNCNAME$
  DBEVAL()
$CATEGORY$
  DATABASE
$SUMMARY$
   Evaluate a code block for each record matching a scope and condition
$LANG_RU$
        ,     
$SYNTAX$
     DBEVAL(<bBlock>,[<bForCondition>],[<bWhileCondition>],[<nNextRecords>],
	[<nRecord>],[<lRest>]) --> NIL
$LANG_RU$
     DBEVAL(< >,[<FOR-.>],[<WHILE-. >],
	  [<- >],[< >],[<>]) --> 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.


$LANG_RU$

     < > -   ,    
     .

     <FOR-.> -   ,   
     ,       .   
      ,    FOR    .

     <WHILE-. > -   ,  
      ,     ,   
        ,      "" (.F.). 
        ,    WHILE   
     .

     <- > -   , 
      ,   ,   .
         NEXT.

     < > -   ,  
      .    ,  
         .   
      RECORD.

     <> -    ,
     ,    , 
     DBEVAL(),        , 
         .   
      REST  ALL    .  
      "" (.T.),     REST,
        - ALL (  ).     ,
          .


$RETURNS$

     DBEVAL() always returns NIL.


$LANG_RU$

     DBEVAL()   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 xClipper 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 xClipper standard header file, std.ch, found in
     \include for examples of xClipper database command definitions
     that use DBEVAL().


$LANG_RU$

     DBEVAL() -      ,   
       ,       ()
           .  
      DBEVAL()   .  ,  
        ,    , 
         .    DBEVAL()  
      ()  .     DBEVAL()
         .    
     ,  . DBEVAL()   
     AEVAL(),     .   , 
     AEVAL(), DBEVAL()       
       ,    .
        xClipper,   
     ,    DBEVAL().

        " "   " " 
              .
         "  "   "
     "        
        .    
     std.ch,    \include, 
            
      xClipper,    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


$LANG_RU$

         DBEVAL()    
        COUNT(),    
             .   
         COUNT()   .  ,  
           ,    
       ,   ,   , 
              
       .       , 
          :

       //  
       //
       #command CREATE SCOPE <aScope> [FOR<for>] [WHILE<while>];
	  [NEXT<next>] [RECORD<rec>] [<rest:REST>] [ALL];
       =>;
	  aScope := { <{for}>, <{while}>, <next>, <rec>, <.rest.> }
       //
       //  
       //
       #define FOR_COND    1
       #define WHILE_COND  2
       #define NEXT_SCOPE  3
       #define REC_SCOPE   4
       #define REST_SCOPE  5
       //
       //         
       //
       LOCAL mySet, myCount
       USE Customer NEW
       CREATE SCOPE mySet FOR Customer = "Smith" WHILE Zip > "90000"
       myCount = Count( mySet )
       RETURN

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


$SEEALSO$
  AEVAL(),EVAL()
$END$
