DBEVAL()
 Avalia um bloco de código para cada registro que atenda a uma abrangência e
 a uma condiçao
------------------------------------------------------------------------------

 Sintaxe

     DBEVAL(<bBloco>,
         [<bCondiçaoFor>],
         [<bCondiçaoWhile>],
         [<nQuantosRegistros>],
         [<nRegistro>],
         [<lRegRestantes>]) --> NIL

 Argumentos

     <bBloco> é o bloco de código a ser executado para cada registro
     processado.

     <bCondiçaoFor> é uma condiçao opcional especificada como sendo um
     bloco de código que é avaliada para cada registro na abrangência.  Ela
     provê a mesma funcionalidade que a cláusula FOR dos comandos de
     processamento de registros.

     <bCondiçaoWhile> é uma condiçao opcional especificada como sendo um
     bloco de código que é avaliado para cada registro a partir do registro
     corrente até que a condiçao retorne (.F.).  Ela provê a mesma
     funcionalidade que a cláusula WHILE dos comandos de processamento de
     registros.

     <nQuantosRegistros> é um número opcional que define quantos
     registros serao processados partindo do registro corrente.  Tem o mesmo
     efeito que a cláusula NEXT dos comandos de manipulaçao de registros.

     <nRegistro> é um número de registro opcional e se refere ao
     registro a processar.  Caso este argumento seja mencionado, <bBloco>
     será avaliado para o registro especifico.  Este argumento é igual à
     cláusula RECORD de alguns comandos que manipulam registros.

     <lRegRestantes> é um valor lógico opcional que determina se a
     abrangência da DBEVAL() envolverá todos os registros, ou se inicia a
     partir do registro corrente até o final do arquivo.  Este argumento
     corresponde às cláusulas REST e ALL de comandos que manipulam
     registros.  Caso seja especificado verdadeiro (.T.), a abrangência
     adotada é REST; caso contrário, a abrangência assume todos os registros
     (ALL).  Se o argumento <lRegRestantes> nao é mencionado a abrangência
     padrao assumida é para todos os registros (ALL).

 Retorno

     DBEVAL() sempre retorna NIL.

 Descriçao

     DBEVAL() é uma funçao que opera em arquivos de dados que avalia um
     bloco de código simples para o registro presente na área corrente que
     atenda à abrangência especificada e/ou condiçao.  A cada repetiçao,
     DBEVAL() avalia o bloco especificado.  Todos os registros dentro da
     abrangência ou que atendam a condiçao sao processados até que o final
     do arquivo seja alcançado.

     Por padrao, DBEVAL() opera sobre a área de trabalho corrente.  Esta
     funçao pode ser operada em uma área de trabalho nao selecionada
     especificando-a dentro de uma expressao com alias.

     DBEVAL() é similar à AEVAL() que aplica um bloco a cada elemento do
     vetor.  Tal como AEVAL(), DBEVAL() pode ser usada como uma funçao
     primitiva para a construçao de comandos definidos pelo usuário que
     processam arquivos de dados.  De fato, muitos dos comandos de
     processamento de arquivos de dados padrao do Clipper 5.0 sao criados
     utilizando DBEVAL().

     Consulte a seçao de Blocos de Código no capítulo Conceitos Básicos para
     maiores informaçoes a respeito da sintaxe e teoria dos blocos de
     código; consulte também a seçao Sistema de Arquivos de Dados no
     capítulo Conceitos Básicos para informaçoes sobre as abrangências e as
     condiçoes aplicadas a registros; e veja o arquivo header padrao Clipper
     5.0, STD.CH, encontrado no \CLIPPER5\INCLUDE para exemplos sobre
     definiçoes de comandos de arquivos de dados do Clipper que utilizam
     DBEVAL().

 Exemplos

     O exemplo seguinte usa a funçao DBEVAL() para implementar Count(), uma
     funçao definida pelo usuário que conta o número de registros em uma
     área de trabalho que atendam à abrangência especificada.  A abrangência
     é passada na forma de vetor para Count().  Para tornar o exemplo mais
     interessante, há um comando definido pelo usuário para criar o vetor
     chamado scope, desta forma permitindo a você especificar a abrangência
     de uma forma mais familiar.  Além disso, há uma série de constantes
     manifestas que definem os atributos do objeto scope:

     // Definiçao do comando Scope
     #command CREATE SCOPE <aScope> [FOR <for>] [WHILE <while>];
        [NEXT <next>] [RECORD <rec>] [<rest:REST>] [ALL];
     =>;
        <aScope> := { <{for}>, <{while}>, <next>, <rec>, <.rest.> }
     //
     // Constantes de atributos do Scope
     #define FOR_COND    1
     #define WHILE_COND  2
     #define NEXT_SCOPE  3
     #define REC_SCOPE   4
     #define REST_SCOPE  5
     //
     // Cria a abrangência e conta os registros usando-o
     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

 Arquivos:  Biblioteca CLIPPER.LIB
 To download this example - click here.

See Also: AEVAL() EVAL()