TOTAL
 Totaliza registros pelo valor chave para um arquivo (.dbf)
------------------------------------------------------------------------------

 Sintaxe

     TOTAL ON <expChave> [FIELDS <idLista campos>] TO <xcArquivo>
        [<abrangência>] [WHILE <lCondiçao>] [FOR <lCondiçao>]

 Argumentos

     ON <expChave> define o grupo de registros que irao produzir um novo
     registro no arquivo destino.  Para que a totalizaçao seja precisa, o
     arquivo fonte deve ser classificado ou indexado nesta expressao.

     FIELDS <idLista campos> especifica a lista de campos a serem
     TOTALizados.  Se a claúsula FIELDS nao é especificada, campos numéricos
     nao sao totalizados.  Ao invés disso cada campo numérico no arquivo
     destino irá conter o primeiro registro que obedeça à expressao chave.

     TO <xcArquivo> é o nome do arquivo destino para onde serao copiados
     os registros totalizados.  Este argumento pode ser especificado
     literalmente ou como expressao caractere entre parênteses.  A menos que
     especificado, TOTAL assume a extensao (.dbf).

     <abrangência> é a porçao do arquivo corrente a ser TOTALizada.  O
     assumido é ALL (todos).

     WHILE <lCondiçao> especifica o conjunto de registros que obedecem à
     condiçao a partir do registro corrente até que a condiçao seja falsa.

     FOR <lCondiçao> especifica o conjunto condicional de registros a
     serem TOTALizados dentro da abrangência corrente.

 Descriçao

     TOTAL percorre sequencialmente o arquivo corrente totalizando pela
     chave especificada e copiando para o arquivo destino.  A estrutura do
     arquivo destino é idêntica à do arquivo fonte com exceçao dos campos
     memo, que nao sao copiados.

     TOTAL trabalha primeiro copiando a estrutura do arquivo corrente para
     <xcArquivo>, exceto campos memo.  Ele entao vai pesquisando
     sequencialmente o arquivo corrente dentro da faixa de registros
     especificada.  Quando um registro com chave única for encontrado, ele é
     copiado para o arquivo destino.  Os valores dos campos numéricos
     especificados em <idLista campos> a partir de sucessivos registros com
     a mesma chave sao adicionados a campos com os mesmos nomes de
     <xcArquivo>.  A TOTALizaçao ocorre até que um registro com uma chave
     diferente é encontrado.  O processo é entao repetido para este
     registro.

     Já que TOTAL atravessa o arquivo fonte sequencialmente, ele deve ser
     indexado ou classificado por <expChave> para que a totalizaçao seja
     correta.

     Para TOTALizar campos numéricos, os campos numéricos devem ser grandes
     o suficiente para conter o maior total possível para campo numérico.
     Do contrário, um erro em tempo de execuçao é gerado.

 Notas

       Registros marcados: Registros marcados sao totalizados a
        menos que SET DELETED esteja ON.  O estado de marcado, entretanto,
        nao é copiado para o arquivo destino.

 Exemplos

     Neste exemplo, um arquivo de dados é TOTALizado pela expressao chave de
     um índice de controle usando uma macro expressao.  Quando a macro
     expressao é encontrada, a expressao é avaliada e o string é substituído
     pelo o argumento TOTAL ON <expChave>:

     USE Sales INDEX Branch NEW
     TOTAL ON &(INDEXKEY(0)) FIELDS Branch, Amount TO Summary

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

See Also: AVERAGE INDEX SORT SUM